This guide is for developers who develop applications that run on the Rhino Telephony Application Server (TAS) platform. The purpose of the guide is to introduce the static object identifier (OID) model and provide instructions for assigning static OIDs based on the model.

The guide assumes that you are familiar with the following:

  • The Java APIs for integration networks (JAIN) service logic execution environment (SLEE) standard

  • The Rhino TAS platform

  • The development, building, and deployment of Rhino applications

Key information in this guide is as follows:

  • Introduction of the static OID model and its architecture

  • Static OID assignment methods and examples

  • Static OID validation

  • Things to note during the application building and deployment process

Notices

Copyright © 2024 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.

Static OID introduction

Rhino 3.1 introduces a static OID model. In this model, Rhino no longer dynamically assigns OIDs to statistics in an application.

The static OID model splits the OID of each statistic into OID parts. During application development, developers manually assign an OID part to each Rhino artifact, such as a service or a parameter set type. At deployment time, Rhino combines the OID parts of relevant artifacts to form a full static OID for each statistic.

Rhino uses OIDs to expose statistics through SNMP. The OIDs of the statistics that operators monitor through SNMP must remain the same when the relevant application is upgraded. Otherwise, the monitoring will break. As the static OID model ensures that the OIDs of the statistics don’t change between versions by assigning OIDs statically, operators can continue to monitor statistics after application upgrade. In addition, with the static OID model, administrators don’t need to manually retain the OIDs dynamically assigned in an earlier version.

The static OID model requires you to manually assign OID parts to Rhino artifacts during application development. Different assignment methods are provided to cater to different development situations. For example, you can use compile-time Java annotations to assign an OID for a resource adaptor. The Assigning OID parts sections provide detailed information about OID assignment methods and assignment examples.

Terminology

This section describes the industry terms and the Rhino-specific terms that this guide uses.

The following table lists the industry terms. When necessary, it also supplies product-specific information related to the term.

Term Definition

DTD

Document type definition (DTD); a set of declarations that define the legal structure, elements, and attributes of a type of SGML document.

MIB

Management information base (MIB); an ASN.1 based data structure description that describes the structure of the attributes that a system exposes for monitoring and configuration.

OID

Object identifier (OID); a string of numbers that identifies a statistic that can be read through SNMP. For example, 1.3.6.1.4.1.19808.20.5.4.1.4.3.1.1.100.1.1.1.

SNMP

Simple network management protocol (SNMP); an application-level protocol used primarily for network device management and monitoring.

Rhino TAS includes an SNMP agent for interoperability with external SNMP-aware management clients. For more information, see Rhino Administration and Deployment Guide.

The following table lists the Rhino-specific terms:

Term Definition

Base OID

The prefix nodes of a full OID, rooted at the base of the global OID hierarchy. For example, 1.3.6.1.4.1.19808.20.5.4.1.

OID part

A subset of nodes of a complete OID. For example, a base OID or an OID suffix is an OID part.

OID suffix

An OID part that can be appended to a base OID. For example, 1, 4.3 or 1.100.1.1.1.

OID suffix mappings descriptor

A JSON text document that specifies OID suffix mappings for arbitrary resource adaptor entities or profile tables. Deployed into Rhino TAS together with relevant components.

Parameter set

An instance of a parameter set type.

Parameter sets can have special characteristics such as aggregation of statistics from the child parameter sets of the same parameter set type.

Parameter set type

A definition that describes a particular set of statistics available from a deployed component or subsystem. A parameter set type consists of a statistics interface and the metadata that describes the statistics it contains.

Singleton parameter set type

A parameter set type that can have only one parameter set created from it.

Statistics interface

A usage parameters interface for SLEE-style usage or a statistics parameter set type interface for Rhino-style usage.

Requirements

The methods of assigning OID parts include using compile-time annotations, runtime annotations, manually created deployment descriptors, or OID suffix mappings descriptors. Each of these OID assignment methods requires its own support module.

The following table lists the modules required by different OID assignment methods:

Module Minimum version Purpose

slee-extensions

3.1

Provides Rhino extension document type definitions (DTD).

slee-annotations

3.1

Supports compile-time annotation for OID and MIB alias assignments, and generates extension deployment descriptors.

stats-annotations

3.1

Supports compile-time annotation for OID and MIB alias assignments for resource adaptors, and generates extension deployment descriptors. These annotations support the Rhino-specific statistics model for resource adaptors.

rhino-ra

3.1

Supports runtime annotation for OID assignments.

Each deployment descriptor for assigning static OIDs and MIB aliases must conform to a version of the relevant Rhino SLEE extension DTD, which the slee-extensions module defines.

The following table lists the DTDs and their minimum versions required:

Rhino extension DTD Minimum version

Profile specification

1.1.3

Resource adaptor

1.1.7

SBB

1.1.4

Service

1.4

Set the DTD version in the header of the deployment descriptor. In the following example, the header of the oc-resource-adaptor-jar.xml extension deployment descriptor shows that the deployment descriptor uses the 1.1.7 version of the resource adaptor extension DTD.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE oc-resource-adaptor-jar PUBLIC
     "-//Open Cloud Ltd.//DTD JAIN SLEE Resource Adaptor Extension 1.1.7//EN"
     "http://www.opencloud.com/dtd/oc-resource-adaptor-jar_1_1_7.dtd">

Architecture

In the static OID model, you define OID parts for individual Rhino artifacts.

The model organizes the OID parts as follows:

  • Base OIDs for services, resource adaptors, or profile specifications

  • Intermediate OIDs for SBBs, resource adaptor entities, or profile tables

  • Usage parameter OIDs, comprised of parameter set type OID suffixes, statistic OID suffixes, and optionally, parameter set OID suffixes

At deployment time, Rhino forms a complete OID by combining a base OID and relevant OID suffixes.

Subsequent subsections provide details about this structure and examples of forming complete OIDs based on it.

OID structure

The structure of a complete OID for a Rhino statistic is as follows:

<base OID>.[<intermediate OID subtree suffix>].<intermediate OID>.<usage parameter OID subtree suffix>.<usage parameter OID>

This structure divides an OID into five logical parts:

  • Base OID

  • Intermediate OID subtree suffix

  • Intermediate OID

  • Usage parameter OID subtree suffix

  • Usage parameter OID

OID parts are separated with periods. For example, if the value of the base OID is 1.3.6 and the value of the intermediate OID subtree suffix is 1, the combined OID is 1.3.6.1.

Base OID

This part defines the base OIDs for a service, a resource adaptor, or a profile specification.

A base OID consists of multiple parts. For example, the base OID of the Sentinel VoLTE SIP service is 1.3.6.1.4.1.19808.20.5.4.1, which has the following parts:

  • 1.3.6.1.4.1.19808: The private enterprise OID for OpenCloud.

  • 20: The OID subtree allocated to products that use the static OID model.

  • 5: The OID subtree for VoLTE-specific artifacts.

  • 1: The OID subtree for the Sentinel VoLTE SIP service component.

Intermediate OID subtree suffix

This part defines the intermediate OID subtree suffix for an SBB. It splits the OID domain into two subtrees:

  • 1: For component-defined statistics. All statistics defined by an SBB component or its parameter set types fall into this subtree.

  • 2: For Rhino-generated statistics.

Intermediate OID

This part defines the OID suffix for an SBB, a resource adaptor entity, or a profile table.

For example, you can assign the value of 1 as the OID suffix for a SIP resource adaptor entity.

Usage parameter OID subtree suffix

This part defines the OID subtree suffix for a usage parameter. It applies to all component types.

The subtree suffix also splits the OID domain into two subtrees:

  • 1: For component-defined statistics. All statistics defined by a parameter set type fall into this subtree.

  • 2: For Rhino-generated statistics.

Note Currently, Rhino-generated statistics only exist for services. Resource adaptors and profile specifications include this subtree suffix as a reservation for future use.

Usage parameter OID

You can declare a parameter set type as a singleton type or a non-singleton type. A singleton type can have only one parameter set created from it, while a non-singleton type can have more than one parameter set created from it. Accordingly, a parameter set can be of a singleton type or a non-singleton type.

For singleton parameter set types, the structure further divides the usage parameter OID part as follows:

<Parameter set type OID suffix>.<Statistic OID suffix>

For non-singleton parameter set types, the structure further divides the usage parameter OID part as follows:

<Parameter set type OID suffix>.<Parameter set subtree suffix>.<Parameter set OID suffix>.<Statistic OID suffix>

Parameter set type OID suffix

This part defines the OID suffix for a parameter set type.

To register a parameter set type in the SNMP subsystem using the static OID model, assign an OID suffix to it.

Parameter set subtree suffix

This part only applies when the relevant statistic uses a non-singleton parameter set. It defines the subtree suffix for the parameter set.

If the non-singleton parameter set is statically mapped, the value of the parameter set subtree suffix is 1. Otherwise, the value is 2.

Parameter set OID suffix

This part only applies when the relevant statistic uses a statically mapped non-singleton parameter set. It defines the OID suffix for the parameter set.

To register such a parameter set in the SNMP subsystem using the static OID model, assign an OID suffix to it.

Statistic OID suffix

This part defines the OID suffix for a statistic.

To expose the statistic of a usage parameter through SNMP, assign an OID to it in the relevant statistics interface.

Note If the value of the parameter set subtree suffix is 2, Rhino generates SNMP tabular entries and appends relevant table row information to the static OID suffix. For more information about SNMP tables, see the SNMP table format section in Rhino Administration and Deployment Guide.

OID example

This section provides two examples that show how Rhino constructs OIDs from their constituent parts.

Example one

The first example uses a SIP resource adaptor to illustrate how all the pieces fit together to create the OID for a counter statistic.

The example makes the following assumptions:

  • A resource adaptor entity of the SIP resource adaptor called sipra is created, and its name is statically mapped to the OID suffix of 1.

  • The adaptor has a parameter set type called BigGroupStats, and this parameter set type has a counter called forksStarted. The following static OID information is defined for this counter:

    • The SIP resource adaptor has a base OID of 1.3.6.1.4.1.19808.20.2.1.

    • The BigGroupStats parameter set type has an OID suffix of 2.4.

    • The forksStarted counter has an OID mapping of 2.

Based on the OID structure, each part of the OID is as follows:

  • Base OID: 1.3.6.1.4.1.19808.20.2.1

  • Intermediate OID subtree suffix: This part doesn’t apply to resource adaptors.

  • Intermediate OID: 1

  • Usage parameter subtree suffix: 1

  • Usage parameter OID: 2.4 for the parameter set type and 2 for the counter.

Putting these together, Rhino registers the forksStarted counter of the BigGroupStats parameter set type that the sipra resource adaptor entity creates with the OID of 1.3.6.1.4.1.19808.20.2.1.1.1.2.4.2.

Example two

The second example still uses the base OID and the intermediate OID in the first example.

In this example, consider the Transactions parameter set type of the SIP resource adaptor. This type has a counter statistic called serverTransactionsActive, and the following static OID information is defined for this counter:

  • The TransactionStats parameter set type has an OID suffix of 2.2.

  • Some parameter set names are defined for the parameter set type TransactionStats, and one of these maps the parameter set name Transactions.INVITE to the OID suffix of 2.

  • The serverTransactionsActive counter in the Transactions.INVITE parameter set has an OID suffix of 9.

For the usage parameter OID, the value of the parameter set subtree suffix is 1 because the parameter set is non-singleton and the OID suffix of the parameter set is statically mapped.

Putting these together similarly, Rhino registers the serverTransactionsActive counter in the parameter set Transactions.INVITE of the Transactions parameter set type with the OID of 1.3.6.1.4.1.19808.20.2.1.1.1.2.2.1.2.9.

Assigning OID parts

Subsequent subsections describe OID assignment methods, provide relevant assignment examples, and list the best practices for avoiding OID conflicts during the assignment.

You can assign each OID part together with a MIB alias, which provides a textual representation of an OID. MIB aliases don’t change across product upgrades although component identities may change, which can make the upgrade process smoother.

Warning If the OID part for an artifact is missing, Rhino doesn’t form complete OIDs for relevant statistics, and that makes it impossible for operators to monitor those statistics.

Assignment methods

In the static OID model, you must manually assign OID parts to individual Rhino artifacts such as SBBs or parameter set types. Rhino combines different OID parts to form complete OIDs at deployment time.

The methods for assigning OID parts are as follows:

  • Use deployment descriptors

  • Use runtime code annotation introspection

  • Use an OID suffix mappings descriptor

Use deployment descriptors

This method applies to artifacts other than profile tables and resource adaptor entities.

To assign OID parts with this method, add OID assignment annotations onto the component’s Java class by importing the annotations from the slee-annotations or the stats-annotations module. From these annotations, the annotation processor automatically generates a deployment descriptor for the corresponding component at compile time.

Alternatively, create a deployment descriptor manually by writing appropriate static OID assignment elements in the deployment descriptor. For example, you can declare the OID suffix for an SBB by using the attributes of the <stats-presentation> element in the Rhino extension deployment descriptor.

Deploy the automatically generated or manually created deployment descriptors with relevant components. For more information, see Build and deployment script considerations.

Use runtime code annotation introspection

This method applies to artifacts other than profile tables and resource adaptor entities.

To assign OID parts with this method, import relevant annotations from the rhino-ra module, and then add annotations onto the component’s Java class that are read at runtime. This method doesn’t require any deployment descriptors.

For more information, see the usage extensions section in Rhino Extended APIs.

Use an OID suffix mappings descriptor

This method applies only to profile tables and resource adaptor entities.

You cannot assign OID parts for resource adaptor entities or profile tables during application development because their names aren’t known at the time. Assign OID parts for resource adaptor entities and profile tables in an application with an OID suffix mappings descriptor, which is a JSON document consisting of an identity and a list of OID mappings.

Deploy the OID suffix mappings descriptor document into Rhino together with the relevant application.

For information about creating an OID suffix mappings descriptor, see Create an OID suffix mappings descriptor.

Create an OID suffix mappings descriptor

Create an OID suffix mappings descriptor document for assigning OID suffixes to resource adaptor entities and profile tables in an application either manually or from an input template.

This section provides instructions on creating the document manually. For information about creating the document using an input template, see Substitute OID mappings in OID suffix mappings descriptors.

The process of creating an OID suffix mappings descriptor is as follows:

  1. Find out what resource adaptor entities and profile tables you need to deploy with the application.

    • Decide the OID mappings by the deployment of the whole application rather than individual components.

    • Consider co-deployments of the application with other applications.

      The OID suffix mappings descriptor of an application assigns the OID suffixes of the resource adaptor entities or profile tables in the application. There may be potential OID conflicts between the OID suffix mappings descriptors of different applications.

      Tip Resource adaptor entities with different names should generally have different OID suffixes.

    • For the deployment of an existing application, find out what resource adaptor entities and profile tables are currently deployed by using the listraentities and listprofiletables Rhino management console commands.

  2. Create an OID suffix mappings descriptor to assign an OID suffix to each resource adaptor entity and profile table in the application.

    The following example adds OID suffix mappings for three HTTP resource adaptor entities with an OID suffix mappings descriptor.

    {
  "name": "HTTP",
  "vendor": "OpenCloud",
  "version": "1.0",
  "resourceAdaptorEntities": [
    {
      "name": "${httpserver.ra.raentity}",
      "oidSuffix": "1"
    },
    {
      "name": "${httpclient.ra.raentity}",
      "oidSuffix": "2"
    },
    {
      "name": "duplicate-${httpclient.ra.raentity}",
      "oidSuffix": "3"
    }
  ]
}

Assignment examples

With the methods described in Assignment methods, assign OID parts to Rhino artifacts in an application. Subsequent subsections provide OID assignment examples for various Rhino artifacts.

Note The examples in the subsections contain OID parts represented as variables that are substituted at build time. Define these variables in a database or a similar shared store.
Note Currently Rhino doesn’t support sample type statistics in SNMP, so only examples for the counter type statistics are provided.

Services

A service requires a base OID assigned to it. This base OID forms part of the OIDs registered for that service’s statistics.

A service may also have a MIB alias assigned to it. The MIB alias of each deployed service must be unique among all deployed services.

The example below defines a base OID and a MIB alias for the SHCM service with the Java annotation @ServiceStatsPresentation:

@OcSleeService(
    statsPresentation=@ServiceStatsPresentation(alias="SHCM", baseOid="@oid.products.sentinel.shcm.services.sh-cache@")
)

From the annotation in this example, the compile-time annotation processor generates the corresponding entry in an extension deployment descriptor, as shown below:

<oc-service-xml>
    <service id="SHCM">
        <stats-presentation alias="SHCM" base-oid="${oid.products.sentinel.shcm.services.sh-cache}"/>
    </service>
</oc-service-xml>

The Java annotation and the extension deployment descriptor above are equivalent.

Resource adaptors

If a resource adaptor defines a parameter set type, assign a base OID to it. This base OID forms part of the OIDs registered for that resource adaptor’s statistics. A resource adaptor may also have a MIB alias assigned to it.

The following example shows the Java annotation @ResourceAdaptorStatsPresentation defining a base OID and a MIB alias for a resource adaptor.

@OcResourceAdaptor(
    statsPresentation=@ResourceAdaptorStatsPresentation(
        alias="CQLRA",
        baseOid="@oid.products.resource-adaptors.cassandra-cql@")
)

From the annotation in this example, the compile-time annotation processor generates the corresponding entry in an extension deployment descriptor, as shown below:

<oc-resource-adaptor-jar>
    <resource-adaptor id="CQLRA">
        <stats-presentation alias="CQLRA" base-oid="${oid.products.resource-adaptors.cassandra-cql}"/>
    </resource-adaptor>
</oc-resource-adaptor-jar>

The Java annotation and the extension deployment descriptor above are equivalent.

Profile specifications

If a profile specification defines a parameter set type, assign a base OID to it. The base OID forms part of the OIDs registered for that profile specification’s statistics. A profile specification can also have a MIB alias assigned to it.

The example below shows a Java annotation @ProfileStatsPresentation defining a base OID and a MIB alias for a profile specification.

@OcProfile(
    statsPresentation=@ProfileStatsPresentation(
        baseOid="@oid.products.sentinel.core.profile-specs.FeatureExecutionScriptProfile@",
        alias="FeatureExecutionScript"
    )
)

From the annotation in this example, the compile-time annotation processor generates the corresponding entry in an extension deployment descriptor, as shown below:

<oc-profile-spec-jar>
    <profile-spec id="FeatureExecutionScript">
        <stats-presentation alias="FeatureExecutionScript" base-oid="${oid.products.sentinel.core.profile-specs.FeatureExecutionScriptProfile}"/>
    </profile-spec>
</oc-profile-spec-jar>

The Java annotation and the extension deployment descriptor above are equivalent.

SBBs

Each SBB that defines one or more parameter set types within a service requires a unique OID suffix. This OID suffix forms part of the OIDs registered for that SBB’s statistics.

Always define OID suffixes for SBBs to allow for easy addition of new statistics and consistency among all SBBs. Each SBB may also have a MIB alias assigned to it.

The example below shows the Java annotation @SBBStatsPresentation defining an OID suffix and a MIB alias for an SBB:

@OcSBB(
    statsPresentation=@SBBStatsPresentation(
        alias="IMSSFCallLeg",
        oidSuffix="@oid.products.imssf.sbbs.CallLegSbb@",
    )
)

From the annotation in this example, the compile-time annotation processor generates the corresponding entry in an extension deployment descriptor, as shown below:

<oc-sbb-jar>
    <sbb id="CallLeg">
        <stats-presentation alias="IMSSFCallLeg" oid-suffix="${oid.products.imssf.sbbs.CallLegSbb}"/>
    </sbb>
</oc-sbb-jar>

The Java annotation and the extension deployment descriptor above are equivalent.

Resource adaptor entities

Set the OID suffix for a resource adaptor entity in an OID suffix mappings descriptor. The OID suffix forms part of the OIDs registered for that resource adaptor entity’s statistics.

Each resource adaptor entity of a resource adaptor component must have a unique OID suffix. Otherwise, an OID conflict occurs.

The following example shows an OID suffix mappings descriptor that specifies an OID suffix for the cqlra resource adaptor entity.

{
  "name": "example-resource-adaptor-entity-binding",
  "vendor": "vendor",
  "version": "1.0.0",

  "resourceAdaptorEntities": [
    {
      "name": "cqlra",
      "oidSuffix": "${oid.products.resource-adaptors.cassandra-cql.resource-adaptor-entities.primary}"
    }
  ]
}

Profile tables

Set the OID suffix for a profile table in an OID suffix mappings descriptor. This OID suffix forms part of the OIDs registered for that profile table’s statistics.

Each profile table of a profile specification must have a unique OID suffix. Otherwise, an OID conflict occurs.

The following example shows an OID suffix mappings descriptor that defines an OID suffix for the FeatureExecutionScriptTable profile table.

{
  "name": "example-profile-table-binding",
  "vendor": "vendor",
  "version": "1.0.0",

  "profileTables": [
    {
      "name": "FeatureExecutionScriptTable",
      "oidSuffix": "${oid.products.sentinel.core.profile-specs.FeatureExecutionScriptProfile.profile-tables.FeatureExecutionScriptTable}"
    }
  ]
}

Parameter set types

Each parameter set type may have an OID suffix assigned to it. The OID suffix forms part of the OIDs registered for that parameter set type’s statistics.

A component’s parameter set types must each have a unique OID suffix. Otherwise, an OID conflict occurs.

Assign the OID suffix of a parameter set type with the statistic presentation options defined in the component’s deployment descriptor or in an annotation on its class file.

A parameter set type may be a singleton or a non-singleton. The following example shows a Java annotation, which specifies the statistic presentations of two singleton parameter set types for a resource adaptor.

@OcResourceAdaptor(
    statsPresentation=@ResourceAdaptorStatsPresentation( //This can also be @SBBStatsPresentation or @ProfileStatsPresentation for their corresponding component types.
        alias="RFControl",
        baseOid="@oid.products.sentinel.core.resource-adaptors.rf-control@",
        usageParametersInterfaceTypeOidMappings = {
            @UsageParametersInterfaceTypeOidMapping(interfaceTypeName="ExecutorStats", singleton=true, oidSuffix="@oid.products.sentinel.core.resource-adaptors.rf-control.parameter-set-types.ExecutorStats@"),
            @UsageParametersInterfaceTypeOidMapping(interfaceTypeName="ProxyStats", singleton=true, oidSuffix="@oid.products.sentinel.core.resource-adaptors.rf-control.parameter-set-types.ProxyStats@"),
        }
    )
)

From the annotation in this example, the compile-time annotation processor generates the corresponding entries in an extension deployment descriptor, as shown below:

<oc-resource-adaptor-jar>
    <resource-adaptor id="rf-control-ra-id">
        <stats-presentation alias="RFControl" base-oid="${oid.products.sentinel.core.resource-adaptors.rf-control}">
            <usage-parameters-interface-type-oid-mapping usage-parameters-interface-type-name="ExecutorStats" oid-suffix="${oid.products.sentinel.core.resource-adaptors.rf-control.parameter-set-types.ExecutorStats}" singleton="True"/>
            <usage-parameters-interface-type-oid-mapping usage-parameters-interface-type-name="ProxyStats" oid-suffix="${oid.products.sentinel.core.resource-adaptors.rf-control.parameter-set-types.ProxyStats}" singleton="True"/>
        </stats-presentation>
    </resource-adaptor>
</oc-resource-adaptor-jar>

The Java annotation and the extension deployment descriptor above are equivalent.

Parameter sets

If a parameter set is used for statistics, assign an OID suffix to it.

The following example shows a Java annotation, which specifies a non-singleton parameter set type’s statistic presentation of three parameter sets for a resource adaptor.

@OcResourceAdaptor(
    statsPresentation=@ResourceAdaptorStatsPresentation( // this can also be @SBBStatsPresentation, @ProfileStatsPresentation for their corresponding component types.
        alias = "OCSIP",
        baseOid = "@oid.products.resource-adaptors.sip@",
        usageParametersInterfaceTypeOidMappings = {
            @UsageParametersInterfaceTypeOidMapping(interfaceTypeName="TransportStats", oidSuffix="@oid.products.resource-adaptors.sip.parameter-set-types.TransportStats@",
                parameterSetNameMappings={
                    @UsageParameterSetNameOidMapping(name="Transport", oidSuffix="@oid.products.resource-adaptors.sip.parameter-set-types.TransportStats.parameter-sets.Transport@"),
                    @UsageParameterSetNameOidMapping(name="Transport.UDP", oidSuffix="@oid.products.resource-adaptors.sip.parameter-set-types.TransportStats.parameter-sets.TransportUDP@"),
                    @UsageParameterSetNameOidMapping(name="Transport.UDP", oidSuffix="@oid.products.resource-adaptors.sip.parameter-set-types.TransportStats.parameter-sets.TransportTCP@")
                }
            )
    )
)

From the annotation in this example, the compile-time annotation processor generates the corresponding entries in an extension deployment descriptor, as shown below:

<oc-resource-adaptor-jar>
    <resource-adaptor id="OCSIP">
        <stats-presentation alias="OCSIP" base-oid="${oid.products.resource-adaptors.sip}">
            <usage-parameters-interface-type-oid-mapping usage-parameters-interface-type-name="TransportStats" oid-suffix="${oid.products.resource-adaptors.sip.parameter-set-types.TransportStats}">
                <usage-parameter-set-name-oid-mapping name="Transport" oid-suffix="${oid.products.resource-adaptors.sip.parameter-set-types.TransportStats.parameter-sets.Transport}"/>
                <usage-parameter-set-name-oid-mapping name="Transport.UDP" oid-suffix="${oid.products.resource-adaptors.sip.parameter-set-types.TransportStats.parameter-sets.TransportUDP}"/>
                <usage-parameter-set-name-oid-mapping name="Transport.TCP" oid-suffix="${oid.products.resource-adaptors.sip.parameter-set-types.TransportStats.parameter-sets.TransportTCP}"/>
            </usage-parameters-interface-type-oid-mapping>
        </stats-presentation>
    </resource-adaptor>
</oc-resource-adaptor-jar>

The Java annotation and the extension deployment descriptor above are equivalent.

Counter statistics

Assign each counter statistic an OID suffix, which forms part of the OID registered for the statistic. The OID suffix is used to differentiate between different statistics in a usage parameter interface.

Note Counter mappings must only start from "2" as Rhino reserves numbers less 2.

The following example shows a Java annotation in a usage parameter interface that maps OID suffixes to two counter statistics at runtime. This is the recommended method for assigning OID mappings for usage parameter interfaces and counter statistics.

import com.opencloud.rhino.facilities.usage.UsageCounter;
import com.opencloud.rhino.facilities.usage.CounterType;

public interface WorkerPoolStats {

    @UsageCounter(mapping=2, shortName="totalThrd", description="Total number of SIP worker threads", counterType=CounterType.GAUGE)
    public void incrementThreadsTotal(long value);

    @UsageCounter(mapping=3, shortName="availThrd", description="Number of available SIP worker threads", counterType=CounterType.GAUGE)
    public void incrementThreadsAvailable(long value);

}

The following example shows the compile-time Java annotations in a usage parameters interface that assigns OID suffixes to the counter statistics.

import com.opencloud.monitoring.annotations.*;

@ParameterSetInterface("WorkerPoolStats")
@Description("SIP RA thread pool statistics")
public interface WorkerPoolStats {

    @Gauge
    @Description("Total number of SIP worker threads")
    @ShortName("totalThrd")
    @SNMPMapping(2)
    void incrementThreadsTotal(long value);

    @Gauge
    @Description("Number of available SIP worker threads")
    @ShortName("availThrd")
    @SNMPMapping(3)
    void incrementThreadsAvailable(long value);

From the compile-time annotations in the example above, the annotation processor generates the corresponding entries in a deployment descriptor, as shown below:

<stats-parameter-sets>
    <stats-parameter-set-type description="SIP RA thread pool statistics" interface="com.opencloud.slee.resources.sip.stats.WorkerPoolStats" name="WorkerPoolStats">
        <counter aggregate="True" default-view="gauge" description="Total number of SIP worker threads" is-replicated="False" mapping="2" name="threadsTotal" short-name="totalThrd"/>
        <counter aggregate="True" default-view="gauge" description="Number of available SIP worker threads" is-replicated="False" mapping="3" name="threadsAvailable" short-name="availThrd"/>
    </stats-parameter-set-type>
</stats-parameter-sets>

The Java annotations and the extension deployment descriptor above are equivalent.

Best practices to avoid OID conflicts

As different statistics assigned the same OIDs will be inaccessible through SNMP, take measures to ensure that there are no OID conflicts.

  • The runtime annotations provided by the rhino-ra module are the easiest way to assign OIDs. These annotations keep the statistic metadata and code together. You can use runtime annotations for parameter set interfaces and counter statistics.

  • The compile-time annotations provided by the slee-annotations module and the stats-annotations module overlap significantly. Don’t combine these annotations within an application.

  • Don’t combine multiple OID assignment methods within a product. For example, if you use compile-time annotations to assign OIDs, avoid using manually written deployment descriptors.

  • Parameter set types shared between different components need different OID suffixes. Assign OID suffixes for such parameter set types with compile-time annotations or in deployment descriptors. Don’t assign with annotations that are introspected at runtime as that may lead to OID conflicts.

  • Allocate separate blocks of numbers for each usage parameters interface in an inheritance hierarchy. For example, a base usage parameters interface would have OID suffix values ranging from "2" to "99" while an extension of that interface would have OID suffix values ranging from "100 to 199", "200 to 299", and so on. This is to avoid an OID clash with interfaces extending the base usage parameters interface if the base interface is expanded with more parameters.

  • Avoid hard-coding OID parts within annotations or deployment descriptors, as it’s difficult to see what OIDs are assigned before compiling and deploying the application. Instead, store the OIDs for the application in a file that has the same version used by all releases and development branches. This provides a clear view of the OID coverage for different components and parameter set types.

Validating static OIDs

To make sure that every counter statistic of each component in a deployed application has a static OID assigned with no OID conflicts, validate the static OID parts and MIB aliases after assigning them.

Use one of the following methods to validate your OID assignments:

  • Rhino alarms

  • Rhino management console commands

  • Manual inspection

Subsequent subsections provide details about these validation methods.

OID conflict alarms

When a component is deployed, Rhino raises an alarm if it detects an OID conflict between two statistics. The alarm shows the static OID that two or more statistics are sharing.

For further information about the alarms for duplicate OIDs, see the Alarms section in the Rhino Administration and Deployment Guide.

Rhino console commands

This section lists the Rhino management console commands for inspecting the static OID coverage in a deployment. You can also get a list of these commands with the help static command.

For details about these commands, see the viewing SNMP static OIDs section in Rhino Administration and Deployment Guide.

auditsnmpstaticoids

This command checks whether the installed components have all their OID parts, counter mappings, and MIB aliases set.

The command returns a pass/fail result. In a fail result, use the JSON formatted output of the audit results to examine where audit for OID coverage has failed. This output describes where a static OID part or MIB alias may be missing.

listsnmpstaticmappingsbycomponent

This command lists the mapped MIB aliases and OID parts of all installed components. It allows you to see which components have mappings.

Note If there are missing statistics for a component that don’t cause an audit failure, this command shows that the base OID for the component isn’t set.

listsnmpstaticoids

This command lists all the parameter set types and their assigned static OIDs.

If there is no static mapping for a parameter set type, the output is displayed as --cleared--, which implies that a static OID mapping is missing for the parameter set type or its parent components.

Note The metric CMP parameter set types don’t support static OIDs, so --cleared-- is displayed for them.

listsnmpstaticoidsuffixmappings

This command lists the static OID mappings installed for profile tables and resource adaptors. Use it to verify the profile table and resource adaptor entity mappings.

The command shows whether the OID suffix mappings descriptor documents installed on a deployed Rhino instance account for every profile table and resource adaptor entity mapping.

listsnmpstaticoidcountersuffixes

This command lists all OID suffixes assigned to each counter mapping.

Use it to find where there may be missing OID suffix mappings to counter statistics.

Manually inspecting deployment descriptors

Note This method doesn’t work for OID parts that you specify with annotations introspected at runtime.

If you set OID parts and MIB aliases using annotations that generate deployment descriptor entries or set them directly in the deployment descriptor of a component, inspect the component’s deployment descriptors to verify the OID or alias assignments.

The deployment descriptors in the META-INF directory of the built jar file contain the component’s OID mappings. After compilation, inspect these deployment descriptors to find where a misused annotation or deployment descriptor attribute impacts the component.

Typical issues in deployment descriptors include:

  • The OID setting variables aren’t replaced with valid OID parts during the compile and build process.

  • The OID part isn’t in the oid-suffix or base-oid field of the deployment descriptor. This implies a missing field in the annotation used to assign the mapping.

Find the static OID mappings for different components in the following deployment descriptors:

  • Service: oc-service.xml

  • SBB: oc-sbb-jar.xml

  • Resource adaptor: oc-resource-adaptor-jar.xml

  • Profile: oc-profile-spec-jar.xml

For more information about these deployment descriptors, see relevant sections in the Rhino Extended APIs.

Build and deployment script considerations

After adding new static OIDs and MIB alias to a component, change relevant build and deployment scripts to process the OID assignments. For example, substitute the OID assignment variables with actual OID values; package an OID suffix mappings descriptor document with the relevant component.

Subsequent subsections describe the considerations you need to make when making build or deployment script changes.

Substituting OID mappings

To assign static OIDs, either hard-code the OIDs directly or store them in properties files. Using a properties file can prevent OID conflicts by having a view of OID coverage before compilation and deployment.

Subsequent subsections assume you use a properties file to store the OIDs. To complete the OID assignment in this case, load the properties file in a build script, and then substitute OID mappings with the values defined in the properties file.

The following example Ant script fragment loads the properties in an example-oid-mapping.properties file into the build process’s environment. Use build scripts to substitute the OID parts defined in this file into OID assignments in annotations and deployment descriptors.

<property file="example-oid-mappings.properties"/>

Substitute OID mappings in annotations

If you use annotations to declare OID assignments, include a dependency on the ant-update-bytecode plugin in the module build script to substitute the OID parts into the compiled classes.

The following example shows an annotation that an Ant task will process to replace the token with the OID part from the relevant imported property.

@ParameterSetInterface("ExecutorStats")
@Description("Thread-pool task execution statistics")
@SNMPOIDSuffix("@oid.parameter-set-types.core-util.ExecutorStats@")

The update-bytecode Ant task can process the value in the @SNMPOIDSuffix annotation by replacing the @…​@ string with the value of the relevant referenced property.

The following script shows the usage of the update-bytecode Ant task. Use the script after compilation but before building the jar file.

<oc:update-bytecode>
  <replaceproperties annotations="true"/>
  <fileset dir="${classes}">
    <include name="**/*Stats.class"/>
  </fileset>
</oc:update-bytecode>

Substitute OID mappings in deployment descriptors

If you use deployment descriptors to declare OID assignments, use a build script to substitute the OID assignment variables with relevant imported properties.

To do the substitution. use the Ant copy task in the build script.

The following code example is from an extension deployment descriptor. In this example, the build script is to substitute the variables ${oid.products.resource-adaptors.http.parameter-set-types.ClientStats} and ${oid.products.resource-adaptors.http.parameter-set-types.ServerStats}.

<stats-parameter-sets>
    <stats-parameter-set-type name="HTTP.ClientStats" interface="com.opencloud.slee.resources.http.transport.stats.ClientStats" description="HTTP RA client statistics"/>
    <stats-parameter-set-type name="HTTP.ServerStats" interface="com.opencloud.slee.resources.http.transport.stats.ServerStats" description="HTTP RA server statistics"/>
    <root-parameter-set-name>HTTP</root-parameter-set-name>
</stats-parameter-sets>

<stats-presentation alias="HTTPRA" base-oid="${oid.products.resource-adaptors.http}">
    <usage-parameters-interface-type-oid-mapping usage-parameters-interface-type-name="HTTP.ClientStats" oid-suffix="${oid.products.resource-adaptors.http.parameter-set-types.ClientStats}" singleton="True"/>
    <usage-parameters-interface-type-oid-mapping usage-parameters-interface-type-name="HTTP.ServerStats" oid-suffix="${oid.products.resource-adaptors.http.parameter-set-types.ServerStats}" singleton="True"/>
</stats-presentation>

The following snippet from the build script build.xml shows how to use the Ant copy task to do the substitution.

<property file="${self.oid-mappings.properties}"/>

<mkdir dir="${classes}/diameter-ro-replication-test-service"/>
<copy todir="${classes}/diameter-ro-replication-test-service/META-INF">
    <fileset dir="${src}/com/opencloud/slee/diameter/test/replication/ro/META-INF" includes="*.xml"/>
    <filterchain>
        <expandproperties/>
    </filterchain>
</copy>

Use this script before building the jar file. The resultant deployment descriptor must be in the file path for the component’s jar build task.

Substitute OID mappings in OID suffix mappings descriptors

Create an OID suffix mappings descriptor for assigning OID suffixes to resource adaptor entities or profile tables either manually or from an input template. If you use an input template, substitute relevant variables in the template with the values from relevant imported properties.

Take the following template called oid-suffix-mappings.json as an example:

{
  "name": "Database Query",
  "vendor": "${dbquery.vendor}",
  "version": "${dbquery.version}",

  "resourceAdaptorEntities": [
    {
      "name": "${dbquery-ra-entity.name}",
      "oidSuffix": "${oid.products.resource-adaptors.dbquery.resource-adaptor-entities.primary}"
    }
  ]
}

To substitute the OID assignment variables in this file, use the Ant copy task in the build script to expand the properties, as shown below:

<property file="${self.oid-mappings.properties}"/>

<mkdir dir="${classes}"/>
<copy todir="${classes}/META-INF">
    <fileset dir="${src}/META-INF" includes="*.json"/>
    <filterchain>
        <expandproperties/>
    </filterchain>
</copy>

Depending on the values of the imported properties, the generated OID suffix mappings descriptor document oid-suffix-mappings.json may be as follows:

{
  "name": "Database Query",
  "vendor": "OpenCloud",
  "version": "2.2.0",

  "resourceAdaptorEntities": [
    {
      "name": "dbquery-0",
      "oidSuffix": "1"
    }
  ]
}

Including OID mappings assigned at compile time

For the static OID mappings that you set with compile-time annotations, include the corresponding deployment descriptor file in the component’s jar file.

The following build script snippet shows how to include the deployment descriptor files. In this script, a wildcard is used to include both the resource-adaptor-jar.xml and the oc-resource-adaptor-jar.xml deployment descriptors in the target jar file.

<target name="build-http-ra" depends="compile, generate">
    <jar jarfile="${artifacts}/http-ra.jar">
        ...
        <metainf dir="${generated}/com/opencloud/slee/resources/http/META-INF" includes="*resource-adaptor-jar.xml"/>
        ...
    </jar>
</target>

Including OID suffix mappings descriptor documents

For resource adaptor entities and profile tables, deploy an OID suffix mappings descriptor document to achieve static OID coverage. Use build scripts to install or uninstall an OID suffix mappings descriptor document for an application.

The following Ant script shows how to install the OID suffix mappings descriptor document for a resource adaptor:

<target name="deploy-http-ra-du" description="Deploy HTTP resource adaptor" depends="login, copy-http-ra-keystore, deploy-rhino-api-compatibility-lib">
    <slee-management>
        ...
        <install srcfile="dus/oid-suffix-mappings.json" url="file:lib/oid-suffix-mappings.json" type="oid-suffix-mappings"/>
        ...
    </slee-management>
</target>

Uninstall the OID suffix mappings descriptor document when the relevant application is removed, as the document might interfere with future deployments.

The following Ant script shows how to uninstall an OID suffix mappings descriptor document:

<target name="undeploy-http-ra-du" description="Undeploy HTTP resource adaptor" depends="undeploy-http-test-service">
    <slee-management>
        ...
        <uninstall url="file:lib/oid-suffix-mappings.json"/>
        ...
    </slee-management>
</target>