This document covers deploying, configuring, and managing the Metaswitch Rhino CDR Resource Adaptor.
Topics
|
|
|
|
|
|
|
|
|
|
|
|
|
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.
 |
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. |
 |
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.
| |
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.
| |
Basic deployment procedure
Deploying the CDR Resource Adaptor includes these steps:
|
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
|
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 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.
 |
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 |
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
|
empty |
||
ArchiveQueueSizeAlarmRaise |
If the archive queue size exceeds this value, the The value must be |
120 |
||
ArchiveQueueSizeAlarmClear |
If the archive queue size decreases below this value mthe The value must be |
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.
|
${rhino.dir.home}${/}cdr
|
||||
CdrFileType |
The CDR file type to use. Either |
Binary |
||||
FilenamePattern |
Pattern used to generate final CDR filenames.
|
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
|
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
|
1,000,000 bytes (approx 1MB) |
||||
MaxCdrs |
Number of CDRs to be written to a CDR file before a new file is started.
|
0 (no rollover) |
||||
MaxInterval |
Number of milliseconds of operation before time-based file rollover. If a CDR file is used for more than The value must be either
|
0 (no rollover) |
||||
Header |
If
|
True |
||||
Footer |
If
|
True |
||||
CreateEmptyFiles |
If If |
False |
||||
ArchiveCommand |
Command to run on each CDR file completion.
If empty, no command is run.
|
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 If
|
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 |
30000 (30 seconds) |
||||
WriteSync |
If If
|
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 |
||
%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
|
||
%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 |
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 |
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.
| |
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.
| |
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.
| |
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…
|
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.
| |
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
| |
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.
| |
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:
-
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 the creation, writing, and reading of 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:
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.
| |
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).
| |
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
FDescriptorcontains encoded bytes representing acom.google.protobuf.Descriptors.FileDescriptor(effectively the.protofile), with the definition of the extension. -
The
EDescriptorprovides a name of the extension field and reference to theFDescriptorcontaining 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
|
||
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]...
The The This tool also supports CDR binary files in gzip format. Each file that ends with a |
| |
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.
| |
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.
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
|
||
-f <cdrfile> [<cdrfile>]... --files <cdrfile> [<cdrfile>]... |
Binary CDR files to process.
|
||
-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
|
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.
| |
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 |
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
-
jarfiles in thelibdirectory of the CDR resource adaptor package -
directories specified in the
OPT_JAR_LISTenvironment 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. |
|
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. |
|
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. |
|
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
cleared
The write thread has been operating normally with no timeouts for at least 2* |
|
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. |
|
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. |
|
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
cleared
A CDR file is successfully archived without errors. |
|
||
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. |
|
||
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.
|
|
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.
| |
See also
Active Reconfiguration. |
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>
| |
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
|
|||||||||||||||
3 |
The properties in
|
|||||||||||||||
4 |
To deploy the examples, using Ant, execute the $ 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:
|
| |
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.
| |
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.
|
||
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 |
||
4 |
To create a temporary $ cd $RHINO_HOME/cdr-ra-VERSION/examples $ ant run-db-insert-cdr-processor This invokes the
|
| |
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. |