mod_cdr_csv
0. About
This module allows you to log call detail records (CDRs) to a text file using text generation templates. These templates along with the default configuration are stored in the file <conf_dir>/autoload_configs/cdr_csv.conf.xml
.
Which template is used for the default is defined by the line below (which uses "example" in the default installation).
<param name="default-template" value="example"/>
Further down in the cdr_csv.conf.xml
file, the "example" template is defined within the <templates>
, </templates>
opening and closing tags. Therefore to change what is being logged you may edit the example template or create a new template and update the default-template
param to that template name.
1. Default configuration
<conf_dir>/autoload_configs/cdr_csv.conf.xml
<configuration name="cdr_csv.conf" description="CDR CSV Format">
<settings>
<!-- 'cdr-csv' will always be appended to log-base -->
<!--<param name="log-base" value="/var/log"/>-->
<param name="default-template" value="example"/>
<!-- This is like the info app but after the call is hung up -->
<!--<param name="debug" value="true"/>-->
<param name="rotate-on-hup" value="true"/>
<!-- may be a b or ab -->
<param name="legs" value="a"/>
</settings>
<templates>
<template name="sql">INSERT INTO cdr VALUES ("${caller_id_name}","${caller_id_number}","${destination_number}","${context}","${start_stamp}","${answer_stamp}","${end_stamp}","${duration}","${billsec}","${hangup_cause}","${uuid}","${bleg_uuid}", "${accountcode}");</template>
<template name="example">"${caller_id_name}","${caller_id_number}","${destination_number}","${context}","${start_stamp}","${answer_stamp}","${end_stamp}","${duration}","${billsec}","${hangup_cause}","${uuid}","${bleg_uuid}","${accountcode}","${read_codec}","${write_codec}"</template>
<template name="snom">"${caller_id_name}","${caller_id_number}","${destination_number}","${context}","${start_stamp}","${answer_stamp}","${end_stamp}","${duration}","${billsec}","${hangup_cause}","${uuid}","${bleg_uuid}", "${accountcode}","${read_codec}","${write_codec}","${sip_user_agent}","${call_clientcode}","${sip_rtp_rxstat}","${sip_rtp_txstat}","${sofia_record_file}"</template>
<template name="linksys">"${caller_id_name}","${caller_id_number}","${destination_number}","${context}","${start_stamp}","${answer_stamp}","${end_stamp}","${duration}","${billsec}","${hangup_cause}","${uuid}","${bleg_uuid}","${accountcode}","${read_codec}","${write_codec}","${sip_user_agent}","${sip_p_rtp_stat}"</template>
<template name="asterisk">"${accountcode}","${caller_id_number}","${destination_number}","${context}","${caller_id}","${channel_name}","${bridge_channel}","${last_app}","${last_arg}","${start_stamp}","${answer_stamp}","${end_stamp}","${duration}","${billsec}","${hangup_cause}","${amaflags}","${uuid}","${userfield}"</template>
</templates>
</configuration>
Useful things to know:
- You can change the
legs
valuea
for a-leg,b
for b-leg andab
for both legs. - The template can be changed to include useful information such as
${remote_media_ip}
and${network_addr}
- The template can be changed to include any custom variables you have set in the dialplan of the corresponding leg, with something like
{customer_name=whitehouse}sofia/gateway/foo/$1
. Then${customer_name}
can be used in the CDR template. - If you log CDR for only one leg and you would like to include some data of the other leg, then u need to prefix
aleg_
orbleg_
before the variable in the template - If you log b-leg then variables can be used directly for that leg such as
${caller_id_name}
and the a-leg variables need to be prefixed withaleg_
andbleg_
if you log a-leg calls
2. API commands
To rotate CDRs without HUPing (i.e., shutting down) the entire FreeSWITCH instance (if rotate-on-hup
is set, that is, see below).
In fs_cli
cdr_csv rotate
Or, from the system terminal:
On the system terminal
fs_cli -x 'cdr_csv rotate'
2. XML
2.1 Settings (<settings>
)
The following parameters (self-closing <param>
tags in <settings>
) can be set under the <settings>
tag in your <conf_dir>/autoload_configs/cdr_csv.conf.xml
file.
<settings>
<param name="PARAM-NAME-HERE" value="VALUE"/>
<!-- PARAM-NAME-HERE = debug, default-template, legs, etc. -->
<!-- param 2 -->
<!-- ... -->
<!-- param N -->
</settings>
debug
When set to true, this prints out all channel data in your log when creating a new CDR record is generated.
- Possible values:
true
,false
- Default value:
false
default-template
The name of a template as defined in the <templates>
section of your <conf_dir>/autoload_configs/cdr_csv.conf.xml
.
- Default value:
default
legs
Choose whether the module will save CDRs for the a or b leg, or both of them.
- Possible values:
a
,b
,ab
- Default value:
a
log-base
The directory where the CSV files will be written to.
- Default value: <
root-of-your-freeswitch-installation>/log/cdr-csv
(or/var/log/freeswitch/
) - The value can be overridden by
cdr_csv_base
channel variable.
master-file-only
When enabled, all CDRs will be written to a single file instead of to multiple files split up per accountcode
.
- Possible values:
true
,false
- Default value:
false
rotate-on-hup
When enabled, after sending a HUP signal to FreeSWITCH (i.e., when the FreeSWITCH server is stopped), the logfile will be rotated to a format like this:
Master.csv.YYYY-mm-dd-HH-MM-SS
- Possible values:
true
,false
- Default value: TODO What is the default?
3. FreeSWITCH variables in a template (<template>
)
FreeSWITCH variables are given in the form ${varname}
. For an overview of variables, check Channel Variables. You can specify any channel variable.
API calls can also be specified in variables, such as:
<template name="custom_timestamp">"${expr(${end_epoch}-${my_timestamp})}"</template>
For example, the first line below shows the definition of the default example
template, and the second one is the output after a successful call:
<template name="example">
"${caller_id_name}","${caller_id_number}","${destination_number}",
"${context}", "${start_stamp}", "${answer_stamp}",
"${end_stamp}", "${duration}", "${billsec}",
"${hangup_cause}", "${uuid}", "${bleg_uuid}",
"${accountcode}", "${read_codec}", "${write_codec}"
</template>
"+19168897510", "+19168897510", "+19167324000",
"default", "2020-10-12 16:52:37", "2020-10-12 16:52:37",
"2020-10-12 16:52:42", "5", "5",
"NORMAL_CLEARING", "5f26b500-d6b1-4c8a-b3ed-cfbea629f011", "",
"", "PCMU", "PCMU"
3.1 Some notable FreeSWITCH variables
Read about Variables, and see the full list in Channel Variables.
accountcode
An arbitrary value given at whim. Useful for billing and segregating calls by account. This is the accountcode
of the aleg.
If the value of the accountcode variable matches the name of a template then that template will be used. This is valuable for having a specific template be used on a per-call basis.
amaflags
Automatic Message Accounting, an archaic system that "flags" CDR for post-processing. Commonly used flags are billing
, default
, documentation
, omit
.
answer_epoch
UNIX epoch value when the call was answered, eg. 1294060468 for Mon, 03 Jan 2011 13:14:28 GMT.