Text Call Detail Records

Revision as of 09:55, 20 June 2011

Text call detail records (CDR) are saved in a log file on disk.

In order to save disk space and simplify the archiving and backup of CDR log files, this log file is automatically archived (gzipped) and rotated every N seconds, as specified by the system configuration.

The format of the CDR traces is defined by configuration, using variables that are replaced by the Gateway application when writing to the log. For example, the following variable will be replaced by the called number: @{CalledNumber}

Enabling text CDR

Text CDR functionality is enabled through the Toolpack Web Portal:

• Go to the Gateway->Configuration menu.
• Click on the Edit link of the configuration you wish to enable CDR for.
• Click on Use CDR behavior to enable the CDR behavior
• Expand the CDR Options section
• Click on Use text CDR to enable text-based CDR
• Expand the Text CDR parameters section
• Configure the Text CDR parameters the way you want, using the parameters describe below

Configuration parameters

• CDR log file path: Path of the CDR log file, relative to the current working directory of the Gateway application (e.g.[...]/toolpack/setup/12358/apps/gateway).
• CDR format (start): Format of the text CDR log written at the time the call is answered (or terminated if it was never answered). This format contains variables automatically replaced (see below).
• CDR format (update): Format of the text CDR log written periodically during call if the CDR option Enable periodic CDR update is used. This format contains variables automatically replaced (see below).
• CDR format (end): Format of the text CDR log written at the time the call is terminated. This format contains variables automatically replaced (see below).
• Rotation delay in seconds: Delay, in seconds, at which the log file is rotated and gzipped. A delay of 3600 seconds will make log file rotate every hour, for example. NOTE: This parameter cannot be larger then 86400 seconds (1 day). A value of 0 will be considered as the equivalent of the maximum value.
• Max total size of gzipped CDR logs: Maximum total size (in bytes) of all gzipped log file segments on disk. If ever total size exceeds this limit, older gzipped log files will be deleted. A value of 0 will be considered as unlimited size.

Available variables

The following variables exist and can be used to define the CDR log format:

*@{ApplicationName}:        Name of the application that has written this log ("Gateway")
*@{CalledNumber}:           Called number
*@{CallingNumber}:          Calling number
*@{CallType}:               Call type ("Telephony" or "VOIP")
*@{Codec}:                  Codec used for this call ("G711" for example)
*@{ConnectedTime}:          Time where the call was answered (and connected with another leg) (in number of seconds since epoch)
*@{ConnectedTime:format}:   Same as @{ConnectedTime} but with custom print format (local time zone), using 'strftime' style, with added
                            support for @m replaced by milliseconds.
                            Example format: %Y-%m-%d %H:%M:%S.@m  -> 2009-09-02 12:16:24.333
*@{ConnectedTimeUtc:format}:Same as @{ConnectedTime:format} but printed in UTC time, rather than local time zone.
*@{EndTime}:                Time where the call has started terminating (in number of seconds since epoch).
                            Note that slightly differs from the @{Timestamp}, since the 'End' CDR trace is printed once the call has
                            finished terminating,
                            while @{EndTime} reports the time where the call has started terminating (upon hangup for example).
*@{EndTime:format}:         Same as @{EndTime} but with custom print format (local time zone), using 'strftime' style, with added
                            support for @m replaced by milliseconds.
                            Example format: %Y-%m-%d %H:%M:%S.@m  -> 2009-09-02 12:16:24.333
*@{EndTimeUtc:format}:      Same as @{EndTime:format} but printed in UTC time, rather than local time zone.
*@{LegId}:                  Unique Id for this leg (32 bits value, but may eventually be upgraded to 64 bits value).
                            See "Known limitations" below for notes about uniqueness of this value.
*@{LinkId}:                 Id common to all call legs from the same call.
                            Deprecated. @{OriginalSessionId} should be used instead. 
*@{MediaInfo}:              Protocol type dependent information on the call leg.
                            For TDM (Telephony) calls (SS7 or ISDN): "trunk_name:timeslot_nb".
                            For VOIP calls (SIP): "codec@ip:port"
*@{NAP}:                    Name of the NAP this call leg is from
*@{OriginalSessionId}:      Unique call identifier for all call legs of a call, including failed route retry attempts, and call
                            transfer legs. Provided in the form of 4 values of 32 bits, printed as 4 blocks of
                            8 hexadecimal characters separated by a space.
                            See "Known limitations" below for notes about uniqueness of this value.
*@{OriginatorName}:         Direction of the call:
                             - "originate" (incoming call leg) - "answer" (outgoing call leg)
*@{OtherLegId}:             Id of the other call leg joined with current call leg.
                            See "Known limitations" below for notes about uniqueness of this value.
*@{Protocol}:               Type of protocol used ("SS7", "ISDN", or "SIP")
*@{RemoteIP}:               For VOIP calls, IP address of the remote peer for this call leg.
*@{RemotePort}:             For VOIP calls, UDP port of the remote peer for this call leg.
*@{SessionId}:              Unique call identifier, in the form of 4 values of 32 bits, printed as 4 blocks of 8 hexadecimal characters
                            separated by a space.
                            See "Known limitations" below for notes about uniqueness of this value.
*@{StartTime}:              Time where the call was created (in number of seconds since epoch)
*@{StartTime:format}:       Same as @{StartTime} but with custom print format (local time zone), using 'strftime' style, with added
                            support for @m replaced by milliseconds.
                            Example format: %Y-%m-%d %H:%M:%S.@m  -> 2009-09-02 12:16:24.333
*@{StartTimeUtc:format}:    Same as @{StartTime:format} but printed in UTC time, rather than local time zone.
*@{TerminationCause}:       Cause of the call termination, printed as an integer value (refering enum TBCMC_CALL_REASON_CODE)
*@{TerminationCauseString}: Cause of the call termination, printed as an string value
*@{TerminationSource}:      Identifies which of the legs has initiated the call termination first: "LocalLeg" or "ConnectedLeg"
*@{TimeslotNumber}:         For TDM (Telephony) calls, timeslot number that this call was using for audio.
*@{Timestamp}:              Time where this CDR log entry was written.
                            Note that slightly differs from the @{Timestamp}, since the 'End' CDR trace is printed once the call has
                            finished terminating,
                            while @{EndTime} reports the time where the call has started terminating (upon hangup for example).
*@{Timestamp:format}:       Same as @{Timestamp} but with custom print format (local time zone), using 'strftime' style, with added
                            support for @m replaced by milliseconds.
                            Example format: %Y-%m-%d %H:%M:%S.@m  -> 2009-09-02 12:16:24.333
*@{TimestampUtc:format}:    Same as @{Timestamp:format} but printed in UTC time, rather than local time zone.
*@{TrunkName}:              For TDM (Telephony) calls, name of the trunk that this call was using for audio.
*@{UserName}:               For SIP calls, name of the user.
*@{ChargeIndicator}:        For TDM (SS7 and CASR2); received charge indicator in Alert message.

Known limitations

The following values may not be unique due to following limitations:

• @{LegId}
• @{OtherLegId}
• @{SessionId}
• @{OriginalSessionId}

In case both gateway and toolpack_engine applications are are restarted at the same time:

• Recently used values may be reused for new call legs (though not twice simultaneously). This is fixed starting with release 2.5.66, which guarantees values are not reused within 49 days
• Active call legs will be re-assigned a different value. It is thus not possible to correlate "start" and "end" traces from one call that was active when applications were restarted. This is fixed starting with release 2.6.0

In both cases above, the workaround is to analyze CDR logs, for billing, based only on the information found in the "end" trace (which should have all required information anyways)

Redundancy

In a redundant Toolpack system with two Gateway applications, the active Gateway application writes the CDR logs.

The analysis of the logs for the purpose of extracting billing information must be done after combining the two logs, sorting the entries by timestamp for example.

It is worth noting that an entry will never be duplicated. It can, however, be lost during transition from active to standby Gateway applications following a system fault. Consequently, a CDR analysis script must thus handle the case where a call answered log does not match any call termination log.

Default values

The default values are as follows:

For the CDR that is printed when the call leg is answered:

@{Timestamp:%Y-%m-%d %H:%M:%S.@m%z},BEG,SessionId='@{SessionId}',LegId='@{LegId}',
StartTime='@{StartTime}',ConnectedTime='@{ConnectedTime}',Calling='@{CallingNumber}', 
Called='@{CalledNumber}',NAP='@{NAP}',Protocol='@{Protocol}',Direction='@{OrginatorName}' 

(Note: the above is a signle line!)

For the CDR that is printed throught the call at periodic intervals (if this option is enable on the CDR behavior):

@{Timestamp:%Y-%m-%d %H:%M:%S.@m%z}: SessionId='@{SessionId}' LegId='@{LegId}'

For the CDR that is printed when the call leg is terminated:

@{Timestamp:%Y-%m-%d %H:%M:%S.@m%z},END,SessionId='@{SessionId}',LegId='@{LegId}',
StartTime='@{StartTime}',ConnectedTime='@{ConnectedTime}', EndTime='@{EndTime}',
FreedTime='@{Timestamp}',TerminationCause='@{TerminationCauseString}', 
Calling='@{CallingNumber}',Called='@{CalledNumber}',NAP='@{NAP}',Direction='@{OrginatorName}' 

(Note: the above is a signle line!)

Examples

For example, one may define a short comma-separated value-based (CSV) CDR log file to minimize disk space requirements:

"@{LegId},@{ConnectedTime},@{EndTime},@{CallingNumber},@{CalledNumber},@{NAP}"

As another example, one may define a XML-based CDR log file:

<cdr_start>
 <time timestamp="@{Timestamp}" start_time="@{StartTime}" connect_time="@{ConnectedTime}" end_time="@{EndTime}"/>
 <id session_id="@{SessionId}" leg_id="@{LegId}" link_id="@{LinkId}"/>
 <number calling="@{CallingNumber}" called="@{CalledNumber}" direction="@{OrginatorName}"/>
 <info nap="@{NAP}" protocol="@{Protocol}" called="@{CalledNumber} media="@{MediaInfo}"/>
 <termination cause="@{TerminationCauseString}" source="@{TerminationSource}"/>
</cdr_start>

How to retrieve CDR

There are 2 ways to retrieve the test CDR manually or automatically. The procedures are describe here.

Notes

• This mode of operation is not recommended for TMG800 or TMG3200 with a flash disk. However, the TMG3200 with SATA disk option is OK (use command cat /proc/device-tree/model to identify your device model).
• TelcoBridges does not recommend storing CDR logs via network file systems (NFS or other). We highly recommend writing to a local hard drive and have developed a background script that moves the gzipped log segments for backup or analysis.