This document covers deploying, configuring, and managing the OpenCloud CDR Generation Resource Adaptor.
 |
About the CDR Generation Resource Adaptor
The CDR resource adaptor provides an interface for SBBs to write Call Detail Records (CDRs) to a series of CDR files. The RA 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. |
Topics
This document includes the following topics:
| Topic | What it covers |
|---|---|
|
|
|
|
|
|
|
|
|
More Information
Download
 |
Download an evaluation version of the CDR Resource Adaptor 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.jar. It has a single dependency, on the Google Protobuf library. Protobuf deployable unit protobuf-library.du.jar is delivered with the CDR resource adaptor package.
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. The basic procedure is:
-
Deploy the Protobuf library.
-
Deploy the CDR resource adaptor.
-
Create a CDR resource adaptor entity.
-
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 Protobuf definition The Protobuf definition can use tools and languages supported by the Protobuf project.
|
The format of a text CDR file consists of:
All lines end with the platform-default line ending (LF 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 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.
 |
If the node exits for any reason before the write/archive process completes, partial CDR files needing manual recovery may be left behind. |
Configuration
This page describes the configuration properties of the CDR resource adaptor. These properties are passed to the createRAEntity management operation when deploying the CDR resource adaptor.
Configuration properties
The following properties are passed to the createRAEntity management operation when deploying the CDR resource adaptor.
| Property | What it does | Default | ||||
|---|---|---|---|---|---|---|
|
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 CDR file type to use. Either |
|
||||
|
Pattern used to generate final CDR filenames.
|
|
||||
|
Prefix used as part of the temporary CDR filename. That is, the file to which currently generated call data records are written.
|
|
||||
|
Approximate maximum size in bytes before a new CDR file is started. After a CDR is written, the total file size is compared to
|
|
||||
|
Number of CDRs to be written to a CDR file before a new file is started. The line count does not include the header and footer lines, if enabled.
|
|
||||
|
Number of milliseconds of operation before time-based file rollover. If a CDR file is used for more than
|
|
||||
|
If |
|
||||
|
If |
|
||||
|
If If |
|
||||
|
Command to run on each CDR file completion. The resource adaptor must have execute permissions for the designated command.
If empty, no command is run.
|
empty |
||||
|
Character encoding to use for the output file. |
|
||||
|
Time, in milliseconds, to wait for a CDR write to complete before returning a timeout error to the calling SBB. |
|
||||
|
Delay, in milliseconds, to wait after a CDR write error before attempting another CDR write. |
|
||||
|
If If
|
|
||||
|
If If
|
|
Filename patterns
The FilenamePattern configuration parameter should include escape sequences that are replaced to generate unique filenames. The supported sequences are:
| Sequence | Description |
|---|---|
|
A literal '%' character |
|
File completion timestamp, as milliseconds since Jan 1 1970 00:00 UTC |
|
File creation timestamp, as milliseconds since Jan 1 1970 00:00 UTC |
|
Auto-incrementing file sequence number, starting at 1 |
|
File completion timestamp, formatted as YYYYMMDDhhmmss |
|
File creation timestamp, formatted as YYYYMMDDhhmmss |
|
Rhino node ID responsible for creating this file |
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/cathy, then the above is equivalent to
/home/cathy/cdr
In order to assist in platform-independent configuration, you can also use the special notation of ${/}, which is a shortcut for ${file.separator}.
Persistence, error handling, and operational state
If both WriteWait and WriteSync configuration properties are 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 a SBB. In that case, after a successful writeCDR call, SBBs should assume that all CDR data has been saved to disk.
If there is a write error while writing the CDR, and the WriteWait configuration property is True, this will be reported to the SBB as an IOException. If the CDR could not be written within the configured WriteTimeout of the RA entity, com.opencloud.slee.resources.cdr.WriteTimeoutException (a subclass of IOException) is reported to the SBB.
| |
In general, receiving an exception means that the CDR RA could not guarantee that the CDR was successfully written. (It might eventually be written successfully, but there is no guarantee.) |
Under normal operation, CDRProvider.isOperational() returns True. If a write error or timeout error occurred recently, isOperational() returns False and all attempts to write CDRs 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 RA entity is currently deactivated. Services should test isOperational() if they wish to behave differently when CDR writing is unavailable due to error.
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_*.tmp where * denotes a random number. If they contain useful CDR data, these files will need to be manually examined and processed.
Binary File Support
This section describes CDR resource adaptor support for writing binary CDR files.
Binary CDR file support using Google Protobuf definition
The CDR resource adaptor:
-
uses the Google Protocol Buffers to support writing CDR files with binary encoded CDR records
-
enables SBBs to store any protocol buffer protocol message.
| |
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 Protobuf functionality in an SBB, the developer must:
-
Define a protocol buffer message that will be generated and written by creating a
.protofile -
Use the protocol buffer compiler to generate code that supports creation, writing, and reading the protocol buffer message specified in
.protofile -
Use the Java protocol buffer API in the SBB to create messages and pass them to the CDR resource adaptor for writing
-
Package the generated protocol buffer code so that it can be used by the SBB at runtime (for example, include it in an
sbb.jaror create and reference a library jar).
| |
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:
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;
}
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;
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;
required int32 fid = 2;
required string message_name = 3;
}
message BinaryCDR {
required int32 mid = 1;
required bytes cdr = 2;
}
message StringCDR {
required string cdr = 1;
}
message Footer {
}
message DateTime {
required int64 milliseconds_since_epoch = 1;
required sint32 zoneoffset_minutes = 2;
}
}
A CDR file is a collection of records. If the Header configuration property is set to True, the first record in CDR file contains the header message. Similarly, based on the Footer configuration property, 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. Each record that contains either a BinaryCDR or StringCDR message also includes a timestamp representing date and time when the CDR was generated.
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 describes 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.
| |
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. |
Binary CDR file interrogation tools
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 | ||
|---|---|---|---|
|
A Python script that displays the content of a binary CDR file in text format. Usage: listcdrs.py CDRFILE
|
||
|
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]...
The The This tool also supports CDR binary files in gzip format. Each file that ends with a |
| |
Short usage message is displayed by each tool when invoked without parameters. |
Alarms
CDR resource adaptor generates alarms related to CDR write and CDR file archive failures.
For all of these alarm types use the CDR resource adaptor entity name as the alarm instanceID:
| Alarm type | When raised | When cleared | Action to take |
|---|---|---|---|
|
A CDR could not be written and flushed to disk within the configured |
The write thread has been operating normally with no timeouts for at least 2* |
Check that the CDR directory is accessible and that the disk is not overloaded. Check that Rhino has available spare CPU time. |
|
An I/O error has occurred when creating a CDR file, writing to a CDR file, or closing a CDR file. |
A CDR is successfully written to disk without errors. |
Examine the Rhino logs for detailed error information and correct the underlying error. Manually recover CDR data if necessary. |
|
Execution of the CDR |
A CDR file is successfully archived without errors. |
Examine the Rhino logs for detailed error information and correct the underlying error. Manually process any CDR files that were not processed automatically if necessary. |
|
The CDR write thread exits unexpectedly. Suggests a bug in the CDR RA code. |
The RA is deactivated. |
Deactivate, then activate the CDR RA entity. Contact OpenCloud support for further diagnosis. |
|
The CDR archive thread exits unexpectedly. Suggests a bug in the CDR RA code. |
The RA is deactivated. |
Deactivate, then activate the CDR RA entity. Contact OpenCloud support for further diagnosis. |
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
|
||||||||||||
3 |
The properties in
|
||||||||||||
4 |
To deploy the examples, using Ant, execute the $ cd $RHINO_HOME/cdr-ra-VERSION/examples $ ant deploy-all This 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:
|
| |
Source code for the example service can be found in the examples/src subdirectory of CDR resource adaptor package. This code may be freely altered and reused. It is made available under a BSD-style license. |
CDR Resource Adaptor Type API
The OpenCloud CDR Resource Adaptor implements the CDR Resource Adaptor Type API.
Changelog
Version 2.2.0.3
-
Added '--formatted' option to the ListCdrs tool to produce more easily readable output. (CDR-25)
Version 2.2.0.2
-
Added new config property "WriteWait". When set to "False", the resource adaptor will not wait for the CDR to be written to the file before reporting success to the calling SBB. This can be used to reduce latency in writing CDRs but means that queued CDRs will be lost in the event of a write error or node failure. When set to "True", the resource adaptor will only report success to the caller once the CDR has been written to the file. The default is "True", which gives the same behaviour as previous versions. (CDR-24)
Version 2.2.0.1
-
Fixed a NullPointerException that occurred when a text CDR file was closed if the resource adaptor was configured not to output a footer line to the file. (CDR-20)
-
Updated configuration default values in documentation. (CDR-21)
Version 2.2.0.0
-
Added binary CDR file support. (CDR-15)
-
Added support for CDR objects which have type com.google.protobuf.Message or Object. (CDR-8)
Version 2.1.0
-
The CDR RA 2.1 has been ported to the JAIN SLEE 1.1 Resource Adaptor API.
Version 2.0.0
-
The CDR RA 2.0 implements the recommended CDR 2.0 RA Type.
-
The CDR examples now include an test implementation of a simple CDR test service.