Text Call Detail Records

From TBwiki
(Difference between revisions)
Jump to: navigation, search
(Again improving CDR doc by splitting into sections)
(→Information related to signaling)
 
(88 intermediate revisions by 11 users not shown)
Line 1: Line 1:
−
Text [[call detail record|call detail records]] (CDR) are saved in a log file on disk.
+
Text [[call detail record|call detail records]] (CDR) can be used on the [[TMG800]], [[TMG3200]] or [[TMG7800]]. The Call Detail Records are saved in a log file on a local disk. There is an entry done for each call leg, at the start of a call and at the end of the call. In addition, the system can be configured to update the CDRs periodically.
−
 
+
−
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.
 
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:
 
For example, the following variable will be replaced by the called number:
 
@{CalledNumber}
 
@{CalledNumber}
  
 +
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.
  
−
== 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 ==
 +
'''Refer to the appropriate Toolpack release:'''
 +
*[[Toolpack:Enabling_CDR_C|Web Portal v2.9, 2.10, 3.0: CDR configuration]]
 +
*[[Toolpack:Enabling_CDR_B|Web Portal v2.8: CDR configuration]]
 +
<div class="mw-collapsible mw-collapsed" data-collapsetext="other versions" data-expandtext="Click here for other versions" style="width: 400px;">
 +
*[[Toolpack:Enabling_CDR_A|Web Portal v2.7: CDR configuration]]
 +
*[[Toolpack:Enabling_RADIUS_A|Web Portal v2.6: CDR configuration]]
 +
</div>
  
−
== Configuration parameters  ==
+
== CDR Text Variables ==
 +
The following variables can be used to define the CDR log format in [[Parameter: CDR format (start)|CDR format (start)]], [[Parameter: CDR format (update)|CDR format (update)]] and [[Parameter: CDR format (end)|CDR format (end)]] configuration fields.
  
−
*'''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).
+
=== Variables used for identifying call (or call leg) in general ===
−
*'''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).
+
@{StatusType}:             Indicates the type of record ("Start", "Update" or "End").
−
*'''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).
+
  @{LegId}:                  Unique Id for this leg (32 bits value).
−
*'''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).
+
  @{OtherLegId}:            Id of the other call leg joined with current call leg.
−
*'''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.
+
  @{SessionId}:              Unique call identifier for two joined and answered call legs, including failed outgoing call attempts (route retry)
−
*'''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.
+
                            Formatted as 4 values of 32 bits, printed as 4 blocks of 8 hexadecimal characters separated by a space
−
 
+
                            Ex: a939d169 299ffcd0 00000000 00000000
−
== Available variables ==
+
                            Note: Call Transfer Target legs have separate SessionId. If you need an id to correlate a transferred call
−
The following variables exist and can be used to define the CDR log format.
+
                                  to the original call, use @{OriginalSessionId}.
−
 
+
                            Note: Toolpack 2.9 and above support globally unique SessionId (unique across separate TMedia systems)
−
=== Variables used for identifying call legs ===
+
  @{OriginalSessionId}:      Refers to @{SessionId} of the original legs for this call, in case of call transfer.
−
  *@{LegId}:                  Unique Id for this leg (32 bits value, but may eventually be upgraded to 64 bits value).
+
                            In fact, Transfer Target leg has a different value for @{SessionId}, but can be linked with the original call
−
  *@{OtherLegId}:            Id of the other call leg joined with current call leg.
+
                             legs through @{OriginalSessionId}.
−
  *@{SessionId}:              Unique call identifier, in the form of 4 values of 32 bits, printed as 4 blocks of 8 hexadecimal characters
+
  @{LinkId}:                Same meaning as @{OriginalSessionId}, but presented as a 32 bits integer value.
−
                            separated by a space (ex: a939d169 299ffcd0 00000000 00000000).
+
For all Ids above, please see [[Text_Call_Detail_Records_(CDR)#Known_limitations|Known Limitations]] below for notes about uniqueness of these values.
−
  *@{OriginalSessionId}:      Same as @{SessionId}, except that it remains identical after a call transfer, while @{SessionId} has
+
−
                             a new value for the Call Transfer Target leg.
+
−
  *@{LinkId}:                Id common to all call legs from the same call, including failed route retry attempts, and any call
+
−
                            leg involved in transfers through this call (32 bits value, but may eventually be upgraded to 64 bits value)
+
−
For all Ids above, please see "Known limitations" below for notes about uniqueness of these values.
+
  
 
=== Timestamps ===
 
=== Timestamps ===
−
  *@{ConnectedTime}:         Time where the call was answered (and connected with another leg) (in number of seconds since epoch)
+
  @{AlertTime}:             Time where the call has started ringing.
−
  *@{ConnectedTime:format}:   Same as @{ConnectedTime} but with custom print format (local time zone), using 'strftime' style, with added
+
                            Note: Supported on release 2.7 and up only.
 +
  @{AlertTime:format}:       Same as @{AlertTime} but with custom print format (local time zone), using 'strftime' style, with added
 
                             support for @m replaced by milliseconds.
 
                             support for @m replaced by milliseconds.
 
                             Example format: %Y-%m-%d %H:%M:%S.@m  -> 2009-09-02 12:16:24.333
 
                             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.
+
  @{ConnectedTime}:          Time where the call was answered (and connected with another leg) (in number of seconds since epoch)
−
  *@{EndTime}:                Time where the call has started terminating (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.
 +
  @{CallDuration}:          Call duration in seconds (not available in the "start" CDR log)
 +
                            Note: Supported on release 2.7 and up only.
 +
@{CallDurationMs}:        Call duration in milliseconds (end - connected time) (not available in the "start" CDR log)
 +
                            Note: Supported on release 2.7 and up only.
 +
@{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
 
                             Note that slightly differs from the @{Timestamp}, since the 'End' CDR trace is printed once the call has
 
                             finished terminating,
 
                             finished terminating,
 
                             while @{EndTime} reports the time where the call has started terminating (upon hangup for example).
 
                             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
+
  @{EndTime:format}:        Same as @{EndTime} but with custom print format (local time zone), using 'strftime' style, with added
 
                             support for @m replaced by milliseconds.
 
                             support for @m replaced by milliseconds.
 
                             Example format: %Y-%m-%d %H:%M:%S.@m  -> 2009-09-02 12:16:24.333
 
                             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.
+
  @{EndTimeUtc:format}:      Same as @{EndTime:format} but printed in UTC time, rather than local time zone.
−
  *@{StartTime}:              Time where the call was created (in number of seconds since epoch)
+
  @{RingingDuration}:        Ringing duration in seconds (connected - start time)
−
  *@{StartTime:format}:      Same as @{StartTime} but with custom print format (local time zone), using 'strftime' style, with added
+
                            Note: Supported on release 2.7 and up only.
 +
@{RingingDurationMs}:      Ringing duration in milliseconds (connected - start time)
 +
                            Note: Supported on release 2.7 and up only.
 +
@{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.
 
                             support for @m replaced by milliseconds.
 
                             Example format: %Y-%m-%d %H:%M:%S.@m  -> 2009-09-02 12:16:24.333
 
                             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.
+
  @{StartTimeUtc:format}:    Same as @{StartTime:format} but printed in UTC time, rather than local time zone.
−
  *@{Timestamp}:              Time where this CDR log entry was written.
+
  @{Timestamp}:              Time where this CDR log entry was written.
 
                             Should not be used for billing purposes. Use @{EndTime} for billing @{EndTime} reports the time where
 
                             Should not be used for billing purposes. Use @{EndTime} for billing @{EndTime} reports the time where
−
                             the call has started terminating (hangup), while *@{Timestamp} the time where signaling confirmed the termination.
+
                             the call has started terminating (hangup), while @{Timestamp} the time where signaling confirmed the termination.
−
  *@{Timestamp:format}:      Same as @{Timestamp} but with custom print format (local time zone), using 'strftime' style, with added
+
  @{Timestamp:format}:      Same as @{Timestamp} but with custom print format (local time zone), using 'strftime' style, with added
 
                             support for @m replaced by milliseconds.
 
                             support for @m replaced by milliseconds.
 
                             Example format: %Y-%m-%d %H:%M:%S.@m  -> 2009-09-02 12:16:24.333
 
                             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.
+
  @{TimestampUtc:format}:    Same as @{Timestamp:format} but printed in UTC time, rather than local time zone.
−
 
+
  
 
=== Information related to signaling ===
 
=== Information related to signaling ===
−
  *@{CalledNumber}:          Called number
+
  @{CalledNumber}:          Called number
−
  *@{CallingNumber}:          Calling number
+
  @{CallingNumber}:          Calling number
−
  *@{CallType}:              Call type ("Telephony" or "VOIP")
+
  @{CallingPresentation}:    Calling presentation: "Unspecified", "NotAvailable", "Allowed", "Restricted", "AddressRestricted" or "NameRestricted"
−
  *@{NAP}:                    Name of the NAP this call leg is from
+
                            Note: Supported on release 2.7 and up only.
−
  *@{OriginatorName}:        Direction of the call:
+
@{CallingSubscriberNumber}: Second calling number (ISDN), Generic number of type "additional calling party number" (SS7) and SIP P-asserted-identity, userinfo
 +
                            Note: Supported on release 2.7.43 and up only.
 +
@{CallType}:              Call type ("Telephony" or "VOIP")
 +
  @{IncomingNAP}:            Name of the NAP that originated this call (incoming call leg's NAP name).
 +
                            Note: Supported on release 2.7 and up only.
 +
@{NAP}:                    Name of the NAP this call leg is from
 +
  @{OriginatorName}:        Direction of the call:
 +
                              - "answer" (incoming call leg) - "originate" (outgoing call leg)
 +
                            Note: In release 2.6 and earlier, the direction of the call is as follows:
 
                               - "originate" (incoming call leg) - "answer" (outgoing call leg)
 
                               - "originate" (incoming call leg) - "answer" (outgoing call leg)
−
  *@{Protocol}:              Type of protocol used ("SS7", "ISDN", or "SIP")
+
                            In release 2.7, the CDR option "Reverse CDR call origin" in Gateway configuration provide the same values as in release 2.6.
−
  *@{TerminationCause}:      Cause of the call termination, printed as an integer value (refering enum TBCMC_CALL_REASON_CODE)
+
@{OriginalCalledNumber}:  Original called number
−
  *@{TerminationCauseString}: Cause of the call termination, printed as an string value
+
                            Note: Supported on release 2.7 and up only.
−
  *@{TerminationSource}:      Identifies which of the legs has initiated the call termination first: "LocalLeg" or "ConnectedLeg"
+
  @{Protocol}:              Type of protocol used ("SS7", "ISDN", or "SIP")
−
  *@{UserName}:              For SIP calls, name of the user.
+
  @{RedirectingNumber}:      Redirecting number
−
  *@{ChargeIndicator}:        For TDM (SS7 and CASR2); received charge indicator in Alert message.
+
                            Note: Supported on release 2.7 and up only.
 +
@{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 a string value
 +
  @{OriginalCause}:          Original cause of the call termination (before it was converted to protocol-specific cause for current call leg), printed as a string value (refering enum TBCMC_CALL_REASON_CODE)
 +
@{TerminationSource}:      Identifies the cause of the leg termination:
 +
                              - "TermInd":      Terminating indication has been received on this leg
 +
                              - "JoinedTermInd": Terminating indication has been received on the leg joined to current leg,
 +
                                                  and has been forwarded to current leg
 +
                              - "App":          Call control application has asked to drop the call
 +
                              - "Engine":        Toolpack engine has decided to terminate this call
 +
                                                  (generally due to local errors like disconnected TMedia)
 +
  @{UserName}:              Static value: 100.
 +
@{SipCallId}:              Content of the "call-id" SIP header
 +
  @{ChargeIndicator}:        For TDM (SS7 and CAS R2); received charge indicator in Alert message.
 +
@{LocalSipIP}:            For SIP calls, IP address locally used for this call leg.
 +
                            Note: Supported on release 3.0.70 and up only.
 +
@{LocalSipPort}:          For SIP calls, UDP port locally used for this call leg.
 +
                            Note: Supported on release 3.0.70 and up only.
 +
@{RemoteSipIP}:            For SIP calls, IP address of the remote peer for this call leg.
 +
                            Note: Supported on release 3.0.70 and up only.
 +
@{RemoteSipPort}:          For SIP calls, UDP port of the remote peer for this call leg.
 +
                            Note: Supported on release 3.0.70 and up only.
  
−
 
+
=== Information related to media ===
−
=== Information related to media, and others ===
+
  @{Codec}:                 Codec used for this call ("G711" for example)
−
  *@{ApplicationName}:       Name of the application that has written this log ("Gateway")
+
  @{LocalMediaInfo}:         Protocol type dependent information on the call leg (local information for SIP calls).
−
  *@{Codec}:                 Codec used for this call ("G711" for example)
+
                            For TDM (Telephony) calls (SS7 or ISDN): "trunk_name:timeslot_nb".
−
  *@{MediaInfo}:             Protocol type dependent information on the call leg.
+
                            For VOIP calls (SIP): "codec@ip:port"  (IP and Port locally used for receiving RTP)
 +
  @{LocalMediaIP}:           For VOIP calls, RTP IP address locally used for this call leg.
 +
@{LocalMediaPort}:        For VOIP calls, RTP UDP port locally used for this call leg.
 +
@{RemoteMediaInfo}:        Protocol type dependent information on the call leg (remote information SIP calls).
 
                             For TDM (Telephony) calls (SS7 or ISDN): "trunk_name:timeslot_nb".
 
                             For TDM (Telephony) calls (SS7 or ISDN): "trunk_name:timeslot_nb".
−
                             For VOIP calls (SIP): "codec@ip:port"
+
                             For VOIP calls (SIP): "codec@ip:port" (IP and Port TMedia is sending RTP to)
−
  *@{RemoteIP}:               For VOIP calls, RTP IP address of the remote peer for this call leg.
+
  @{RemoteMediaIP}:         For VOIP calls, RTP IP address of the remote peer for this call leg.
−
  *@{RemotePort}:             For VOIP calls, RTP UDP port of the remote peer for this call leg.
+
  @{RemoteMediaPort}:       For VOIP calls, RTP UDP port of the remote peer for this call leg.
−
  *@{TimeslotNumber}:        For TDM (Telephony) calls, timeslot number that this call was using for audio.
+
  @{TimeslotNumber}:        For TDM (Telephony) calls, timeslot number that this call was using for audio.
−
  *@{TrunkName}:              For TDM (Telephony) calls, name of the trunk that this call was using for audio.
+
  @{TrunkName}:              For TDM (Telephony) calls, name of the trunk that this call was using for audio.
  
−
== Known limitations ==
+
=== Statistics ===
−
The following values may not be unique due to following limitations:
+
The call statistics variable allow to print RTP, RTCP and T38 statistics in the text CDR logs.
−
* @{LegId}
+
* Available '''only in the "end" CDR entry'''
−
* @{OtherLegId}
+
* Available in release '''2.7.103''' and above only
−
* @{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 ==
+
Example:
 +
* Pkt=@{Stat:Rtp:Rx:Packets}/@{Stat:Rtp:Tx:Packets}, Err=@{Stat:Rtp:Rx:Errors}/@{Stat:Rtp:Tx:Errors}
  
−
In a redundant Toolpack system with two Gateway applications, the active Gateway application writes the CDR logs.
+
Refer to the following pages for the list of statistics:
 +
* [[Call_statistics_format_C|Call statistics format for Toolpack 3.0 or later]]
 +
* [[Call_statistics_format_B|Call statistics format for Toolpack 2.9 or 2.10]]
 +
* [[Call_statistics_format_A|Call statistics format for Toolpack 2.8]]
 +
* [[Call_statistics_format_A|Call statistics format for Toolpack 2.7.103 or later]]
  
−
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.
+
===  Information related to routing ===
 +
@{ApplicationName}:        Name of the application that has written this log ("Gateway")
 +
@{RouteAttribute:attr}:    Replaced by the value of a custom route attribute, for the selected
 +
                            route. This will apply only to outgoing call legs that were made from routing.
 +
                            Eligible route attributes are:
 +
                                Route name:                    Use attribute "route_name". Ex: @{RouteAttribute:route_name}
 +
                                Route set name:                Use attribute "routeset_name". Ex: @{RouteAttribute:routeset_name}
 +
                                Custom route attribute column: Use the custom attribute name. Ex: @{RouteAttribute:priority}
 +
                                Routing script parameters:    Use the route attribute name provided by routing script.
 +
                                                              Ex: If script provides: route[:my_param]="myval"
 +
                                                                  Then it's included in CDR with @{RouteAttribute:my_param}]
 +
                            ***** Important note:  This parameter cannot be retrieved after a switchover of the active to
 +
                                                    the standby Toolpack host.
 +
                                                    It's thus recommended to insert this information in the "Start" CDR entry,
 +
                                                    rather than the "End" CDR entry.
 +
@{ScriptAttribute:attr}:  Replaced by the value of a routing script attribute stored in params[:bridge].
 +
                            This will apply for incoming and outgoing call legs.
 +
                            Eligible script attributes are:
 +
                                Custom CDR value:              Use attribute "CustomCdrValue". Ex: @{ScriptAttribute:CustomCdrValue}
 +
                                Script parameters:            Use the attribute name provided by routing script.
 +
                                                              Ex: If script provides: params[:bridge][:my_param]="myval"
 +
                                                                  Then it's included in CDR with @{ScriptAttribute:my_param}
 +
                            ***** Important note:  This parameter cannot be retrieved after a switchover of the active to
 +
                                                    the standby Toolpack host.
 +
                                                    It's thus recommended to insert this information in the "Start" CDR entry,
 +
                                                    rather than the "End" CDR entry.
  
−
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.
+
=== Deprecated values: ===
 +
@{MediaInfo}:              Same as @{RemoteMediaInfo}
 +
@{RemoteIP}:              Same as @{RemoteMediaIP}
 +
@{RemotePort}:            Same as @{RemoteMediaPort}
  
 +
== CDR sample ==
 +
=== Call sample with Start and End records ===
 +
  2013-02-07 10:19:04.640-0500,BEG,SessionId='f2685706 00000000 00000000 00000000',LegId='0xF2685706',StartTime='1360250341',ConnectedTime='1360250344',Calling='',Called='123',NAP='NAP_SIP',Protocol='SIP',Direction='answer'
 +
  2013-02-07 10:19:04.640-0500,BEG,SessionId='f2685706 00000000 00000000 00000000',LegId='0x72685C1F',StartTime='1360250344',ConnectedTime='1360250344',Calling='',Called='123',NAP='NAP_SIP2',Protocol='SIP',Direction='originate'
 +
  2013-02-07 10:19:07.562-0500,END,SessionId='f2685706 00000000 00000000 00000000',LegId='0x72685C1F',StartTime='1360250344',ConnectedTime='1360250344',EndTime='1360250347',FreedTime='1360250347',TerminationCause='TOOLPACK_NORMAL',TerminationSource='App',Calling='',Called='123',NAP='NAP_SIP2',Direction='originate'
 +
  2013-02-07 10:19:07.656-0500,END,SessionId='f2685706 00000000 00000000 00000000',LegId='0xF2685706',StartTime='1360250341',ConnectedTime='1360250344',EndTime='1360250347',FreedTime='1360250347',TerminationCause='TOOLPACK_NORMAL',Termination Source='App',Calling='',Called='123',NAP='NAP_SIP',Direction='answer'
  
−
== Default values  ==
+
== Redundancy ==
  
−
The default values are as follows:
+
In a [[TMG7800]] configuration, with redundant TMG-Control servers, or [[TMG3200]]/[[TMG800]] in 1+1 configuration, only the active server writes the CDR logs. Since the active server may change over time, CDR parsing must take into account that CDR logs may be found in files from the two servers.
  
−
<br> For the CDR that is printed when the call leg is answered:
 
  
−
@{Timestamp:%Y-%m-%d&nbsp;%H:%M:%S.@m%z},BEG,SessionId='@{SessionId}',LegId='@{LegId}',
+
The analysis of the logs for the purpose of extracting billing information must be done after combining the two logs, from both TMG-Control servers, sorting the entries by timestamp for example. See how to [[TMG:Retrieve_Text_CDR|Retrieve Text CDR here]].
−
StartTime='@{StartTime}',ConnectedTime='@{ConnectedTime}',Calling='@{CallingNumber}',
+
−
Called='@{CalledNumber}',NAP='@{NAP}',Protocol='@{Protocol}',Direction='@{OrginatorName}'
+
  
−
(Note: the above is a signle line!)<br>
+
== CDR entry loss due to switchover ==
 +
In some situations (during HA switchover for example), some CDR entries may be lost.
  
 +
The following guide lines provide information on how to deal with these corner cases:
  
 +
[[Call_Detail_Records_Entry_Loss|Deal with CDR entries loss]]
  
−
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&nbsp;%H:%M:%S.@m%z}: SessionId='@{SessionId}' LegId='@{LegId}'
+
== Retrieving Text CDRs ==
  
−
For the CDR that is printed when the call leg is terminated:
+
There are 2 ways to retrieve the text CDR manually or automatically. The procedures are described in [[TMG:Retrieve_Text_CDR|Retrieve Text CDR]].
−
 
+
−
@{Timestamp:%Y-%m-%d&nbsp;%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}'
+
−
 
+
−
<br>
+
−
 
+
−
(Note: the above is a signle line!)<br>
+
−
 
+
−
== 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 [[TMG:Retrieve_Text_CDR|here]].
+
  
 
== Notes ==
 
== 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).
+
*This mode of operation is not recommended for [[TMG800]] or [[TMG3200]] with a flash disk (last shipment January 2011). However, the [[TMG800]] or [[TMG3200]] with SATA or SSD disk option is OK (use command [[Get Product Type|tbinfo]]: if the command can be executed, the disk is SATA or SSD).
 
*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.
 
*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.
 +
 +
[[Category:Revise on Major]]

Latest revision as of 10:47, 19 December 2019

Text call detail records (CDR) can be used on the TMG800, TMG3200 or TMG7800. The Call Detail Records are saved in a log file on a local disk. There is an entry done for each call leg, at the start of a call and at the end of the call. In addition, the system can be configured to update the CDRs periodically.

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}

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.


Contents

Configuration

Refer to the appropriate Toolpack release:

CDR Text Variables

The following variables can be used to define the CDR log format in CDR format (start), CDR format (update) and CDR format (end) configuration fields.

Variables used for identifying call (or call leg) in general 

@{StatusType}:             Indicates the type of record ("Start", "Update" or "End").
@{LegId}:                  Unique Id for this leg (32 bits value).
@{OtherLegId}:             Id of the other call leg joined with current call leg.
@{SessionId}:              Unique call identifier for two joined and answered call legs, including failed outgoing call attempts (route retry)
                            Formatted as 4 values of 32 bits, printed as 4 blocks of 8 hexadecimal characters separated by a space
                            Ex: a939d169 299ffcd0 00000000 00000000
                            Note: Call Transfer Target legs have separate SessionId. If you need an id to correlate a transferred call
                                  to the original call, use @{OriginalSessionId}.
                            Note: Toolpack 2.9 and above support globally unique SessionId (unique across separate TMedia systems)
@{OriginalSessionId}:      Refers to @{SessionId} of the original legs for this call, in case of call transfer.
                            In fact, Transfer Target leg has a different value for @{SessionId}, but can be linked with the original call
                            legs through @{OriginalSessionId}.
@{LinkId}:                 Same meaning as @{OriginalSessionId}, but presented as a 32 bits integer value.

For all Ids above, please see Known Limitations below for notes about uniqueness of these values.

Timestamps 

@{AlertTime}:              Time where the call has started ringing.
                            Note: Supported on release 2.7 and up only.
@{AlertTime:format}:       Same as @{AlertTime} 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
@{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.
@{CallDuration}:           Call duration in seconds (not available in the "start" CDR log)
                            Note: Supported on release 2.7 and up only.
@{CallDurationMs}:         Call duration in milliseconds (end - connected time) (not available in the "start" CDR log)
                            Note: Supported on release 2.7 and up only.
@{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.
@{RingingDuration}:        Ringing duration in seconds (connected - start time)
                            Note: Supported on release 2.7 and up only.
@{RingingDurationMs}:      Ringing duration in milliseconds (connected - start time)
                            Note: Supported on release 2.7 and up only.
@{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.
@{Timestamp}:              Time where this CDR log entry was written.
                            Should not be used for billing purposes. Use @{EndTime} for billing @{EndTime} reports the time where
                            the call has started terminating (hangup), while @{Timestamp} the time where signaling confirmed the termination.
@{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.

Information related to signaling 

@{CalledNumber}:           Called number
@{CallingNumber}:          Calling number
@{CallingPresentation}:    Calling presentation: "Unspecified", "NotAvailable", "Allowed", "Restricted", "AddressRestricted" or "NameRestricted"
                            Note: Supported on release 2.7 and up only.
@{CallingSubscriberNumber}: Second calling number (ISDN), Generic number of type "additional calling party number" (SS7) and SIP P-asserted-identity, userinfo
                            Note: Supported on release 2.7.43 and up only.
@{CallType}:               Call type ("Telephony" or "VOIP")
@{IncomingNAP}:            Name of the NAP that originated this call (incoming call leg's NAP name).
                            Note: Supported on release 2.7 and up only.
@{NAP}:                    Name of the NAP this call leg is from
@{OriginatorName}:         Direction of the call:
                             - "answer" (incoming call leg) - "originate" (outgoing call leg)
                            Note: In release 2.6 and earlier, the direction of the call is as follows:
                             - "originate" (incoming call leg) - "answer" (outgoing call leg)
                            In release 2.7, the CDR option "Reverse CDR call origin" in Gateway configuration provide the same values as in release 2.6.
@{OriginalCalledNumber}:   Original called number
                            Note: Supported on release 2.7 and up only.
@{Protocol}:               Type of protocol used ("SS7", "ISDN", or "SIP")
@{RedirectingNumber}:      Redirecting number
                            Note: Supported on release 2.7 and up only.
@{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 a string value
@{OriginalCause}:          Original cause of the call termination (before it was converted to protocol-specific cause for current call leg), printed as a string value (refering enum TBCMC_CALL_REASON_CODE)
@{TerminationSource}:      Identifies the cause of the leg termination:
                              - "TermInd":       Terminating indication has been received on this leg
                              - "JoinedTermInd": Terminating indication has been received on the leg joined to current leg,
                                                 and has been forwarded to current leg
                              - "App":           Call control application has asked to drop the call
                              - "Engine":        Toolpack engine has decided to terminate this call
                                                 (generally due to local errors like disconnected TMedia)
@{UserName}:               Static value: 100.
@{SipCallId}:              Content of the "call-id" SIP header
@{ChargeIndicator}:        For TDM (SS7 and CAS R2); received charge indicator in Alert message.
@{LocalSipIP}:             For SIP calls, IP address locally used for this call leg.
                            Note: Supported on release 3.0.70 and up only.
@{LocalSipPort}:           For SIP calls, UDP port locally used for this call leg.
                            Note: Supported on release 3.0.70 and up only.
@{RemoteSipIP}:            For SIP calls, IP address of the remote peer for this call leg.
                            Note: Supported on release 3.0.70 and up only.
@{RemoteSipPort}:          For SIP calls, UDP port of the remote peer for this call leg.
                            Note: Supported on release 3.0.70 and up only.

Information related to media 

@{Codec}:                  Codec used for this call ("G711" for example)
@{LocalMediaInfo}:         Protocol type dependent information on the call leg (local information for SIP calls).
                            For TDM (Telephony) calls (SS7 or ISDN): "trunk_name:timeslot_nb".
                            For VOIP calls (SIP): "codec@ip:port"  (IP and Port locally used for receiving RTP)
@{LocalMediaIP}:           For VOIP calls, RTP IP address locally used for this call leg.
@{LocalMediaPort}:         For VOIP calls, RTP UDP port locally used for this call leg.
@{RemoteMediaInfo}:        Protocol type dependent information on the call leg (remote information SIP calls).
                            For TDM (Telephony) calls (SS7 or ISDN): "trunk_name:timeslot_nb".
                            For VOIP calls (SIP): "codec@ip:port"  (IP and Port TMedia is sending RTP to)
@{RemoteMediaIP}:          For VOIP calls, RTP IP address of the remote peer for this call leg.
@{RemoteMediaPort}:        For VOIP calls, RTP UDP port of the remote peer for this call leg.
@{TimeslotNumber}:         For TDM (Telephony) calls, timeslot number that this call was using for audio.
@{TrunkName}:              For TDM (Telephony) calls, name of the trunk that this call was using for audio.

Statistics

The call statistics variable allow to print RTP, RTCP and T38 statistics in the text CDR logs.

  • Available only in the "end" CDR entry
  • Available in release 2.7.103 and above only

Example:

  • Pkt=@{Stat:Rtp:Rx:Packets}/@{Stat:Rtp:Tx:Packets}, Err=@{Stat:Rtp:Rx:Errors}/@{Stat:Rtp:Tx:Errors}

Refer to the following pages for the list of statistics:

Information related to routing 

@{ApplicationName}:        Name of the application that has written this log ("Gateway")
@{RouteAttribute:attr}:    Replaced by the value of a custom route attribute, for the selected
                            route. This will apply only to outgoing call legs that were made from routing.
                            Eligible route attributes are:
                               Route name:                    Use attribute "route_name". Ex: @{RouteAttribute:route_name}
                               Route set name:                Use attribute "routeset_name". Ex: @{RouteAttribute:routeset_name}
                               Custom route attribute column: Use the custom attribute name. Ex: @{RouteAttribute:priority}
                               Routing script parameters:     Use the route attribute name provided by routing script.
                                                              Ex: If script provides: route[:my_param]="myval"
                                                                  Then it's included in CDR with @{RouteAttribute:my_param}]
                            ***** Important note:   This parameter cannot be retrieved after a switchover of the active to
                                                    the standby Toolpack host.
                                                    It's thus recommended to insert this information in the "Start" CDR entry,
                                                    rather than the "End" CDR entry.
@{ScriptAttribute:attr}:   Replaced by the value of a routing script attribute stored in params[:bridge].
                            This will apply for incoming and outgoing call legs.
                            Eligible script attributes are:
                               Custom CDR value:              Use attribute "CustomCdrValue". Ex: @{ScriptAttribute:CustomCdrValue}
                               Script parameters:             Use the attribute name provided by routing script.
                                                              Ex: If script provides: params[:bridge][:my_param]="myval"
                                                                  Then it's included in CDR with @{ScriptAttribute:my_param}
                            ***** Important note:   This parameter cannot be retrieved after a switchover of the active to
                                                    the standby Toolpack host.
                                                    It's thus recommended to insert this information in the "Start" CDR entry,
                                                    rather than the "End" CDR entry.

Deprecated values: 

@{MediaInfo}:              Same as @{RemoteMediaInfo}
@{RemoteIP}:               Same as @{RemoteMediaIP}
@{RemotePort}:             Same as @{RemoteMediaPort}

CDR sample

Call sample with Start and End records 

 2013-02-07 10:19:04.640-0500,BEG,SessionId='f2685706 00000000 00000000 00000000',LegId='0xF2685706',StartTime='1360250341',ConnectedTime='1360250344',Calling=,Called='123',NAP='NAP_SIP',Protocol='SIP',Direction='answer' 
 2013-02-07 10:19:04.640-0500,BEG,SessionId='f2685706 00000000 00000000 00000000',LegId='0x72685C1F',StartTime='1360250344',ConnectedTime='1360250344',Calling=,Called='123',NAP='NAP_SIP2',Protocol='SIP',Direction='originate' 
 2013-02-07 10:19:07.562-0500,END,SessionId='f2685706 00000000 00000000 00000000',LegId='0x72685C1F',StartTime='1360250344',ConnectedTime='1360250344',EndTime='1360250347',FreedTime='1360250347',TerminationCause='TOOLPACK_NORMAL',TerminationSource='App',Calling=,Called='123',NAP='NAP_SIP2',Direction='originate' 
 2013-02-07 10:19:07.656-0500,END,SessionId='f2685706 00000000 00000000 00000000',LegId='0xF2685706',StartTime='1360250341',ConnectedTime='1360250344',EndTime='1360250347',FreedTime='1360250347',TerminationCause='TOOLPACK_NORMAL',Termination Source='App',Calling=,Called='123',NAP='NAP_SIP',Direction='answer'

Redundancy

In a TMG7800 configuration, with redundant TMG-Control servers, or TMG3200/TMG800 in 1+1 configuration, only the active server writes the CDR logs. Since the active server may change over time, CDR parsing must take into account that CDR logs may be found in files from the two servers.


The analysis of the logs for the purpose of extracting billing information must be done after combining the two logs, from both TMG-Control servers, sorting the entries by timestamp for example. See how to Retrieve Text CDR here.

CDR entry loss due to switchover

In some situations (during HA switchover for example), some CDR entries may be lost.

The following guide lines provide information on how to deal with these corner cases:

Deal with CDR entries loss


Retrieving Text CDRs

There are 2 ways to retrieve the text CDR manually or automatically. The procedures are described in Retrieve Text CDR.

Notes

  • This mode of operation is not recommended for TMG800 or TMG3200 with a flash disk (last shipment January 2011). However, the TMG800 or TMG3200 with SATA or SSD disk option is OK (use command tbinfo: if the command can be executed, the disk is SATA or SSD).
  • 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.
Retrieved from "https://docs.telcobridges.com/mediawiki/index.php?title=Text_Call_Detail_Records&oldid=27912"
Personal tools