Mod xml cdr

From FreeSWITCH Wiki

Contents 1 Description 2 Features 2.1 Output capabilities 2.2 Reliability capabilities 3 Getting it working 3.1 modules.conf 3.2 Install dependencies 3.2.1 Debian 3.3 Building 3.4 modules.conf.xml 3.5 Sample Configuration 3.6 Verifying 4 Configuration Options 5 Handling POST request 5.1 Examples 6 Reference Information 6.1 Channel Variables 6.1.1 Call Date/Time Variables 6.1.1.1 answer_stamp 6.1.1.2 end_stamp 6.1.1.3 profile_start_stamp 6.1.1.4 progress_stamp 6.1.1.5 progress_media_stamp 6.1.1.6 start_stamp 6.1.2 Call Epoch Variables 6.1.2.1 answer_epoch 6.1.2.2 answer_uepoch 6.1.2.3 end_epoch 6.1.2.4 end_uepoch 6.1.2.5 profile_start_epoch 6.1.2.6 profile_start_uepoch 6.1.2.7 start_epoch 6.1.2.8 start_uepoch 6.1.3 Call Duration Variables 6.1.3.1 billsec 6.1.3.2 billmsec 6.1.3.3 billusec 6.1.3.4 duration 6.1.3.5 flow_billsec 6.1.3.6 flow_billmsec 6.1.3.7 flow_billusec 6.1.3.8 mduration 6.1.3.9 progresssec 6.1.3.10 progressmsec 6.1.3.11 progressusec 6.1.3.12 progress_mediasec 6.1.3.13 progress_mediamsec 6.1.3.14 progress_mediausec 6.1.3.15 uduration 7 Troubleshooting 7.1 Recovering CDRs 7.2 Error loading module 7.3 Does not write to non-default logDir 7.4 I'm getting a Memory Error when module loads 8 FAQ 8.1 Q: Does mod_cdr need to be compiled/enabled?

Description

Outputs CDR records in XML format to local file or to a webserver via HTTP POST.

Here is an Example XML cdr

 

Features

Output capabilities

• Always log to the disk
• Always log to HTTP/HTTPS
• Always log to both

Reliability capabilities

On failure it will log the HTTP POST data to disk where you specify, and it has configurable timeouts and retries for the HTTP post.

Getting it working

modules.conf

To compile the module, uncomment mod_xml_cdr in modules.conf

Install dependencies

If you try to build and get an error

you will need to install curl and the development headers.

Debian

Building

modules.conf.xml

Enable mod_xml_cdr in modules.conf.xml for the next time freeswitch is restarted. Type load mod_xml_cdr at the CLI to load the module.

Sample Configuration

Edit or Create a file in the \conf\autoload_configs\ directory called xml_cdr.conf.xml with the following contents:

 

 

Verifying

Place a call, hangup, and you should have a new XML file in /usr/local/freeswitch/log. Also check your webserver logs.

Configuration Options

name	description	example
cred	credentials to use to post to webserver (if webserver requires it)	user:pass
auth-scheme	which auhtentification scheme to use. Supported values are: basic, digest, NTLM, GSS-NEGOTIATE or "any" for automatic detection	basic
url	Webserver URL (you can specify this element more than once, and it will try each URL in order of succession until retries is reached. note retries is not per URL specified)	http://myhost/cdr.php
log-http-and-disk	Default behaviour is to write either HTTP or Disk on HTTP failure. Setting this to true will write to both HTTP and Disk regardless (handy for realtime + reconciliation later if required)	true
retries	number of retries before giving up http post and writing to disk	2
delay	delay in seconds before retrying	120
log-dir	directory to log to -- you must create this directory. If left blank, will use the default directory. If omitted, disables logging to a file and will only POST to webserver. If a name is given instead of a path, a subdirectory under the default will be used. This directory must already exists.	/tmp/log
err-log-dir	directory to log errors to -- you must create this directory. If left blank, will use the default directory. If omitted, disables logging to a file and will only POST to webserver. If a name is given instead of a path, a subdirectory under the default will be used. This directory must already exists.	/tmp/errlog
encode	whether to encode the information in the POST that is sent to the webserver. By default, (if this param is not provided or is invalid) the content-type of the post is application/x-www-form-plaintext and no URL-encoding is done on the POST'ed data. If set to 'True', it will set the content type to application/x-www-form-urlencoded and URL-encode the information. This is what most webservers expect. If set to base64, the content type will be application/x-www-form-base64-encoded. Finally, if set to textxml the content type will be text/xml.	True

Handling POST request

The POST request can be made to any web server via HTTP or HTTPS. The script handling the request can be in any language you choose.

The POST request consists of a single variable named cdr, which contains the CDR as a XML document (the same data that would be written to disk).

If the page returns a HTTP status code of 200 OK, then the request is treated as successful. Any other status code will be treated as failure, which will cause mod_xml_cdr to either retry the request, try the next server or write to disk. No output is required; only the status code is used to check whether the request succeeded.

The contents of the cdr variable can be parsed with the XML parser available within your language of choice. It will appear similar to:

<?xml version="1.0"?>
<cdr>
  <channel_data>
    <state>CS_REPORTING</state>
    <direction>inbound</direction>
    <state_number>11</state_number>
    <flags>0=1;36=1;38=1;51=1</flags>
    <caps>1=1;2=1;3=1</caps>
  </channel_data>
  <variables>
   <uuid>2e831835-d336-4735-b3e5-90e5d7dc8187</uuid>
   <sip_network_ip>192.168.0.2</sip_network_ip>
   <sip_network_port>56866</sip_network_port>
   <sip_received_ip>192.168.0.2</sip_received_ip>
   <sip_received_port>56866</sip_received_port>
   <sip_via_protocol>udp</sip_via_protocol>
   <sip_from_user>1000</sip_from_user>
   <sip_from_uri>1000%40192.168.0.2</sip_from_uri>
   <sip_from_host>192.168.0.2</sip_from_host>
   <sip_from_user_stripped>1000</sip_from_user_stripped>
   <sip_from_tag>BD37552C-4B5</sip_from_tag>
   ...
  </variables>
  <app_log>
   <application app_name="set" app_data="continue_on_fail=true"></application>
   <application app_name="bridge" app_data="sofia/external/gateway/gw001/1000"></application>
   <application app_name="bridge" app_data="sofia/external/gateway/gw002/1000"></application>
  </app_log>
  <callflow dialplan="XML" profile_index="1">
   <extension name="1000" number="1000">
    <application app_name="set" app_data="continue_on_fail=true"></application>
    <application app_name="bridge" app_data="sofia/external/gateway/gw001/1000"></application>
    <application app_name="bridge" app_data="sofia/external/gateway/gw002/1000"></application>
    <application app_name="bridge" app_data="sofia/external/gateway/gw003/1000"></application>
    <application app_name="bridge" app_data="sofia/external/gateway/gw004/1000"></application>
    <application app_name="bridge" app_data="sofia/external/gateway/gw005/1000"></application>
   </extension>
  </callflow>
  <caller_profile>
    <username>1000</username>
    <dialplan>XML</dialplan>
    <caller_id_name>1000</caller_id_name>
    <ani>1000</ani>
    <aniii></aniii>
    <caller_id_number>1000</caller_id_number>
    <network_addr>192.168.0.2</network_addr>
    <rdnis>1000</rdnis>
    <destination_number>1000</destination_number>
    <uuid>2e831835-d336-4735-b3e5-90e5d7dc8187</uuid>
    <source>mod_sofia</source>
    <context>default</context>
    <chan_name>sofia/default/1000@192.168.0.2</chan_name>
  </caller_profile>
  <times>
    <created_time>1274439432438053</created_time>
    <profile_created_time>1274439432448060</profile_created_time>
    <progress_time>0</progress_time>
    <progress_media_time>0</progress_media_time>
    <answered_time>0</answered_time>
    <hangup_time>1274439438418776</hangup_time>
    <resurrect_time>0</resurrect_time>
    <transfer_time>0</transfer_time>
  </times>
</cdr>

Note that you'll see many character sequences such as %22. These replace a character in the XML with its ASCII number in hexadecimal and is required to make the document valid XML. This is part of XML and your XML parser will convert these to their original value when parsing the document.

Examples

See scripts/contrib/trixter/xml-cdr for examples to take a webpost (which mod_xml_cdr does now) and turn it into an associative array so your script can process it.

Reference Information

The Example XML cdr was generated by calling the FreeSWITCH conference via the PSTN. A SIP phone registered with FS dialed 9+2137991400 and went through this dialplan extension:

  <!-- Dial 9, go out Qwest PRI on span 1 -->
  <extension name="Dial 9">
    <condition field="destination_number" expression="^9(\d{10})$">
      <action application="bridge" data="openzap/1/A/$1"/>
    </condition>
  </extension>

Channel Variables

The XML CDR contains a number of channel variables as well as call flow information.
Call times are in date/time stamp format or in either epoch seconds or epoch microseconds (usec).
Date/time stamp variables are URI encoded so be sure to "URI decode" them prior to inserting them into a database.
Example: "2008-07-31%2011%3A35%3A38" is URI encoded. Decoded it is "2008-07-31 11:35:38".
The epoch began at 1970-01-01 00:00:00, therefore the epoch values are the number of seconds (or microseconds) since the epoch began.
Using the epoch microseconds values allows for extremely accurate measurements.

Call Date/Time Variables

answer_stamp

Date/time that the far end of the call was actually answered.
In the example CDR this value is "2008-07-31%2011%3A35%3A41" (2008-07-31 11:35:41).

end_stamp

Date/time that the call was terminated.
In the example CDR this value is "2008-07-31%2011%3A36%3A17" (2008-07-31 11:36:17).

profile_start_stamp

???? (still researching this one).
In the example CDR this value is "2008-07-31%2011%3A35%3A38" (2008-07-31 11:35:38).

progress_stamp

Date/time that progress information from the far end is first received.
In the example CDR this value is "2008-07-31%2011%3A35%3A38" (2008-07-31 11:35:38). (Researching accuracy of this statement)

progress_media_stamp

Date/time that "early media" or progress media was first received. "Early media" includes ring-back tone (RBT).
In the example CDR this value is "2008-07-31%2011%3A35%3A38" (2008-07-31 11:35:38).

start_stamp

Date/time that the call was initiated.
In the example CDR this value is "2008-07-31%2011%3A35%3A38" (2008-07-31 11:35:38).

Call Epoch Variables

answer_epoch

Call answer time in epoch seconds.
In the example CDR this value is 1217529338.

answer_uepoch

Call answer time in epoch microseconds.
In the example CDR this value is 1217529338452698.

end_epoch

Call end time in epoch seconds.
In the example CDR this value is 1217529377.

end_uepoch

Call end time in epoch microseconds.
In the example CDR this value is 1217529377795951.

profile_start_epoch

Profile start time in epoch seconds.
In the example CDR this value is 1217529338.

profile_start_uepoch

Profile start time in epoch microseconds.
In the example CDR this value is 1217529338212616.

start_epoch

Call start time in epoch seconds.
In the example CDR this value is 1217529338.

start_uepoch

Call start time in epoch microseconds.
In the example CDR this value is 1217529338212616.

Call Duration Variables

billsec

Billable call duration in seconds. Billable time does not include call time spent in "early media" prior to the far end answering the call.
In the example CDR this value is 36.

billmsec

Billable call duration in milliseconds. Billable time does not include call time spent in "early media" prior to the far end answering the call.
In the example CDR this value is 36267.

billusec

Billable call duration in microseconds. Billable time does not include call time spent in "early media" prior to the far end answering the call.
In the example CDR this value is 36267529.

duration

Total call duration in seconds.
In the example CDR this value is 39.

flow_billsec

flow_billmsec

flow_billusec

mduration

Total call duration in milliseconds.
In the example CDR this value is 39583.

progresssec

The amount of time in seconds between the sip invite and the sip 180 message
In the example CDR this value is 0. (Less than 1 second.)

progressmsec

The amount of time in milliseconds between the sip invite and the sip 180 message
In the example CDR this value is 238.

progressusec

The amount of time in microseconds between the sip invite and the sip 180 message
In the example CDR this value is 237955.

progress_mediasec

The amount of time in seconds between the sip invite and the sip 183 message
In the example CDR this value is 0. (Less than 1 second.)

progress_mediamsec

The amount of time in milliseconds between the sip invite and the sip 183 message
In the example CDR this value is 238.

progress_mediausec

The amount of time in microseconds between the sip invite and the sip 183 message
In the example CDR this value is 237955.

uduration

Total call duration in microseconds.
In the example CDR this value is 39583335.

Troubleshooting

Recovering CDRs

Within ./conf/autoload_configs/xml_cdr.conf.xml you can activate the "err-log-dir" option to log in a directory the xml cdrs if the http cdr server is down.

You may want to re-sent your backuped cdr to the server once it's back.

The curl command to do that is :

curl -X POST --data-urlencode cdr@cdr.xml  http://yourcdrserver/

One may want to script into the err-log-dir directory in a :

for xmlcdrfile in *.cdr.xml; do curl -X POST -d cdr=$(cat $xmlcdrfile) http://yourcdrserver; rm -f $xmlcdrfile; done

Error loading module

2007-06-27 17:59:12 [ERR] switch_loadable_module.c:714 switch_loadable_module_load_file() Error 
Loading module /usr/local/freeswitch/mod/mod_xml_cdr.so
**/usr/local/freeswitch/mod/mod_xml_cdr.so: undefined symbol: curl_easy_getinfo**

Fix: This indicates you dont have curl linked in right. Check the mod_xml_cdr/Makefile and make sure it has WANTS_CURL=yes

Does not write to non-default logDir

If you set logDir to /tmp/foo, you must mkdir /tmp/foo/xml_cdr or it will revert to the default directory.

I'm getting a Memory Error when module loads

2007-06-27 19:41:06 [DEBUG] mod_xml_cdr.c:192 do_config() processing logDir config
2007-06-27 19:41:06 [DEBUG] mod_xml_cdr.c:197 do_config() val is NON zero length, setting globals.logDir: /tmp/log
2007-06-27 19:41:06 [CRIT] mod_xml_cdr.c:219 do_config() Memory Error!

Fix: try setting a custom errLogDir in config and this error should go away. It is a bug, and it's not actually a memory error that indicates any memory related problems.

FAQ

Q: Does mod_cdr need to be compiled/enabled?

No, this module is independent -- you may have both without conflict, they will not communicate with each other.