Cisco CUCM CDR (Call Detail Record) App

Cisco CUCM CDR (Call Detail Record) is a logging feature of Cisco Unified Communications Manager (CUCM) that provides detailed information about call activity within an organization's telephony system. CDRs capture important metadata about each call, including caller/callee numbers, call duration, timestamps, device information, and call routing details. This app enables LogZilla to ingest, parse, and analyze these records, providing valuable insights into call patterns, troubleshooting capabilities for voice quality issues, and support for compliance requirements.

Required: CDR Loader

Please note that the CDR Loader tool must be deployed on a machine with access to the directory where Cisco Call Manager writes the CDR (and CMR) files. This utility is a vital component of the solution and detailed implementation instructions are provided in the CDR Loader Implementation Guide section.

App Function

This app processes Cisco CDR and CMR messages generated by the Cisco Unified Communications Manager system. These messages are transmitted to the LogZilla server via an auxiliary CDR loader program. The LogZilla server then parses the CDR data and assigns various user tags based on the administrator's configuration settings.

Vendor Documentation

Incoming Log Format

Cisco CDR logs are generated as comma-separated files by the Cisco Unified Call Manager system. The CDR Loader program monitors these files, processes each csv (comma-separated value) row, and transmits the data to LogZilla in JSON format.

Parsed Metadata Fields

This app allows administrators to customize the user tag names that correspond to fields in the CDR log messages. By default, user tags inherit the same names as the original field names. The following tables display the default field (and user tag) names, first showing all available CDR fields, followed by a list of fields that are recorded by LogZilla by default. These settings can be customized for each LogZilla deployment.

All CDR Fields

CDR Field Name
`cdrRecordType`
`globalCallID_callManagerId`
`globalCallID_callId`
`origLegCallIdentifier`
`dateTimeOrigination`
`origNodeId`
`origSpan`
`origIpAddr`
`callingPartyNumber`
`callingPartyUnicodeLoginUserID`
`origCause_location`
`origCause_value`
`origPrecedenceLevel`
`origMediaTransportAddress_IP`
`origMediaTransportAddress_Port`
`origMediaCap_payloadCapability`
`origMediaCap_maxFramesPerPacket`
`origMediaCap_g723BitRate`
`origVideoCap_Codec`
`origVideoCap_Bandwidth`
`origVideoCap_Resolution`
`origVideoTransportAddress_IP`
`origVideoTransportAddress_Port`
`origRSVPAudioStat`
`origRSVPVideoStat`
`destLegIdentifier`
`destNodeId`
`destSpan`
`destIpAddr`
`originalCalledPartyNumber`
`finalCalledPartyNumber`
`finalCalledPartyUnicodeLoginUserID`
`destCause_location`
`destCause_value`
`destPrecedenceLevel`
`destMediaTransportAddress_IP`
`destMediaTransportAddress_Port`
`destMediaCap_payloadCapability`
`destMediaCap_maxFramesPerPacket`
`destMediaCap_g723BitRate`
`destVideoCap_Codec`
`destVideoCap_Bandwidth`
`destVideoCap_Resolution`
`destVideoTransportAddress_IP`
`destVideoTransportAddress_Port`
`destRSVPAudioStat`
`destRSVPVideoStat`
`dateTimeConnect`
`dateTimeDisconnect`
`lastRedirectDn`
`pkid`
`originalCalledPartyNumberPartition`
`callingPartyNumberPartition`
`finalCalledPartyNumberPartition`
`lastRedirectDnPartition`
`duration`
`origDeviceName`
`destDeviceName`
`origCallTerminationOnBehalfOf`
`destCallTerminationOnBehalfOf`
`origCalledPartyRedirectOnBehalfOf`
`lastRedirectRedirectOnBehalfOf`
`origCalledPartyRedirectReason`
`lastRedirectRedirectReason`
`destConversationId`
`globalCallId_ClusterID`
`joinOnBehalfOf`
`comment`
`authCodeDescription`
`authorizationLevel`
`clientMatterCode`
`origDTMFMethod`
`destDTMFMethod`
`callSecuredStatus`
`origConversationId`
`origMediaCap_Bandwidth`
`destMediaCap_Bandwidth`
`authorizationCodeValue`
`outpulsedCallingPartyNumber`
`outpulsedCalledPartyNumber`
`origIpv4v6Addr`
`destIpv4v6Addr`
`origVideoCap_Codec_Channel2`
`origVideoCap_Bandwidth_Channel2`
`origVideoCap_Resolution_Channel2`
`origVideoTransportAddress_IP_Channel2`
`origVideoTransportAddress_Port_Channel2`
`origVideoChannel_Role_Channel2`
`destVideoCap_Codec_Channel2`
`destVideoCap_Bandwidth_Channel2`
`destVideoCap_Resolution_Channel2`
`destVideoTransportAddress_IP_Channel2`
`destVideoTransportAddress_Port_Channel2`
`destVideoChannel_Role_Channel2`
`IncomingProtocolID`
`IncomingProtocolCallRef`
`OutgoingProtocolID`
`OutgoingProtocolCallRef`
`currentRoutingReason`
`origRoutingReason`
`lastRedirectingRoutingReason`
`huntPilotPartition`
`huntPilotDN`
`calledPartyPatternUsage`
`IncomingICID`
`IncomingOrigIOI`
`IncomingTermIOI`
`OutgoingICID`
`OutgoingOrigIOI`
`OutgoingTermIOI`
`outpulsedOriginalCalledPartyNumber`
`outpulsedLastRedirectingNumber`
`wasCallQueued`
`totalWaitTimeInQueue`
`callingPartyNumber_uri`
`originalCalledPartyNumber_uri`
`finalCalledPartyNumber_uri`
`lastRedirectDn_uri`
`mobileCallingPartyNumber`
`finalMobileCalledPartyNumber`
`origMobileDeviceName`
`destMobileDeviceName`
`origMobileCallDuration`
`destMobileCallDuration`
`mobileCallType`
`originalCalledPartyPattern`
`finalCalledPartyPattern`
`lastRedirectingPartyPattern`
`huntPilotPattern`
`origDeviceType`
`destDeviceType`
`origDeviceSessionID`
`destDeviceSessionID`

Recorded CDR Fields

CDR Field Name
`globalCallID_callId`
`dateTimeOrigination`
`duration`
`callingPartyNumber`
`originalCalledPartyNumber`
`finalCalledPartyNumber`
`origDeviceName`
`destDeviceName`
`origIpv4v6Addr`
`destIpv4v6Addr`
`origCause_value`
`destCause_value`

Log Examples

{
    "callingPartyNumber_uri": "",
    "destDeviceSessionID": "b304f5966fdbf2cd7d4a90ab95954783",
    "destDeviceType": "",
    "destMobileCallDuration": "5",
    "destMobileDeviceName": "",
    "FACILITY": "user",
    "finalCalledPartyNumber_uri": "",
    "finalCalledPartyPattern": "+0617XXXXXXX",
    "finalMobileCalledPartyNumber": "",
    "HOST": "LZ-6499-cisco-cdr-logzilla",
    "huntPilotPattern": "",
    "lastRedirectDn_uri": "",
    "lastRedirectingPartyPattern": "+49694262658",
    "MESSAGE": "7,98,7755172,361204278,9254213996,24,302812243,-641624020,\"+84511067045\",\"\",0,7,0,6179308642,46752,3,31,1,4,4,0,3,8,\"5\",\"8\",101519798,64,729754582,0519742610,\"+36666796847\",\"+91386543881\",\"\",9,57,0,853835537,92728,2,73,5,4,6,8,2,0,\"2\",\"6\",0998253486,7756278605,\"+94319865977\",\"961f4a26-7ba1-3068-3eaf-5db690244005\",\"E584-GDPR-Learned-DN-PT\",\"\",\"WAFRSMC-PSTN-Local-PT\",\"E902-GDPR-Learned-DN-PT\",984,\"SME-Trunk\",\"SME-Trunk\",7,73,9,7,22,03,8,\"c1422ccm-AMER-CL9\",3,\"\",\"\",1,\"\",1,3,4,4,61,57,\"\",\"\",\"\",\"90.223.73.09\",\"737.034.974.59\",8,7,4,3,1,5,0,0,6,7,9,6,7,\"A717E193186939641059FFD6D491A930\",5,\"A420E2702388649982648B80FA75A896\",5,2,1,\"\",\"\",3,\"\",\"\",\"\",\"\",\"\",\"\",\"\",\"\",9,7,\"\",\"\",\"\",\"\",\"\",\"\",\"\",\"\",5,5,9,\"+07879622762\",\"+2267XXXXXXX\",\"+20582558326\",\"\",\"\",\"\",\"111ba8f3ab8e866d76a51bab80275849\",\"b030f1517fdbf4cd8d4a64ab84669617\""
}

LogZilla Configuration

The app's configuration is managed through a dedicated configuration file located at /etc/logzilla/apps/cisco_cdr/config/cisco-cdr-config.yaml. This file is structured into four primary sections: HOST_SOURCE, DESIRED_FIELDS, CAUSE_LOOKUP_FIELDS, and CAUSE_MAPPING.

`HOST_SOURCE`

Each LogZilla log entry includes a "host" field that identifies the source of the log. For this application, the host value can be derived from any column in the CDR file. By default, the origDeviceName field is used as the source.

`DESIRED_FIELDS`

CDR files contain numerous columns and fields, but typically only a subset are relevant for analysis. LogZilla captures only the fields of interest as specified in this section. Administrators can configure which columns from the CDR file should be recorded by LogZilla.

`CAUSE_LOOKUP_FIELDS`

Certain CDR columns contain numeric values that reference specific "causes" or reasons. This section identifies which CDR columns contain these reference numbers. The application processes these columns and enhances the LogZilla log entries with additional user tags containing the textual "Description" and "Disposition" that correspond to each cause number.

`CAUSE_MAPPING`

This section defines the mappings between cause numbers (referenced in the CAUSE_LOOKUP_FIELDS section) and their corresponding Descriptions and Dispositions. If new causes are added to the Cisco Call Manager system, this section can be modified to incorporate the appropriate textual descriptions.

CDR Loader Implementation Guide for System Administrators

Overview

The CDR Loader application is designed to process CDR and CMR files generated by Cisco Call Manager systems and transmit these call logs to a LogZilla server for analysis.

This document outlines the procedures for deploying the CDR Loader using Docker Compose. The deployment can be performed on either the LogZilla server itself or on a separate system, provided that Docker is installed and access to the CDR and CMR file directories is available.

Prerequisites

Prior to implementation, the following requirements should be verified:

Note: The CDR Loader may be deployed on the LogZilla server or a separate server. The selected server must meet all requirements below.

Docker: Docker and Docker Compose (plugin) must be installed on the target deployment server.
File System Access: Access to directories containing CDR and CMR files must be established.
Network Connectivity: Network access between the deployment server and the LogZilla server must be confirmed (the LogZilla server should be reachable via a URL in the format http://[hostname or IP]/incoming).

LogZilla Server Configuration

A valid LogZilla authentication token is required for CDR Loader operation. If a token has not been created or is unknown, instructions for token management can be found in the Appendix A section of this document.

The Cisco CDR application must be installed on the LogZilla server through the following procedure:

Navigate to the Settings menu in the LogZilla web interface
Select App Store
Click Add
Choose Cisco CDR
Click Install

Upon successful installation, a confirmation message will be displayed in the top-right corner of the interface. The LogZilla dashboard can be returned to by clicking the LogZilla logo in the top-left of the screen.

Docker Compose Configuration

This file must be customized for the specific deployment environment. Create the file on the server using a preferred text editor such as vi or nano.

Sample `docker-compose.yaml` file for CDR Loader deployment

In the example below:

The CDR and CMR files are stored on the local server in the /local/path/to/cdr_files and /local/path/to/cmr_files directories, respectively.
The LogZilla server is located at http://logzilla.corp.com/incoming and the authentication token is ingest-4cb844da7e91387890ebc27cf4982f57037b746a910927de.

services:
  cdr-loader:
    container_name: cdr_loader
    image: logzilla/runtime:latest
    volumes:
      - /local/path/to/cdr_files:/data/cdr
      - /local/path/to/cmr_files:/data/cmr
    command: >
      python3 /usr/lib/logzilla/bin/cdr-loader.py
      --cdr-directory /data/cdr
      --cmr-directory /data/cmr
      --logzilla-url http://logzilla.corp.com/incoming
      --logzilla-token ingest-4cb844da7e91387890ebc27cf4982f57037b746a910927de
      --max-batch-size 100
      --max-batch-time 5
      --cdr-delay 15
      --cmr-delay 5
      --call-delay 60
      --monitor-interval 10

# Optional flags that may be appended:
# --debug
# --delete-processed
# --collect-stats
# --emulate
# --emulation-speed 1.0
# --bad-record-file /path/to/bad/records.yaml

The following parameters in the docker-compose.yaml file must be configured:

Parameter	Default	Description
--logzilla-url, -U	N/A	URL for LogZilla data submission
--logzilla-token, -t	N/A	Authentication token for LogZilla

The following parameters may remain at their default values unless specific requirements dictate otherwise:

Parameter	Default	Description
--delete-processed, -D	False	CDR/CMR files removal after processing
--max-batch-size, -S	100	Maximum event count per batch
--max-batch-time, -T	5	Maximum batching wait time (seconds)
--cdr-delay	15	Delay before CDR file processing (seconds)
--cmr-delay	5	Delay before CMR file processing (seconds)
--bad-record-file	N/A	Destination file for invalid records
--call-delay	60	Delay before call completion determination (seconds)
--monitor-interval	0	Queue size monitoring interval (0 disables monitoring)

The following parameters are intended for docker compose, and should not be modified. They will not vary to match your environment.

Parameter	Default	Description
--cdr-directory, --cdr	N/A	Internal container directory for CDR files
--cmr-directory, --cmr	N/A	Internal container directory for CMR files

Special operation modes

Special operation modes can be enabled through the following parameters. These are only intended for testing and development purposes and should be disabled in production environments.

The collect-stats mode is utilized for statistical analysis of call data in the specified directories:

Parameter	Default	Description
--collect-stats, -s	False	Collection and output of CDR file statistics

The emulate mode is intended for technical diagnostics and should only be enabled when specifically instructed:

Parameter	Default	Description
--emulate, -e	False	Emulation of file processing
--emulation-speed	1.0	Emulation speed factor (e.g., 2.0 is twice normal)

Shared Directory Configuration

In deployments where CDR and CMR files are stored in the same directory, the Docker Compose configuration must be adjusted. The following modifications should be made to the docker-compose.yaml file:

The CMR directory mount line should be removed:
Remove:
- /local/path/to/cmr_files:/data/cmr
The CMR directory parameter should be updated:
Change:
--cmr-directory /data/cmr
To:
--cmr-directory /data/cdr

Docker Compose Operations

After the docker-compose.yaml file has been created, Docker Compose can be utilized to manage the CDR Loader container.

Note: All Docker Compose commands must be executed from within the directory containing the docker-compose.yaml file as specified in the configuration section.

Container Initialization

To start the container in detached mode (background execution), the following command should be executed:

docker compose up -d

Container Status Verification

To verify the container's operational status, the following command should be used:

docker compose ps

Log Monitoring

The logs for the CDR Loader container can be viewed using the docker compose logs command.

docker compose logs -n 50 -f cdr-loader

The -n flag is used to get the last 50 lines of the file.

The -f flag enables continuous log monitoring, providing real-time output observation.

Container Termination

To stop the container, the following command should be executed:

docker compose stop

If container removal (including the default network) is desired after termination, the following command may be used:

docker compose down

Troubleshooting

If issues are encountered, add the --debug flag to the command in the docker-compose.yaml file to enable detailed logging for diagnostic purposes.

Optional Features

To automatically remove processed files, enable the --delete-processed feature.
To gather and display statistical information, use the --collect-stats feature.

Consult the command line help for detailed information on each available flag.

Appendix A - LogZilla Authentication Token Management

Token Creation

To create a token for a LogZilla server, administrator or root access is required to execute the following command:

logzilla authtoken create --ingest-only

Note: The ingest-only token type is a permission-limited token that will only allow ingest of data. No other permissions are given to this token such as user management, queries, etc.

ingest-4cb844da7e91387890ebc27cf4982f57037b746a910927de

Token Administration

Token Listing

Existing tokens can be reviewed using the following command:

logzilla authtoken list

This command will display all active tokens along with their creation dates and associated users.

Token Information

Detailed information for a specific token can be accessed with:

logzilla authtoken info <token_id>

Token Deactivation

A token can be revoked (deleted) using:

logzilla authtoken revoke <token_id>