This document covers deploying, configuring, and managing the Metaswitch Rhino CDR Resource Adaptor.

Topics

Overview and Concepts

  • how the CDR Resource Adaptor serves as an interface to SBBs to write Call Detail Records

  • general options for managing CDR streams and generating CDR files

Getting Started

  • how to deploy the resource adaptor

  • resource adaptor output formats

  • resource adaptor deactivation process

Resource Adaptor Configuration

  • how to configure a resource adaptor entity

  • how to use profiles to configure the CDR streams

  • active reconfiguration

Binary File Support

  • how to generate SBB-specific binary CDR files

  • user tools to query and display binary CDR file content in text format

Alarms

  • alarms generated by the resource adaptor

CDR Management Bean

  • the management bean which can be used to view state of stream configuration

Example Service

  • how to install and run the example service

Other documentation can be found on the CDR Resource Adaptor product page.

Notices

Copyright © 2022 Microsoft. All rights reserved

This manual is issued on a controlled basis to a specific person on the understanding that no part of the Metaswitch Networks product code or documentation (including this manual) will be copied or distributed without prior agreement in writing from Metaswitch Networks.

Metaswitch Networks reserves the right to, without notice, modify or revise all or part of this document and/or change product features or specifications and shall not be responsible for any loss, cost, or damage, including consequential damage, caused by reliance on these materials.

Metaswitch and the Metaswitch logo are trademarks of Metaswitch Networks. Other brands and products referenced herein are the trademarks or registered trademarks of their respective holders.

Overview and Concepts

This section provides an overview of the CDR Resource Adaptor and concepts related to its management and operation.

About the CDR Resource Adaptor

The CDR resource adaptor provides an interface for SBBs to write Call Detail Records (CDRs) to a series of CDR files. The resource adaptor supports automatic rollover by number of CDRs written, CDR file size, or elapsed time. CDR files can be automatically post-processed by an external program when they are completed.

CDR streams

A single CDR resource adaptor entity can manage multiple CDR streams. A CDR stream is a series of rolled-over CDR files. From the perspective of an SBB, a CDR stream is a named destination for writing CDRs to. A single SBB can write to multiple CDR streams by providing a stream name as one of the parameters when invoking methods of the CDR Resource Adaptor interface.

Defining multiple CDR streams allows separation for groups of related CDRs, such as a CDR stream per user service or type of CDR. This usually simplifies any post-processing of generated CDR files; for example, CDR files that SBBs use consistently can be generated by a single stream, to contain CDRs in the same format.

CDR streams are configured by creating, modifying, and removing profiles in a CdrStreamConfiguration profile table. Each profile represents a CDR stream. The name of the profile in the profile table is used as the CDR stream name. As the CDR resource adaptor supports active reconfiguration, there is no need to deactivate it for reconfiguration.

Reliability/Latency tradeoff

Each CDR stream can be configured to favour write operation reliability or write operation latency from the perspective of the calling SBB. That is, whether the resource adaptor should wait until the CDR is persisted to disk (meaning it is synchronous) or just queue the CDR write internally before returning control to SBB (in which case it is asynchronous).

The default CDR stream configuration favours write reliability over latency for SBBs making synchronous CDR write requests to a given stream. This behaviour can be changed to make the write requests asynchronous.

Tip It is important to understand that this tradeoff is not between the probability of write failure or CDR write operation latency. It is only about whether the SBB should wait for the result of writing the file, for example to customise SBB behaviour if a CDR write operation fails.
Note
See also
the description of WriteTimeout and WriteSync stream configuration attributes in CDR stream profile-based configuration.

CDR files

Each CDR stream can be configured to generate CDR files in either binary or text format. When text format is selected, CDRs are persisted to a human-readable text file with configurable character encoding. In turn, selecting binary format results in creation of binary CDR files. The format of CDR records is controlled by the SBB developer, by either providing the CDR as SBB-controlled text or defining a Google Protocol Buffers message descriptor and generating code that is the SBB uses to represent the CDR.

Tip Examples for both usage scenarios are part of the CDR Resource Adaptor distribution package.

Getting Started

Below are overviews of how to deploy the CDR Resource Adaptor, its output format, and how to force immediate deactivation of a CDR resource adaptor entity.

Deploying the CDR Resource Adaptor

The CDR Resource Adaptor comes packaged in a deployable unit, cdr-ra-du-VERSION.jar. The CDR resource adaptor type is packaged in cdr-ratype-VERSION.du.jar

The resource adaptor has two dependencies, both delivered as part of distribution package, in the du subdirectory:

  • the CDR Stream Configuration profile, with profile deployable unit cdr-profile-spec-VERSION.du.jar

  • the Google Protocol Buffers library, with protobuf deployable unit protobuf-library-VERSION.du.jar

…​ where VERSION represents the version of the CDR resource adaptor.

The CDR resource adaptor does not come with a deployment script. Instead, an example service, distributed as part of the CDR resource adaptor package, includes a script that installs and configures the resource adaptor for that example. Developers and administrators should refer to the example script for the exact steps and adjust them to their own needs.

Note
Basic deployment procedure

Deploying the CDR Resource Adaptor includes these steps:

  1. Deploy the Google Protocol Buffers library.

  2. Deploy the CDR resource adaptor type.

  3. Deploy the CDR profile specification.

  4. Deploy the CDR Resource Adaptor.

  5. Create a CDR Stream Configuration profile table.

  6. Create at least a single profile in the CDR Stream Configuration profile table.

  7. Create a CDR resource adaptor entity.

  8. Bind the CDR resource adaptor entity to a link name expected by the service.

Output format

A CDR resource adaptor entity can be configured to produce either binary or text CDR files.

Binary output format Text output format

Defined in the Google Protocol Buffers definition CdrFileFormat.proto
(in the CDR Resource Adaptor package, under etc/).

CdrFileFormat.proto defines a list of records, where a record is one of:

  • Header

  • FieldDescriptor

  • MessageDescriptor

  • BinaryCdr

  • StringCdr

  • Footer

  • Timestamp

  • ExtensionDescriptor

The format of a text CDR file consists of:

  • an optional one-line header containing the creation time of the CDR file (if Header is True)

  • zero or more CDRs, one per line

  • an optional one-line footer containing the completion time of the CDR file (if Footer is True).

All lines end with the platform-default line ending (LF \n on Unix, CRLF \r\n on Windows).

The format of an individual CDR is controlled by the calling service.

Immediate deactivation of a resource adaptor entity

When deactivated, a CDR resource adaptor entity remains in the STOPPING state until all pending CDRs are written and the CDR files are completed and archived. If you need a faster shutdown, you can administratively remove the "CDR deactivation guard activities" (listed using the findactivities rhino-console command), to force the resource adaptor to transition to the INACTIVE state immediately.

Warning If the node exits for any reason before the write/archive process completes, partial CDR files needing manual recovery may be left behind.

Resource Adaptor Configuration

The CDR Resource Adaptor is configured using resource adaptor configuration properties and a configuration profile table.

The configuration is processed when you activate the resource adaptor or reconfigure it while it’s active.

Resource adaptor configuration properties

The CDR Resource Adaptor is configured using following configuration properties:

Property What it does Default
 CdrStreamConfigurationProfileTable

The name of a profile table defining CDR streams configuration. Each profile represents a CDR stream. The table must use the CDR Stream Configuration profile specification.

 CdrStreamConfiguration
 DefaultStream

The stream name to be used when an SBB requests a CDR write using a resource adaptor provider interface method without a stream name parameter. If the stream name is provided, it must match the name of a profile defined in CdrStreamConfigurationProfileTable.

Warning If the value is not set, an SBB CDR write request with no stream name provided will result in an exception being thrown and a SLEE alarm raised.

empty

 ArchiveQueueSizeAlarmRaise

If the archive queue size exceeds this value, the cdr.archive-queue-size alarm is raised.

The value must be >= 10.

 120
 ArchiveQueueSizeAlarmClear

If the archive queue size decreases below this value mthe cdr.archive-queue-size active alarm is cleared.

The value must be >= 5.

 80

Profile configuration

The CDR Resource Adaptor manages a set of CDR streams. A CDR stream is configured by creating a profile in CdrStreamConfigurationProfileTable. The profile name is used as the CDR stream name.

Attribute What it does Default
 OutputDirectoryName

Name of the directory into which the CDRs will be written. The resource adaptor must have write permissions for it.

This parameter is mandatory.

The directory will be created if it does not exist when the resource adaptor configuration is verified. This will happen before the resource adaptor is activated. The directory will also be created if it is missing when a new CDR file is created.

Note

The resource adaptor requires a Java file permission to write to the directory specified here.

This property supports property expansion.

Warning

In a clustered environment, each node manages its own set of CDR files. Several nodes may safely write to the same output directory; but care should be taken to ensure that the final output filenames do not collide. Including a %n format specifier (node ID) as part of the FilenamePattern is the safest way to ensure this.

 ${rhino.dir.home}${/}cdr
 CdrFileType

The CDR file type to use. Either Text or Binary.

 Binary
 FilenamePattern

Pattern used to generate final CDR filenames.

Note This property supports property expansion and filename patterns.
 cdr_%n_%M_%t.log
 TempFilePrefix

Prefix used as part of the temporary CDR filename. That is, the file to which currently generated call data records are written.

The full filename format for temporary CDR file is:

TempFilePrefix RHINO NODE ID CDR STREAM NAME _*.tmp

where * denotes a random number and CDR STREAM NAME represents the name of the CDR stream with characters other than a-z, A-Z, 0-9,.,_,- replaced by _.

Note This property supports property expansion.
 cdr_
 MaxSize

Approximate maximum size in bytes before a new CDR file is started. After a CDR is written, the total file size is compared to MaxSize.

  • If the current file size is larger, it is completed.

  • If MaxSize is 0, no size-based rollover is done.

1,000,000

bytes (approx 1MB)

 MaxCdrs

Number of CDRs to be written to a CDR file before a new file is started.

  • If MaxCdrs is 0, no size-based rollover is done.

0

(no rollover)

 MaxInterval

Number of milliseconds of operation before time-based file rollover. If a CDR file is used for more than MaxInterval seconds without being rolled over due to line- or size-based limits, it is completed anyway.

The value must be either 0 or >= 1000.

Note If CreateEmptyFiles is True, at least one CDR file is created every MaxInterval seconds, even if no CDRs are written.
0

(no rollover)

 Header

If True, a one-line header containing the start time of the text CDR file is put at the start of each file.

Note This attribute is ignored if CdrFileType is set to Binary. For binary CDR files, a record containing the header is always present.
 True
 Footer

If True, a one-line footer containing the end time of the text CDR file is put at the end of each file.

Note This attribute is ignored if CdrFileType is set to Binary. For binary CDR files, a record containing the footer is always present.
 True
 CreateEmptyFiles

If True, a new CDR file is created immediately on resource adaptor activation, and whenever a CDR file is rolled over.

If False, a new file is created when writing the first CDR record after activation or rollover of a CDR file.

 False
 ArchiveCommand

Command to run on each CDR file completion.

{0} in the command line denotes the absolute path to the CDR file.

If empty, no command is run.

Note

The resource adaptor must have execute permissions for the specified command. The default permissions allow it to run commands in a directory named cdr-bin in the Rhino home directory and the Rhino node directory.

This property supports property expansion.

empty

 Charset

Character encoding to use for the output file.

 ISO-8859-1
 WriteTimeout

Time, in milliseconds, to wait for a CDR write to complete before returning a timeout error to the calling SBB.

The value must either 0 or >= 200.

If 0, the resource adaptor adds the CDR to a queue and returns immediately. This can be used to reduce latency in writing CDRs, but means that queued CDRs are lost in the event of a write error or node failure.

Warning If this property is set to 0, then WriteSync should generally also be set to False, because the resource adaptor will already have returned to the calling SBB before FileDescriptor.sync() is called.
5000

(5 seconds)

 WriteRetry

Delay, in milliseconds, to wait after a CDR write error before attempting another CDR write. Value must be greater than or equal to 500.

30000

(30 seconds)

 WriteSync

If True, FileDescriptor.sync() is called after writing CDRs, to flush them to disk before reporting success to the calling SBB.

If False, the call to sync() is skipped, resulting in considerably less disk I/O but a weaker guarantee to the calling SBB.

Warning If WriteTimeout is 0, then this value has no effect on when control is returned to the calling SBB.
 True

File permissions

The security permission spec in the resource adaptor descriptor contains the following default permissions:

// rhino.dir.home - the install directory for Rhino SDK, the node-nnn directory for Rhino Production.
permission java.io.FilePermission "${rhino.dir.home}${/}cdr", "read, write, execute";
permission java.io.FilePermission "${rhino.dir.home}${/}cdr${/}-", "read, write, execute";
permission java.io.FilePermission "${rhino.dir.home}${/}cdr-bin", "read, execute";
permission java.io.FilePermission "${rhino.dir.home}${/}cdr-bin${/}-", "read, execute";
// rhino.dir.base - the install directory for both Rhino Production and Rhino SDK
permission java.io.FilePermission "${rhino.dir.base}${/}cdr", "read, write, execute";
permission java.io.FilePermission "${rhino.dir.base}${/}cdr${/}-", "read, write, execute";
permission java.io.FilePermission "${rhino.dir.base}${/}cdr-bin", "read, execute";
permission java.io.FilePermission "${rhino.dir.base}${/}cdr-bin${/}-", "read, execute";
// deprecated, retained for compatibility
permission java.io.FilePermission "${rhino.dir.home}${/}archive-cdr-log.sh", "read, execute";
permission java.io.FilePermission "${rhino.dir.home}${/}cdr${/}archive-cdr-log.sh", "execute";
permission java.io.FilePermission "${rhino.dir.base}${/}archive-cdr-log.sh", "read, execute";
permission java.io.FilePermission "${rhino.dir.base}${/}cdr${/}archive-cdr-log.sh", "read, execute";

Specifying an output directory or archive command that is not covered by the above permissions will require a new permission to be added to the deployable unit, using a Rhino management tool.

The Rhino Element Manager is the simplest way to make manual changes, and there is an Ant task for scripted deployment.

Filename patterns

The FilenamePattern configuration parameter should include format specifiers that are replaced to generate unique filenames. The supported specifiers are:

Specifier Description
 %%

A literal % character

 %t

File completion timestamp, as milliseconds since Jan 1 1970 00:00 UTC

 %T

File creation timestamp, as milliseconds since Jan 1 1970 00:00 UTC

 %s

Auto-incrementing file completion sequence number, starting at 1

Warning Deactivation and activation of a CDR resource adaptor entity will result in resetting the sequence number to 1. To obtain a unique filename, use this pattern together with one of timestamp patterns.
 %d

File completion timestamp, formatted as yyyyMMddHHmmss

 %D

File creation timestamp, formatted as yyyyMMddHHmmss

 %n

Rhino node ID responsible for creating this file

 %M

CDR stream name where characters other than a-z, A-Z, 0-9,.,_,- are replaced by _

Property expansion

Certain CDR resource adaptor configuration properties support system property expansion. This mechanism is similar to expanding variables in a shell. That is, when a string like ${some.property} appears as part of a configuration property value, it will be expanded to the value of the system property. For example,

${user.home}/cdr

will expand ${user.home} to use the value of the user.home system property. If that property’s value is /home/rhino, then the above is equivalent to

/home/rhino/cdr

Two useful properties for specifying paths (used in the default file permissions) are rhino.dir.home and rhino.dir.base:

Property What it refers to
 rhino.dir.home

the install directory for Rhino SDK, the node-nnn directory for Rhino Production

 rhino.dir.base

the install directory for both Rhino Production and Rhino SDK

In order to assist in platform-independent configuration, you can also use the special notation of ${/}, which is a shortcut for ${file.separator}.

CDR stream persistence, error handling, and operational state

If stream configuration attributes WriteTimeout is set to a non-zero value and WriteSync is set to True, the CDR resource adaptor ensures that all written CDR data has been flushed to disk (using java.io.FileDescriptor.sync()) before returning to an SBB. In that case, after a successful writeCDR call, SBBs should assume that all CDR data has been saved to disk.

Warning The exact behaviour of java.io.FileDescriptor.sync() is dependent on the operating system, drivers and hardware. In some environments the sync() call may return successfully before the data is permanently stored.

If there is a write error while writing the CDR, and the WriteTimeout stream configuration attribute is set to a non-zero value, this will be reported to the SBB as an IOException. If the CDR could not be written within the configured WriteTimeout, then a com.opencloud.slee.resources.cdr.WriteTimeoutException (a subclass of IOException) is reported to the SBB.

Note In general, receiving an exception means that the CDR resource adaptor could not guarantee that the CDR was successfully written.

Under normal operation, a CDRProvider.isOperational() call directed towards any stream returns True. If a write error or timeout error occurred recently for a stream, a isOperational() call towards that stream returns False. All attempts to write CDRs to such streams are immediately rejected without attempting to write them to disk. This state persists for 2 * WriteTimeout milliseconds (for timeout errors) or WriteRetry milliseconds (for write errors).

Additionally, isOperational() returns False if the resource adaptor entity is currently inactive (but was successfully activated at least once). Services should test isOperational() if they wish to behave differently when CDR writing is unavailable.

In the event of a write error, or if a Rhino node unexpectedly exits, partial CDR files may be left in the CDR directory. With the default configuration value of TempFilePrefix, these files are named cdr_nodeID_streamName_*.tmp where * denotes a random number. If they contain useful CDR data, these files will need to be manually examined and processed.

Active reconfiguration

The resource adaptor supports active reconfiguration. You can update configuration properties without having to deactivate the resource adaptor entity.

Warning
Changes to stream configuration profiles are not automatically discovered by the resource adaptor

For the stream configuration to take effect, you must trigger a configuration reload after changing the profile table. To trigger a configuration reload…​

  • using the Rhino command-line console: run updateraentityconfigproperties <entity-name>

  • using the Rhino Element Manager: edit and save the resource adaptor entity configuration without changing any configuration property values.

When the configuration is updated, the resource adaptor will compare the new configuration with the previous valid configuration to determine which streams need to be:

  • stopped and removed — when a profile representing the stream was removed; that is, there is no profile with a profile name equal to the CDR stream name

  • created and started — when a new profile was added

  • reconfigured — when attributes of an existing profile were changed; that is, attribute values of a profile with the same CDR stream name are different than attribute values previously used by the resource adaptor.

If errors are encountered when adding new streams or reconfiguring existing streams, the configuration update is aborted. No changes to the existing "in use" configuration are made.

Note Changing configuration of a stream that is in use results in a rollover of the stream’s CDR file. The newly created CDR file is configured based on the updated stream configuration. CDRs will not be lost during stream reconfiguration.

Binary File Support

This section describes the CDR Resource Adaptor support for writing binary CDR files.

Using the Google Protocol Buffers definition

Warning
Download package

The CDR resource adaptor uses Google Protocol Buffers version 2.3.0 — which is no longer available from the official website. Please download the package from here: protobuf-2.3.0.tar.gz.

The CDR resource adaptor:

  • uses the Google Protocol Buffers (proto2 version of the protocol buffers language) to support writing CDR files with binary-encoded CDR records

  • enables SBBs to store any protocol buffer protocol message.

Note
See also
Google’s Protocol Buffer documentation includes an extensive description of the .proto file syntax and a tutorial on using the protocol buffers.

To use Protocol Buffers functionality in an SBB, the developer must:

  1. Define a protocol buffer message that will be generated and written by creating a .proto file.

  2. Use the protocol buffer compiler to generate code that supports the creation, writing, and reading of the protocol buffer message specified in .proto file.

  3. Use the Java protocol buffer API in the SBB to create messages and pass them to the CDR resource adaptor for writing.

  4. Package the generated protocol buffer code so that it can be used by the SBB at runtime (for example, include it in an sbb.jar or create and reference a library jar).

Tip There is no need to package the protocol buffer library code itself, as it is already distributed as a library jar with the CDR resource adaptor package.

Binary CDR file format

The binary CDR file format is specified as the protocol buffer’s .proto file. It is distributed as part of the CDR resource adaptor package in /etc/CdrFileFormat.proto. Here’s what it looks like:

Binary CDR file format
syntax = "proto2";
package com.opencloud.slee.resources.cdr.protobuf;

option java_outer_classname = "CdrFileFormat";

message CdrFile {

    repeated Record record = 1;

    message Record {
        optional Header header = 1;
        optional MDescriptor messageDescriptor = 2;
        optional FDescriptor fileDescriptor = 3;
        optional BinaryCDR  binaryCdr = 4;
        optional StringCDR stringCdr = 5;
        optional Footer footer = 6;
        optional DateTime timestamp = 7;
        optional EDescriptor extensionDescriptor = 8;
    }

    message Header {
        optional string ra_name = 1;
        optional string ra_vendor = 2;
        optional string ra_version = 3;
        optional string ra_release = 4;
        optional string ra_build = 5;
        optional string ra_revision = 6;
        optional string description = 7;
        optional string rhino_node = 8;
        optional string ra_entity = 9;
        optional string hostname = 10;
    }

    // Contains a single encoded FileDescriptorProto.
    // The descriptor can subsequently be referred to by 'fid'
    message FDescriptor {
        required int32 fid = 1; // FDescriptor id
        required bytes encoded_descriptor = 2;
        repeated int32 dependency = 3 [packed=true];  // List of dependencies, referring to previously-encoded fids
    }

    // Associates a 'mid' with a particular named message in a previously-encoded FileDescriptor
    message MDescriptor {
        required int32 mid = 1; // MDescriptor id
        required int32 fid = 2;
        required string message_name = 3;
    }

    message BinaryCDR {
        required int32 mid = 1;
        required bytes cdr = 2;
        repeated int32 eid = 3;
    }

    message StringCDR {
        required string cdr = 1;
    }

    message Footer {
    }

    message DateTime {
      required int64 milliseconds_since_epoch = 1;
      required sint32 zoneoffset_minutes = 2;
    }

    message EDescriptor {
        required int32 eid = 1; // EDescriptor id
        required int32 fid = 2;
        required string name = 3;
    }
}

A CDR file is a collection of records. The first record in CDR file contains the header message; the last record in CDR file might be the footer message.

SBB-generated CDRs represented by protocol buffer messages are stored in the record as BinaryCDR messages. If the SBB generates text CDRs, they are stored in the record as StringCDR messages. A record that contains either a BinaryCDR or StringCDR message may also contain a timestamp representing the date and time when the CDR was processed by stream’s write thread.

The stream’s write thread processes CDRs in batches; only the first CDR record in the batch contains a timestamp. A record that contains either a BinaryCDR or StringCDR without a timestamp value should be processed assuming the timestamp value is equal to the last encountered timestamp.

Whenever an SBB requests a write of a binary CDR (protocol buffer message), the resource adaptor checks if this type of binary CDR is written, for the first time, in the current CDR file. If it is, then the resource adaptor first generates and writes one or more records containing an FDescriptor message, followed by a record containing an MDescriptor message. These messages contain protocol buffer metadata that describe the format of the binary CDR (SBB-generated protocol buffer message).

The encoded_descriptor field of the FDescriptor message contains encoded bytes representing a com.google.protobuf.Descriptors.FileDescriptor for the binary CDR (SBB-generated protocol buffer message) and can be used to recreate and programmatically interrogate the protocol buffer’s description (effectively the .proto file) of the stored binary CDR records.

Note
See also
For more information on how to use Descriptors.FileDescriptor, see the protocol buffer documentation on Self-describing Messages, and the Protocol Buffers Java API.

Extensions

The Google Protocol Buffers library supports the notion of extension fields. Any message may contain multiple extension fields. This enables storing additional information in a protocol buffer message without modifying the original message definition (the .proto file).

Note
See also
For more information on extensions, see the protocol buffer documentation Extensions.

When a binary CDR (protocol buffer message) is stored using the extension-supporting resource adaptor API call, the extension definitions are included in the CDR file. When the extension definition is used for the first time in a CDR file, the write of the BinaryCDR message is preceded with records representing metadata about the extension. Extension metadata is represented by records containing one or more FDescriptor messages followed by a single record with an EDescriptor message.

  • The FDescriptor contains encoded bytes representing a com.google.protobuf.Descriptors.FileDescriptor (effectively the .proto file), with the definition of the extension.

  • The EDescriptor provides a name of the extension field and reference to the FDescriptor containing the field definition. The mapping between the binary CDR and extensions used is persisted within the CDR file.

Binary CDR file processing

The CDR resource adaptor package contains tools for processing binary CDR files, described in Binary CDR file processing.

Binary CDR File Processing

This page describes tools for processing binary CDR files delivered as part of the CDR Resource Adaptor package.

Display binary CDR file content

The CDR Resource Adaptor package contains two user tools that can be used to display the content of a binary CDR file in text format.

Tool Description
 listcdrs.py

A Python script that displays the content of a binary CDR file in text format.

Usage:

listcdrs.py CDRFILE
Note This script requires the Python protocol buffers module, which is available as part of a complete protocol buffers installation. (Depending on your operating system type and vendor, it might also be available as part of your standard software distribution system.)
 listcdrs.sh

A shell script that starts a Java program capable of querying and displaying a binary CDR file’s content in text format.

Usage:

listcdrs.sh [--field field --regex regex] [--formatted] CDRFILE [CDRFILE]...
Tip To list possible values for the --field parameter, display the binary CDR file content without the --field parameter. Any text followed by = is a field name.

The --regex parameter takes a regular expression; only CDRs with matching field values display. The supported regular expression format is described in the Pattern class documentation.

The --formatted option results in using a multiline display format.

This tool also supports CDR binary files in gzip format. Each file that ends with a .gz suffix is treated as compressed. That is, there is no need to decompress such CDR files before running the tool.

Note When invoked without parameters, each tool displays a short usage message.

Extendable binary CDR file processing tools

The CDR processing tool cdrpipeline is a Java-based tool that streamlines development of custom binary CDR files' processing logic.

The cdrpipeline is responsible for loading and parsing binary CDR files. The actual CDR processing logic is captured as plugins provided by the service developer, where cdrpipeline plugins are implementations of the CDRProcessor interface.

The tool is delivered with abstract helper implementations of a CdrProcessor that allow the service developer to cede responsibility for decoding the binary CDR (protocol buffer message) to the helper class. The service developer can then concentrate on creating custom processing logic without the need to reimplement the boilerplate message-parsing code. This effectively lets the service developer work with the binary CDR at the same abstraction level (protocol buffer message) when generating the CDR in service code and when post-processing the resulting binary CDR files.

Note
See also
The CDR File Tools API Javadoc.

Running the CDR Pipeline tool

The cdrpipeline tool can be run using the cdrpipeline.sh shell script delivered as part of the CDR resource adaptor package.

Usage:
cdrpipeline.sh [-i] [-p <property=value>] [-s <bytes>] -c <processor> [<processor>]... -f <cdrfile> [<cdrfile>]...

Option

Description

-c <processor> [<processor>]...
--chain <processor> [<processor>]...

Class names representing com.opencloud.slee.resources.cdr.process.CdrProcessor to be used to process CDR records.

Note The CdrProcessor classes are invoked in the order in which they are specified on the command line. The order is relevant as every CDR processor may act as a filter. That is, a CDR processor may instruct the tool that a given CDR is not to be processed by later CDR processors.
 -f <cdrfile> [<cdrfile>]...
--files <cdrfile> [<cdrfile>]...

Binary CDR files to process.

Note The CDR files are processed in the order in which they are specified on the command line.
-i
--ignore-error

If specified, the tool is to ignore record-processing errors and continue processing.

 -p <property=value>
--processor-property <property=value>

Custom property value pair to be used by CDR processors.

-s <bytes>
--size-limit <bytes>

CDR record size limit.

Minimal supported value is 67108864 (64 MB). The default value is equal to minimal value, which is 67108864 (64 MB).

Note The version of protocol buffers library used by the CDR resource adaptor does not enforce the limit uniformly. If processing fails with message "InvalidProtocolBufferException: Protocol message was too large" and you are sure that the CDR file that is processed is correct, increase the limit.

This tool also supports CDR binary files in gzip format. Each file that ends with a .gz suffix is treated as compressed. That is, there is no need to decompress such CDR files before running the tool.

Examples

To process all files in the ../../cdr directory matching *.log.gz using a processor that outputs stats for each file:

./cdrpipeline.sh -c com.opencloud.slee.resources.cdr.process.GenerateStatsCdrProcessor -f ../../cdr/*.log.gz

To process the same files using a processor that outputs formatted content of the CDRs, and increase the size limit for protobuf messages to 128MB:

./cdrpipeline.sh -c com.opencloud.slee.resources.cdr.process.listcdr.FormattedCdrProcessor -s 134217728 -f ../../cdr/*.log.gz

The other processor that can be used for simple (single-line) output is com.opencloud.slee.resources.cdr.process.listcdr.SimpleCdrProcessor.

Developing a custom CDR Processor

To create and use a custom CdrProcessor, you must implement the com.opencloud.slee.resources.cdr.process.CdrProcessor interface (or any of the implementing helper classes), and place the compiled class file (or jar file) in the classpath used by cdrpipeline.

Note Example CdrProcessor implementations are distributed as part of the Example Service.
CDR Pipeline source code

The binary version of the cdrpipeline tool is located in the lib directory of the CDR resource adaptor package. The relevant jar files are described below:

Filename Description Required to compile against?
cdr-file-tools-VERSION.jar

Classes constituting the cdrpipeline tool, including the com.opencloud.slee.resources.cdr.process.CdrProcessor interface.

Yes

cdr-file-format-VERSION.jar

Classes generated by the protocol buffers library, used to decode data from the binary CDR file.

Yes

protobuf-java-VERSION.jar

Protocol buffers Java library, used to decode data from the binary CDR file.

Yes

log4j-VERSION.jar

Log-handling library.

No

commons-cli-VERSION.jar

Command-line parameters-handling library.

No

…​ where VERSION represents the version of the CDR resource adaptor or library used.

The CDR Pipeline classpath

The classpath searched by the cdrpipeline tool when using the provided cdrpipeline.sh script includes:

  • the current working directory

  • jar files in the lib directory of the CDR resource adaptor package

  • directories specified in the OPT_JAR_LIST environment variable (separated using the : character).

Alarms

The CDR Resource Adaptor generates alarms when unexpected failures occur.

Alarms raised by the CDR Resource Adaptor signal failure conditions that usually require administrator intervention to resolve. They are grouped into the following categories:

Configuration and usage alarms

Error conditions signaled by alarms in this category are not related to any particular stream managed by the resource adaptor. The alarm Instance ID(s) are equal to the entity name, except for the cdr.stream.missing alarm type. The Instance ID for the cdr.stream.missing alarm type also contains the name of missing or unconfigured streams; its format is

entity name : stream name
Alarm type When…​ Actions to take
 cdr.misconfiguration
raised

The resource adaptor is unable to activate due to an invalid configuration.

cleared

The resource adaptor is deactivated.

  • Examine the Rhino logs for detailed information.

  • Change the configuration.

  • Deactivate, then activate the CDR resource adaptor entity.

 cdr.stream.missing
raised

The service requested an operation on a stream unknown to the CDR resource adaptor entity.

cleared

The resource adaptor is deactivated.

  • Check that the expected stream is configured.

  • Change the configuration.

  • Notify the CDR resource adaptor entity of the configuration changes.

  • Deactivate, then activate the CDR resource adaptor entity; or clear the alarm administratively.

 cdr.stream.nodefault
raised

The service requested an operation on the default stream, but the default stream is not configured.

cleared

The resource adaptor is deactivated or the default stream is configured.

  • Check resource adaptor configuration.

  • Set a valid default stream name.

CDR stream IO failure alarms

Alarms in this category are raised when error conditions occur during CDR write or CDR file archive operations. These alarms are raised and cleared on a per CDR stream basis. That is, an alarm can be raised due to a CDR write failure on a given CDR stream while other CDR streams are operational and successfully fulfill CDR write requests.

CDR write failure alarms

These alarms are raised when a CDR stream write thread encounters failures writing to CDR files. The format of the alarm Instance ID(s) is:

entity name : stream name : write thread sequence

where write thread sequence is a sequence number assigned to each CDR stream write thread.

Alarm type When…​ Actions to take
 cdr.write-timeout
raised

A CDR could not be written and flushed to disk within the configured WriteTimeout.

cleared

The write thread has been operating normally with no timeouts for at least 2*WriteTimeout milliseconds.

  • Check that the CDR directory is accessible and that the disk is not overloaded.

  • Check that Rhino has available spare CPU time.

 cdr.write-failure
raised

An I/O error has occurred when creating a CDR file, writing to a CDR file, or closing a CDR file.

cleared

A CDR is successfully written to disk without errors.

  • Examine the Rhino logs for detailed error information,

  • Correct the underlying error.

  • Manually recover CDR data if necessary.

 cdr.write-thread-failure
raised

The CDR write thread exits unexpectedly. Suggests a bug in the CDR resource adaptor code.

cleared

The resource adaptor is deactivated.

  • Deactivate, then activate the CDR resource adaptor entity.

  • Contact Metaswitch support for further diagnosis.

CDR file archive failure alarms

These alarms are raised when the CDR archive thread encounters failures archiving CDR files. The format of the alarm
Instance ID(s) is:

entity name : stream name : archive thread sequence

where archive thread sequence is a sequence number assigned to each CDR stream archive thread.

Alarm type When…​ Actions to take
 cdr.archive-failure
raised

Execution of the CDR ArchiveCommand fails, or the command returns a non-zero exit code.

cleared

A CDR file is successfully archived without errors.

  • Examine the Rhino logs for detailed error information.

  • Correct the underlying error.

  • Manually process any CDR files that were not processed automatically if necessary.

 cdr.archive-thread-failure
raised

The CDR archive thread exits unexpectedly. Suggests a bug in the CDR resource adaptor code.

cleared

The resource adaptor is deactivated.

  • Deactivate, then activate the CDR resource adaptor entity.

  • Contact Metaswitch support for further diagnosis.

 cdr.archive-queue-size
raised

The queue size for archiver thread exceeds the warning level set in the configuration. Suggests that the archive command execution time is too high for current load.

cleared

The queue size for archiver thread decreases below the safe level set in the configuration.

Note
See also
The ArchiveQueueSizeAlarmRaise and ArchiveQueueSizeAlarmClear configuration properties.
  • Examine the Rhino logs for problems executing the archive command.

  • Investigate the run time of archive command.

CDR Management Bean

The CDR resource adaptor entity registers a Java Management Extensions (JMX) managed bean that exposes information about currently configured CDR streams.

The CDR resource adaptor configuration is in part based on a profile table defining the CDR streams configuration. The CDR streams configuration is loaded by the resource adaptor when it is initialized or reconfigured. This means that the configuration used by the CDR resource adaptor entity at any given moment might be different than the configuration described in the profile table defining the CDR streams configuration.

Each CDR resource adaptor entity registers a JMX managed bean. That managed bean can be used to check if the configuration that is in use differs from the current CDR stream’s profile table configuration description.

CDRStreamMXBean

Each CDR resource adaptor entity provides its own CDRStreamMXBean managed bean. The ObjectName of the managed bean is of the form:

com.opencloud.cdr:type=Entity,name=<ra-entity>
Tip
See also
The CDR Resource Adaptor MXBean API Javadoc.

Example Service

The CDR resource adaptor comes with the CDR Generation example service. To deploy the example:

1

Start Rhino:

$RHINO_HOME/start-rhino.sh

2

Unpack the CDR resource adaptor distribution package into $RHINO_HOME.

Note If unpacked elsewhere, adjust the client.home configuration property in the build.properties file.

3

The properties in build.properties are used to configure the CDR resource adaptor during deployment. Edit it to verify that the configuration is correct for your local environment. In particular, verify these properties:

Property

 cdr.directory=$${rhino.dir.home}$${/}cdr

Specifies

Name of the directory into which the CDRs will be written. The resource adaptor must have write permissions for it. This parameter is mandatory, and its value is set to $RHINO_HOME/cdr.

Note If you intend to modify the value of cdr.directory to point to somewhere else, you need to update the security-permissions in the resource-adaptor-jar.xml deployment descriptor, in the resource adaptor’s deployable unit.

Property

 cdr.archivecommand=$RHINO_HOME/cdr-bin/archive-cdr-log.sh {0}

Specifies

Command to run on each CDR file completion. The resource adaptor must have execute permissions for the designated command.

{0} in the command line denotes the absolute path to the CDR file.

If empty, no command is run.

4

To deploy the examples, using Ant, execute the deploy-all target:

$ cd $RHINO_HOME/cdr-ra-VERSION/examples
$ ant deploy-all

This copies the archive script to the cdr folder, deploys the CDR Resource Adaptor, example (Telnet) resource adaptor, and the CDR Generation example service.

5

Use a Telnet utility to connect to the example resource adaptor:

telnet localhost 9999

6

Try these commands:

Command Description Example
send <number> [streamName]

Sends the number of CDRs to be written to the specified stream (or the default stream if streamName is not specified).

send 1
send-ext <number> [streamName]

Sends the number of CDRs with an additional extension field set to be written to the specified stream (or the default stream if streamName is not specified).

send-ext 1
close

Closes the Telnet connection and exits.

close
help

Displays the usage commands.

help
Tip Source code for the example service can be found in the examples/src subdirectory of the CDR Resource Adaptor package. This code may be freely altered and reused. It is made available under a BSD-style license.

Example: processing binary CDR files

The CDR Generation example service is accompanied by example code that processes the resulting binary CDR files. The examples are custom extensions of cdrpipeline tool.

Note The cdrpipeline tool is part of the CDR Resource Adaptor package, described in Extendable binary CDR file processing tools.

To run the binary CDR file processing examples:

1

Deploy the example service by following the steps in Example Service.

2

Use the example service to generate one or more completed binary CDR files.

Tip

The CDR Resource Adaptor writes CDRs to temporary files which are later completed (that is: closed, renamed, and possibly archived). After the CDR file is completed, the CDR Resource Adaptor no longer operates on the CDR file, at which time other tools can safely process the finalized CDR file. To force the CDR Resource Adaptor to complete a CDR file:

  1. Generate more than ~1 MB of CDRs (because the example service uses a stream configured with maxSize set to 1000000 bytes) — repeatedly use the send 1000 command until CDR file rollover occurs.

  2. Generate at least one CDR.

  3. Deactivate the resource adaptor.

3

To display the content of generated CDR files on the console, execute these commands:

$ cd $RHINO_HOME/cdr-ra-VERSION/examples
$ ant run-sysout-cdr-processor

This invokes the cdrpipeline tool with example SysOutDynamicCdrProcessor.

4

To create a temporary JavaDB database in $RHINO_HOME/cdr-ra-VERSION/examples/cdrdb and load the content of generated CDR files, execute these commands:

$ cd $RHINO_HOME/cdr-ra-VERSION/examples
$ ant run-db-insert-cdr-processor

This invokes the cdrpipeline tool with example DBInsertCdrProcessor. The Ant run-db-insert-cdr-processor target outputs a text message containing:

  • a command that may be used to start the Java DB ij tool (interactive JDBC) connected to the created database

  • example SQL queries that interrogate the imported CDR data (to be run in the ij tool connected to the created database).

Tip Source code for the example CdrProcessor(s) can be found in the examples/src subdirectory of the CDR Resource Adaptor package. Reviewing the Ant targets run-sysout-cdr-processor and run-db-insert-cdr-processor in examples/build.xml is also recommended.