CDR Build Module

From Yate Documentation
(Difference between revisions)
Jump to: navigation, search
(→‎Section [parameters])
 
(79 intermediate revisions by 3 users not shown)
Line 1: Line 1:
 +
Cdrbuild module is the module that builds live CDRs (call detail records) and creates a list for the calls that can be interrogated using telnet command [[CDR_Build_Module#Rmanager_command|status]].<br/>
 +
Cdrbuild module reads messages from other channel modules ([[H323_channel_module|h323chan]], [[SIP_Configuration_File|ysipchan]], [[IAX|iaxchan]]) about calls and builds the CDR.<br/>
 +
Then it sends the "[[call.cdr]]" message. This message is caught by different [[Modules#CDR modules|cdr modules]] that intend to write in different mediums ([[CDR_File_Module#Configuration|cdrfile]] writes in file, [[Register#Section_.5Bcall.cdr.5D|register]] that writes in database).<br/>
 +
Cdrbuild module generates CDR per channel not like [[CDRcombine_Module|cdrcombine]] that generates CDR per call.
  
−
Cdrbuild module is reading messages from other channel modules (h323chan, ysipchan, iaxchan) about calls and is building the CDR (call detail record), then is sending a message [[call.cdr]] for different cdr modules that intend to write in different mediums (file, database). The same message is used by channels that track channel or line states.
+
The cdrbuild module is loaded by default unless yate.conf file is used to load only specific modules in Yate.
  
−
The operation to be performed is indicated by the operation parameter that can be one of:
+
=== The configuration file===
 +
 
 +
The file used by this module for configuration is cdrbuild.conf. See below the sections and their description.
 +
 
 +
==== Section [general] ====
 +
* '''resolution''': keyword: Resolution for time representation: sec, msec or usec. The default value is:
 +
:resolution=msec
 +
* '''guardtime''': int: Time in ms to remember hungup channels to avoid race conditions. The default value is:
 +
:guardtime=5000
 +
* '''updates''': bool: Emit [[call.cdr]] message when call status has changed. The default value is:
 +
:updates=true
 +
* '''status''': bool: Emit [[call.cdr]] status messages for the call duration. The default value is:
 +
:status=false
 +
* '''status_interval''': int: The time interval in seconds to emit [[call.cdr]] status messages.
 +
'''Note:''' If status is set to false this interval will be ignored.
 +
: Default 60s. Minimum: 60s and Maximum 600s.
 +
:Default: status_interval=60
 +
* '''status_answer''': bool: Emit cdr status message immediately when the call is answered.
 +
: If set to false the first cdr status is sent after status_interval.
 +
:status_answer=true
 +
* '''ring_on_progress''': bool: Start ring timer when processing call.progress.
 +
:This parameter can be overridden in [[call.progress]] message by a 'ringing' parameter.The default value is:
 +
:ring_on_progress=no
 +
 
 +
====Section [parameters]====
 +
 
 +
In this section the possible values for the parameters that can be set, are true or false. This allows or disallows to overwrite their initial value.<br>
 +
There are 2 types of parameters in this section, the ones that can be overwritten and the ones that are handled internally and they can not be changed.<br> Also this is where you can add your own monitored parameters that will appear in "[[call.cdr]]".
 +
 +
:The following parameters are handled by default but you can overwrite them:
 +
:*'''billid'''=true ( will hold the billing ID. Billid is created from stitching the value of runid with the value cdrid )
 +
:*'''reason'''=true  ( a (mostly) human readable reason for this CDR )
 +
:*'''address'''=false ( channel endpoint address being involved in this CDR )
 +
:*'''caller'''=false ( caller party ID )
 +
:*'''called'''=false ( called party ID )
 +
:*'''calledfull'''=false ( full called party ID )
 +
:*'''username'''=false (  username of the caller party ID )
 +
 
 +
:The following parameters are handled internally and cannot be changed:
 +
:* '''time''': UNIX time and date when the CDR has been initially generated
 +
:* '''chan''': module and module-specific channel name being involved in this CDR
 +
:* '''operation''': one of initialize, update or finalize depending on the state of the CDR being signalled out
 +
:* '''cdrwrite''': true or false specify if the CDR will be written or not
 +
:* '''cdrtrack''': default true, if false the CDR will not be track
 +
:* '''cdrcreate''': default true, if set o false the CDR will not be build
 +
:* '''cdrid''': the channel ID for CDR
 +
:* '''runid''': running ID of Yate
 +
:* '''direction''': either of incoming or outgoing, Yate instance-wise (i.e. a call coming into the Yate instance emitting this CDR will have incoming here and a call being generated from the Yate instance in question will have outgoing here)
 +
:* '''status''': one of incoming, outgoing, ringing, answered or connected, reflecting the current state of the call referred to by this CDR
 +
:* '''duration''': end-to-end time (in seconds) of the call described in this CDR (i.e. from the moment the last digit was dialed on the calling side until the moment the line was hung up)
 +
:* '''billtime''': effective payable time (in seconds) of the call described in this CDR (i.e. from the moment the line was picked up on the called side until the moment the line was hung up)
 +
:* '''ringtime''': ringing time (in seconds) of the call described in this CDR (i.e. from the moment the routing decision has been taken and the remote endpoint alerted of the incoming call until the moment the line was picked up on the called side)
 +
 
 +
'''Note:''' in order for a parameter to appear in the call.cdr messages it has to be received in at least one of the messages handled by this module.
 +
For outgoing calls you should use the '''copyparams''' parameter of the [[call.execute]] message to copy parameters from incoming call leg to the outgoing one.
 +
 
 +
====Section [formatted-timers]====
 +
 
 +
This is a special section for time formatting.
 +
Formatting rules:
 +
YYYY | %Y -> Year (2012)
 +
YY | %y  -> Year, last two digits (00-99)
 +
MM | %m  -> Month as a decimal number (01-12)
 +
DD | %d  -> Day of the month (01-31)
 +
HH | %H  -> Hour in 24h format (00-23)
 +
mm | %M  -> Hour in 24h format (00-23)
 +
SS | %S  -> Second (00-60)
 +
              '''Note!''' the value is rounded.
 +
UTC      -> If present the time will represent the UTC time.
 +
              If is missing the time will represent local time zone.
 +
N*u      -> Milliseconds and Microseconds.
 +
              '''Note!''' The value is rounded.
 +
              EG: time: 1.123456
 +
                  s.u -> 1.1
 +
                  s.uu -> 1.12
 +
                  s.uuu -> 1.123
 +
                  s.uuuu -> 1.1234
 +
                  s.uuuuu -> 1.12346
 +
                  s.uuuuuu -> 1.123456
 +
Other formats may be used but they must correspond with C strftime method formats.
 +
'''Important!''' If duplicate formats are ignored!
 +
Eg: date : 09 14 2012
 +
            YYYY YY DD DD mm DD-> 2012 YY 14 DD 09 DD
 +
 +
 
 +
Append the call start time in [[call.cdr]] message with the given format.
 +
: Eg: '''call_start_time'''=YY/MM/DD HH:mm:SS.uuuuuu UTC
 +
 
 +
Append the call answer time in [[call.cdr]] message with the given format
 +
: Eg: '''call_answer_time'''=YY/MM/DD HH:mm:SS.uuuuuu UTC
 +
 +
Append the call hangup time in [[call.cdr]] message with the given format
 +
: Eg: '''call_hangup_time'''=YY/MM/DD HH:mm:SS.uuuuuu UTC
 +
 +
Append the call duration in [[call.cdr]] message with the given format
 +
: Allowed formats: HH mm SS N*u
 +
: Eg: '''duration_call'''=HH:mm:SS.uuu
 +
 
 +
=== The result of the module ===
 +
 
 +
The result of the module is sending the call.cdr message. One of the essential parameters of this message is "operation" parameter.<br/>
 +
The "operation" parameter indicates the state of the call and the reason why the message was sent.
 +
 
 +
The operation on CDRs to be performed is indicated by the "operation" parameter that can be one of:
  
 
* '''initialize''' - the first call.cdr message generated for the channel.
 
* '''initialize''' - the first call.cdr message generated for the channel.
 
* '''update''' - generated every time something could have changed.
 
* '''update''' - generated every time something could have changed.
−
* '''finalize''' - last call.cdr message generated for the channel holding the final information on the call leg, this is the only one used by the cdrfile module.  
+
* '''finalize''' - last call.cdr message generated for the channel holding the final information on the call leg, this is the only one used by the cdrfile module.
 +
 
 +
One of the modules that catches the call.cdr message for the same operations described above is [[CDRcombine Module]] and will emit call.cdr message with operation "combine" at the end of the call. Cdrcombine module unifies the information about the call and for the 2 call legs only a single entry will be written.
 +
 
 +
===Rmanager command===
 +
 
 +
From telnet you can see details from live CDRs by using 'status' command:
 +
 
 +
status cdrbuild
 +
%%+status:cdrbuild
 +
name=cdrbuild,type=cdr,format=Status|Caller|Called|BillId|Duration;cdrs=2,hungup=0;sip/2=ringing|103|104|1389195688-10|13,sip/3=ringing|103|104|1389195688-10|13
 +
%%-status
 +
 
 +
* cdrs=2 means that when command is given in telnet there are 2 call legs. Usually you will see 2 entries for a CDR because a call has 2 call legs.
 +
* The other elements displayed are described in '''format''' element: Status|Caller|Called|BillId|Duration.
 +
 
 +
As you've seen the call was not established, but once established the reason of the call is changed from 'ringing' to 'answered' and also the duration:
 +
 
 +
status cdrbuild
 +
%%+status:cdrbuild
 +
name=cdrbuild,type=cdr,format=Status|Caller|Called|BillId|Duration;cdrs=2,hungup=0;sip/2=answered|103|104|1389195688-10|45,sip/3=answered|103|104|1389195688-10|45
 +
%%-status
 +
 
 +
If the call ends then the 'hungup' value will change:
 +
status cdrbuild
 +
%%+status:cdrbuild
 +
name=cdrbuild,type=cdr,format=Status|Caller|Called|BillId|Duration;cdrs=0,hungup=2;
 +
%%-status
 +
 
 +
If you want to store the CDRs, other modules are used to write them [[CDR_File_Module|in a file]] or in the [[Register|database]].
 +
Some examples of how to store CDR entries you can find in [[How_To%27s#Call_detail_records|How To's]].
 +
 
 +
===Usage===
 +
 
 +
====Default behavior====
 +
 
 +
If you wish to store CDRs to a file, you will need to use '''cdrfile.conf'''. If you wish to store CDRs in a database you will need to edit either '''mysqldb.conf''' or '''pgsqldb.conf''', for either MySQL or PostgreSQL respectively and then '''register.conf''' to specify the queries to use.
 +
 
 +
Initially, you can keep the default configuration of the file '''cdrbuild.conf'''. Wait until the need arises, if you need more fields in CDR, then you can add parameters.
 +
 
 +
====Adding custom parameters====
 +
 
 +
For a more complex usage of cdrbuild module take a look at at the example on [[How_to_add_custom_parameters_in_CDR_from_routing|how to add custom parameters in CDR from routing]].
 +
 
  
−
In order for a variable/parameter to be available from the cdrbuild module it has to be enabled. Here's a complete list of builtin overridable variables:
+
'''See also'''
−
* billid
+
−
* reason
+
−
* address
+
−
* caller
+
−
* called
+
−
* callername
+
−
* calledfull
+
−
* username
+
  
−
Other variables are critical for the operation or generated internally and cannot be overriden:
+
* [[CDR File Module]]
−
* time
+
* [[Starting CDR Ring Timer on call.progress]]
−
* chan
+
−
* operation
+
−
* direction
+
−
* status
+
−
* duration
+
−
* billtime
+
−
* ringtime
+
−
* cdrwrite
+
−
* cdrtrack
+
−
* cdrcreate
+
−
* cdrid
+
−
* runid
+
  
−
'''Note:''' that in order for a parameter to appear in the chan.cdr messages it has to be received in at least one of the messages handled by this module. For outgoing calls you should use the ''copyparams'' parameter of the [[call.execute]] message to copy parameters from incoming call leg to the outgoing one.
+
[[Category:CDR]]

Latest revision as of 15:22, 13 January 2014

Cdrbuild module is the module that builds live CDRs (call detail records) and creates a list for the calls that can be interrogated using telnet command status.
Cdrbuild module reads messages from other channel modules (h323chan, ysipchan, iaxchan) about calls and builds the CDR.
Then it sends the "call.cdr" message. This message is caught by different cdr modules that intend to write in different mediums (cdrfile writes in file, register that writes in database).
Cdrbuild module generates CDR per channel not like cdrcombine that generates CDR per call.

The cdrbuild module is loaded by default unless yate.conf file is used to load only specific modules in Yate.

Contents

[edit] The configuration file

The file used by this module for configuration is cdrbuild.conf. See below the sections and their description.

[edit] Section [general]

  • resolution: keyword: Resolution for time representation: sec, msec or usec. The default value is:
resolution=msec
  • guardtime: int: Time in ms to remember hungup channels to avoid race conditions. The default value is:
guardtime=5000
  • updates: bool: Emit call.cdr message when call status has changed. The default value is:
updates=true
  • status: bool: Emit call.cdr status messages for the call duration. The default value is:
status=false
  • status_interval: int: The time interval in seconds to emit call.cdr status messages. 
Note: If status is set to false this interval will be ignored.
Default 60s. Minimum: 60s and Maximum 600s.
Default: status_interval=60
  • status_answer: bool: Emit cdr status message immediately when the call is answered.
If set to false the first cdr status is sent after status_interval.
status_answer=true
  • ring_on_progress: bool: Start ring timer when processing call.progress.
This parameter can be overridden in call.progress message by a 'ringing' parameter.The default value is:
ring_on_progress=no

[edit] Section [parameters]

In this section the possible values for the parameters that can be set, are true or false. This allows or disallows to overwrite their initial value.
There are 2 types of parameters in this section, the ones that can be overwritten and the ones that are handled internally and they can not be changed.
Also this is where you can add your own monitored parameters that will appear in "call.cdr".

The following parameters are handled by default but you can overwrite them:
  • billid=true ( will hold the billing ID. Billid is created from stitching the value of runid with the value cdrid )
  • reason=true ( a (mostly) human readable reason for this CDR )
  • address=false ( channel endpoint address being involved in this CDR )
  • caller=false ( caller party ID )
  • called=false ( called party ID )
  • calledfull=false ( full called party ID )
  • username=false ( username of the caller party ID )
The following parameters are handled internally and cannot be changed:
  • time: UNIX time and date when the CDR has been initially generated
  • chan: module and module-specific channel name being involved in this CDR
  • operation: one of initialize, update or finalize depending on the state of the CDR being signalled out
  • cdrwrite: true or false specify if the CDR will be written or not
  • cdrtrack: default true, if false the CDR will not be track
  • cdrcreate: default true, if set o false the CDR will not be build
  • cdrid: the channel ID for CDR
  • runid: running ID of Yate
  • direction: either of incoming or outgoing, Yate instance-wise (i.e. a call coming into the Yate instance emitting this CDR will have incoming here and a call being generated from the Yate instance in question will have outgoing here)
  • status: one of incoming, outgoing, ringing, answered or connected, reflecting the current state of the call referred to by this CDR
  • duration: end-to-end time (in seconds) of the call described in this CDR (i.e. from the moment the last digit was dialed on the calling side until the moment the line was hung up)
  • billtime: effective payable time (in seconds) of the call described in this CDR (i.e. from the moment the line was picked up on the called side until the moment the line was hung up)
  • ringtime: ringing time (in seconds) of the call described in this CDR (i.e. from the moment the routing decision has been taken and the remote endpoint alerted of the incoming call until the moment the line was picked up on the called side) 
Note: in order for a parameter to appear in the call.cdr messages it has to be received in at least one of the messages handled by this module. 
For outgoing calls you should use the copyparams parameter of the call.execute message to copy parameters from incoming call leg to the outgoing one.

[edit] Section [formatted-timers]

This is a special section for time formatting. 

Formatting rules:
YYYY | %Y -> Year (2012)
YY | %y   -> Year, last two digits (00-99)
MM | %m   -> Month as a decimal number (01-12)
DD | %d   -> Day of the month (01-31)
HH | %H   -> Hour in 24h format (00-23)
mm | %M   -> Hour in 24h format (00-23)
SS | %S   -> Second (00-60)
             Note! the value is rounded.
UTC       -> If present the time will represent the UTC time. 
             If is missing the time will represent local time zone.
N*u       -> Milliseconds and Microseconds.
             Note! The value is rounded.
             EG: time: 1.123456
                 s.u -> 1.1
                 s.uu -> 1.12
                 s.uuu -> 1.123
                 s.uuuu -> 1.1234
                 s.uuuuu -> 1.12346
                 s.uuuuuu -> 1.123456
Other formats may be used but they must correspond with C strftime method formats.
Important! If duplicate formats are ignored!
Eg: date : 09 14 2012
           YYYY YY DD DD mm DD-> 2012 YY 14 DD 09 DD

Append the call start time in call.cdr message with the given format.

Eg: call_start_time=YY/MM/DD HH:mm:SS.uuuuuu UTC

Append the call answer time in call.cdr message with the given format

Eg: call_answer_time=YY/MM/DD HH:mm:SS.uuuuuu UTC

Append the call hangup time in call.cdr message with the given format

Eg: call_hangup_time=YY/MM/DD HH:mm:SS.uuuuuu UTC

Append the call duration in call.cdr message with the given format

Allowed formats: HH mm SS N*u
Eg: duration_call=HH:mm:SS.uuu

[edit] The result of the module

The result of the module is sending the call.cdr message. One of the essential parameters of this message is "operation" parameter.
The "operation" parameter indicates the state of the call and the reason why the message was sent.

The operation on CDRs to be performed is indicated by the "operation" parameter that can be one of:

  • initialize - the first call.cdr message generated for the channel.
  • update - generated every time something could have changed.
  • finalize - last call.cdr message generated for the channel holding the final information on the call leg, this is the only one used by the cdrfile module.

One of the modules that catches the call.cdr message for the same operations described above is CDRcombine Module and will emit call.cdr message with operation "combine" at the end of the call. Cdrcombine module unifies the information about the call and for the 2 call legs only a single entry will be written.

[edit] Rmanager command

From telnet you can see details from live CDRs by using 'status' command: 

status cdrbuild 
%%+status:cdrbuild
name=cdrbuild,type=cdr,format=Status|Caller|Called|BillId|Duration;cdrs=2,hungup=0;sip/2=ringing|103|104|1389195688-10|13,sip/3=ringing|103|104|1389195688-10|13
%%-status
  • cdrs=2 means that when command is given in telnet there are 2 call legs. Usually you will see 2 entries for a CDR because a call has 2 call legs.
  • The other elements displayed are described in format element: Status|Caller|Called|BillId|Duration.

As you've seen the call was not established, but once established the reason of the call is changed from 'ringing' to 'answered' and also the duration: 

status cdrbuild
%%+status:cdrbuild
name=cdrbuild,type=cdr,format=Status|Caller|Called|BillId|Duration;cdrs=2,hungup=0;sip/2=answered|103|104|1389195688-10|45,sip/3=answered|103|104|1389195688-10|45
%%-status

If the call ends then the 'hungup' value will change: 

status cdrbuild
%%+status:cdrbuild
name=cdrbuild,type=cdr,format=Status|Caller|Called|BillId|Duration;cdrs=0,hungup=2;
%%-status

If you want to store the CDRs, other modules are used to write them in a file or in the database. Some examples of how to store CDR entries you can find in How To's.

[edit] Usage

[edit] Default behavior

If you wish to store CDRs to a file, you will need to use cdrfile.conf. If you wish to store CDRs in a database you will need to edit either mysqldb.conf or pgsqldb.conf, for either MySQL or PostgreSQL respectively and then register.conf to specify the queries to use.

Initially, you can keep the default configuration of the file cdrbuild.conf. Wait until the need arises, if you need more fields in CDR, then you can add parameters.

[edit] Adding custom parameters

For a more complex usage of cdrbuild module take a look at at the example on how to add custom parameters in CDR from routing.


See also

Retrieved from "https://docs.yate.ro/wiki/index.php?title=CDR_Build_Module&oldid=7555"
Personal tools
Namespaces

Variants
Actions
Preface
Configuration
Administrators
Developers