CDR Build Module

Revision as of 21:31, 9 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. This module is loaded by default unless yate.conf file is used to load modules in Yate.

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 (file, database).

Configuration

The file used in configuration is cdrbuild.conf. See below the section and their description.

[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

[parameters]

Each line consists of name=bool, where name is the name of the parameter being monitored while bool allows or disallows subsequent overwrites of the initial non-empty value. 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
• reason=true
• address=false
• caller=false
• called=false
• calledfull=false
• username=false

The following parameters are handled internally and cannot be changed:

• time, chan, operation, cdrwrite, cdrtrack, cdrcreate, cdrid, runid, direction, status, duration, billtime, ringtime

[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 me 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

call_start_time=

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

call_answer_time=

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

call_hangup_time=

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

Allowed formats: HH mm SS N*u

Eg: HH:mm:SS.uuu

duration_call=

Operation on CDRs

The operation 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.

Another module 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.

List of builtin overridable variables

In order for a variable/parameter to be available from the cdrbuild module it has to be enabled from configuration file. Here's a complete list of builtin overridable variables:

• billid
• reason
• address
• caller
• called
• calledfull
• username

List of generated internally variables

Other variables are critical for the operation or generated internally and cannot be overriden:

• time
• chan
• operation
• direction
• status
• duration
• billtime
• ringtime
• cdrwrite
• cdrtrack
• cdrcreate
• cdrid
• runid

Note: that 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.

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.

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.

See also

• CDR File Module
• Starting CDR Ring Timer on call.progress