15 Monitoring Service Controller Using Runtime MBeans

This chapter explains how to monitor Oracle Communications Service Controller.

Introduction to Service Controller Monitoring

You can monitor Service Controller using JMX Runtime MBeans which are simple Java objects that provide an API to:

• Poll values of Service Controller measurements, that is, counters, gauges and status

• Receive notifications when certain events occur

Runtime MBeans is a Java software API-based on the standard Java Management eXtensions (JMX). The API provides a system interface to monitor the activity of each Service Controller module.

Using JMX clients you can monitor any component (that is SSUs, IMs and SMs) in a Service Controller domain.

You access runtime MBeans by connecting your JMX-client to the managed servers process.

Understanding Service Controller Runtime MBeans

This section describes the Service Controller Runtime MBeans.

Service Controller Runtime MBeans Organization

Monitoring a Service Controller module involves polling measurements and statuses from a set of MBeans that together provide the module state. Each Service Controller module has a set of Runtime MBeans, which are organized in a hierarchy that includes:

• A root MBean that lets you monitor the functionality of the module. For example, the IM-SCF root MBean provides measurement on the number of sessions that the IM-SCF handled successfully or sessions that the IM-SCF handled unsuccessfully. The root MBean also provides references to other Runtime MBeans in the hierarchy.

• Other Runtime MBeans, each monitors a component or an interface of the module. For example, the IM-SCF TcapRuntimeMBean provides measurements regarding the TCAP interface.

Figure 15-1 shows an example of the Runtime MBean hierarchy for the IM-SCF CAP phase 1 Interworking Module. The root runtime MBean for M-SCF CAP phase 1 is ImscfCapRuntimeMBean. It contains TcapRuntimeMBean and CapRuntimeMBean.

Figure 15-1 Example of the IM-SCF CAP Runtime MBean Hierarchy

Each Runtime MBean provides reference to other Runtime MBeans under it in the hierarchy. Therefore, a JMX client can access a Runtime MBean by either directly looking it up in the MBean Server or by browsing down through the Runtime MBean hierarchy.

Service Controller Runtime MBean Instantiation

Each module instance instantiates its own Runtime MBeans on the server where the module instance is running. If Service Controller executes a module instance on more than one server, then the module instance will create several instances of its Runtime MBeans, one on each server. The Runtime MBeans on a server let you monitor the activity of the module instance running on that specific server.

Figure 15-2 shows an example of how IM-SCF instantiates Runtime MBeans on each of the servers on which IM-SCF is installed.

Figure 15-2 IM-SCF CAP1 Instances

Module instance Runtime MBeans are registered in the MBean server where the module instance is running. Runtime MBeans remain available in the MBean server as long as the module instance that instantiated them is running. When a module instance stops, its Runtime MBeans also cease to exist.

Service Controller Runtime MBean Object Names

Runtime MBeans are registered in the MBean Server under an object name of type javax.management.ObjectName. Service Controller naming conventions encode its Runtime MBean object names as follows:

com.convergin:Type=MBean-type-name,Version=version,Location=server-name,Name=module-instance-name.resource-name,CountingMethod=counting_method

Table 15-1 describes the key properties that Service Controller encodes in its Runtime MBean object names.

Table 15-1 Service Controller MBean Object Name Key Properties

Property	Description
Type=MBean-type-name	Specifies a short name of an MBean's type without the postfix MBean. For example, the Type parameter of LinksetRuntimeMBean is LinksetRuntime.
Location=server-name	Specifies a name of a Processing Server or Signaling Server on which the Runtime MBean runs.
Version=version_number	Specifies the version of the containing bundle of the MBean instance. The ability to upgrade bundles is a key feature of OSGi containers. When you upgrade an MBean to a later version, this parameter enables Service Controller to keep the same name for different versions of the same MBean and use the version number to differentiate between them.
Name=module-instance-name.resource-id	Specifies the name of a Runtime MBean which consists of the following keys: monitor-instance-name: Name of the module instance that the Runtime MBean monitors resource-name: Resource that the Runtime MBean monitors. Possible values of this key depend on the type of MBean.
CountingMethod=counting_method	Specifies how an MBean counts events. You can set counting_method to one of the following: CurrentInterval, when you want to get the number of times that a specific event occurred from the beginning of the time interval until the moment when you read the counter PreviousInterval, when you want to get the number of times that a specific event occurred by the end of a previous time interval CurrentGeneral, when you want to get the number of currently occurring events For more information on counting methods, see "Counters, Gauges, TPSs and Statuses".

For example:

com.convergin:Type=MessageByOpRuntime,Version=1.0.0,Location=sb_01,
Name=imscfcap4_instance.CAP.InitialDP,CountingMethod=CurrentInterval

Accessing Service Controller Runtime MBeans

Runtime MBeans are located and registered in the MBean Server of Processing Servers and Signaling Servers, where the Service Controller module instances are running.

Remote JMX clients (clients running in a different JVM than the Processing Server or Signaling Server), can use the javax.management.remote APIs to access any Service Controller MBean server. When accessed from a remote client, a Service Controller MBean Server returns its javax.management.MBeanServerConnection interface, which enables clients to access MBeans.

To monitor a module instance running on a Processing Server or a Signaling Server, a JMX client has to:

• Connect to the MBean Server on the server. This is where the Runtime MBeans are registered.

• Look up the Runtime MBeans in the MBean Server.

• Use the Runtime MBean interfaces to query counter and status values, and to receive notifications.

Runtime MBeans Reference

The Service Controller Runtime MBeans are described in details in JavaDoc. For more information, see the Service Controller Configuration and Runtime MBean Java API Reference.

Service Controller Measurements

This section describe various aspects of Service Controller measurements.

Counters, Gauges, TPSs and Statuses

Service Controller Runtime MBeans provide the following types of attributes:

Counters

Counters store the number of times a particular event has occurred during the last time interval. For example, a counter can provide the number of messages received in the last 15 minute interval. The time interval is configured for each module instance depending on your specific needs. Whenever a time interval ends, Service Controller zeroes a counter.

Figure 15-3 shows how a counter increases and zeroes periodically in the end of each time interval.

Figure 15-3 Typical Counter Graph

Names of counter attributes have the count prefix.

Service Controller provides the following types of counters:

• Current interval counters

  This type of counter provides the number of times that a specific event occurred from the beginning of the time interval until the moment you read the counter. You can check how much time elapsed since the beginning of the current time interval using WcsUptimeMBean.

  To make a counter act as a current interval counter, create an instance of an MBean and set the CountingMethod property of the MBean object name to CurrentInterval.

• Previous interval counters

  This type of counters provides the number of times that a specific event occurred by the end of a previous time interval.

  To make a counter act as a previous interval counter, create an instance of an MBean and set the CountingMethod property of the MBean object name to PreviousInterval.

Figure 15-4 shows an example of a current interval counter compared to a previous interval counter.

Figure 15-4 Current Interval Counter

Note:

You need to access different instances of an MBean for each type of counter. The two MBean instances differ by the CountingMethod property of their object name. The value of the CountingMethod of one instance is CurrentInterval and of the second instance is PreviousInterval.

TPSs

TPSs are special counters whose time interval is non-configurable and preset to a very short duration of 15 seconds. There are only a few TPS counters. All of them have been identified as the most important Service Controller counters, which are critical to monitor Service Controller performance.

Names of TPS attributes have the count prefix. However, as opposed to regular counter attributes, TPS counters are available in MBean instances whose CountingMethod property is set to ShortInterval.

Gauges

Gauges store a number measured at a given moment. For example, the number of currently active sessions.

Figure 15-5 shows how a gauge value changes over time.

Figure 15-5 Typical Gauge Graph

Names of gauge attributes have the gauge prefix. Gauge attributes are available in MBean instances whose CountingMethod property equals CurrentGeneral.

Statuses

Statuses are attributes that indicate a state of a resource. For example, a status can provide information about a current state of an SS7 point code.

Module-Level Measurements and Tier-Level Measurements

Runtime MBeans can provide measurements described in "Service Controller Measurements" on the following levels:

• Module

  When a Service Controller module loads, Service Controller creates runtime MBeans for this module. Counters and gauges of runtime MBeans provide information about the module for which the MBeans were created. For example, when IM-SCF CAP1 loads, Service Controller creates runtime MBeans for monitoring the TCAP and CAP interfaces of the module. These MBeans contains counters and gauges that gather information about sessions and operations handled by IM-SCF CAP1.

• Tier

  To provide measurements on how an entire tier functions, Service Controller provides the runtime MBean that contains counters and gauges for gathering information related to the tier rather than to individual modules. For example, SystemCountersRuntimeMBean provides a counter that indicates the number of sessions opened in the last period in the Processing Tier.

  Table 15-2 describes attributes that enable you to monitor the Service Controller Processing Tier.

  Table 15-2 Processing Titer Monitoring Attributes

  Attribute	Description	Type	MBean
  InitialRequestCount	Specifies the number of sessions opened in the Processing Server in the last measurement period	Counter	SystemCountersRuntimeMBean
  SessionGauge	Specifies the number of currently opened sessions in the Processing Server	Gauge	SystemGaugeRuntime MBean

  
  

Understanding Notifications

Service Controller notifications are based on Service Controller counters, gauges, TPSs and status attributes as described in "Service Controller Measurements". You can specify criteria for each Runtime MBean attribute (that is counter, gauge, TPS or status) that cause Service Controller to invoke a notification when each criteria is met.

In general, the notification mechanism involves the following steps:

1. An attribute value changes and reaches a criteria that was specified.

2. The Runtime MBean invokes a notification.

3. The attribute value changes again and the criteria is not met any longer.

4. The Runtime MBean clears the previously sent notification by invoking a cease notification.

Notifications are triggered by the Runtime MBean whose attribute is being monitored.

"Specifying Notification Criteria for Counters and TPSs" and "Specifying Notification Criteria for Gauges" explain how thresholds define reporting and clearance of a notification for counters and gauges.

Specifying Notification Criteria for Counters and TPSs

Counters store the number of times a particular event has occurred in the last time interval. For example, a counter can measure the number of InitialDP operations received in the last 15 minutes. See "Counters".

Table 15-3 explains how reaching an upper threshold or a lower threshold causes reporting and clearing of a notification.

Table 15-3 Reporting and Clearing Notifications for Counters

Threshold	Notification Sent When...	Notification Cleared When...
Upper	The counter crosses the upper threshold	The counter does not reach the upper threshold by the end of the last time interval
Lower	The counter does not cross the lower threshold by the end of the last time interval	The counter crosses up the lower threshold by the end of the last time interval

Specifying Notification Criteria for Gauges

Gauges are MBean attributes that provide a measurement at a given moment. For example, a gauge can contain a number of currently active sessions. See "Gauges".

Table 15-4 explains how reaching an upper threshold or a lower threshold causes reporting and clearing of a notification.

Table 15-4 Reporting and Clearing Notifications for Gauges

Threshold	Notification Sent When...	Notification Cleared When...
Upper	The increasing gauge crosses the upper threshold	The decreasing gauge crosses the threshold ceased value
Lower	The decreasing gauge crosses the lower threshold	The increasing gauge crosses the threshold ceased value

Specifying Notification Criteria for Statuses

Statuses are MBean attributes that indicate a state of a module. Service Controller triggers a notification when the value of an attribute changes to a certain value.

For example, SsuRemotePointCodeRuntimeMBean has the Status attribute that indicates availability of a point code. To monitor this attribute, you can define that Service Controller triggers a notification when the value of the Status attribute changes and indicates that the remote point becomes unavailable.

Table 15-5 explains how entering a specified state and exiting a state causes reporting and clearing of a notification.

Table 15-5 Reporting and Clearing Notifications for Statuses

Notification Sent When...	Notification Cleared When...
A monitored attribute changes to a specified state	A monitored attribute changes again to a state other than a specified state

Notification Structure

The Service Controller notification mechanism is based on javax.management.Notification and javax.management.AttributeChangeNotification Java classes.

These Java classes contain the following fields:

• Source

  The ObjectName of a Runtime MBean that sent the notification

• Sequence number

  This number allows individual notifications to be identified by a receiver

• Message

  Provides detailed textual description of a notification

• Type

  The type conveys the semantics of the notification in the following format: rmb.attr.class, where:

  • rmb defines a type of the runtime MBean that triggers a notification

  • attr defines an attribute of a runtime MBean whose change triggers the notification

  • cause defines a type of the change that triggers the notification. Table 15-6 describes notification causes that can be defined in the Type field.

    Table 15-6 Notification Cause Values for Counters and Gauges

    Cause	Description
    highThresholdCrossed	A runtime MBean counter or gauge crosses a higher threshold.
    clearedHighThreshold	The highThresholdCrossed notification was cleared.
    lowThresholdCrossed	A runtime MBean counter or gauge crosses a lower threshold.
    clearedLowThreshold	The lowThresholdCrossed notification was cleared.

    
    

    Table 15-7 Notification Cause Values for State Change Indicators

    Cause	Description
    StateEntered	A runtime MBean attribute changed to a value.
    StateCeased	A runtime MBean attribute is no longer equal to the value.

    
    

• Time

  Specifies the time when the event, which triggered the notification, occurred

• UserData

  Specifies additional data that the runtime MBean that triggers the notification wants to communicate.

  The UserData field can contain any data that a runtime MBean, which sends a notification, wants to communicate to a receiver. This field contains tag-value pairs separated by the semicolon.

  The following tags are allowed:

  • OriginNotificationSeqNum, which is used by a clearing notification to enable matching with the original notification that was cleared. In the clearing notification, this tag is set to the sequence number of the cleared notification. For more information, see "Receiving Notification Clearing".

  • LowThreshold, which is set to the crossed value of the lower threshold when the notification class set to low is triggered

  • HighThreshold, which is set to the crossed value of the upper threshold when the notification class is set to high is triggered

  • Match, which is set to the matched value when the notification class set to match is triggered

  • Differs, which is set to the value with which an attribute value was compared when the notification class set to differs is triggered

Receiving Notification Clearing

A runtime MBean clears a notification when criteria described in "Specifying Notification Criteria for Counters and TPSs" and "Specifying Notification Criteria for Gauges" are met.

To enable a notification receiver to recognize which original notification needs to be cleared, a runtime MBean uses the following methods:

• The OriginNotificationSeqNum tag in the UserData field of a clearing notification contains the sequence number of the original notification to be cleared.

• The Source field of the clearing notification contains the same value as the Source field of the original notification to be cleared.

• Clearing notifications contain the "ceased" postfix in the Type field. For example: Type=ImscfCapRuntimeMBean.SessionGauge.ceased.

Registering for Notifications

You can register for notifications using any JMX client. To receive notifications from several MBeans, you need to register for each MBean separately.

The following explains how to register for notifications using JConsole:

1. Start JConsole.

2. Click the MBeans tab.

   The MBeans tree view is displayed.

3. In the tree view pane, select the MBean for which you want to register.

4. Under the selected MBean, select Notifications.

   The Notification Buffer is displayed in the main pane.

5. Click Subscribe.

The registration created. When an event occurs, the notification is displayed in the Notification Buffer. You can clear the Notification Buffer at any time by clicking Clear.

Identifying Key Performance Indicators

Key performance indicators are measurements (counters, gauges, TPSs and statuses) that you monitor in order to assess the state and performance of your system. Depending on your system and the modules installed in your system, you must identify the measurements that best serve the evaluation of your system. For more information about the measurements, see the discussion on monitoring Service Controller in the implementation guides.

Use the Administration Console to configure the Monitoring tab of each module instance in your system. Define notifications that Service Controller will invoke, based on key performance indicators that you selected.

Set your NMS to monitor key performance indicators by either periodically polling the values of these measurements or register to notifications that you specified.

Configuring Service Controller Monitoring

You can configure monitoring separately for the following components: entire Processing Tier, each of the Processing Tier components, and Signaling Server Units (SSUs):

• Processing Tier:

  • Entire Processing Tier

  • Orchestration Engine (OE)

  • Interworking Modules

  • Supplementary Modules

• Signaling Tier:

  • SS7 SSU for SIGTRAN

Monitoring parameters that you can configure for each of these components are common for all the components. However, you can set up each of these parameters differently for different components depending on your specific requirements.

For example, you can define different triggers for generating notifications for IM-SCF and IM-SSF.

Warning:

Thresholds that you define for notifications serve also as thresholds for key overload indicators. If you select a measurement (Runtime MBean and attribute) as a trigger for both notification and overload protection, the threshold value that you specify in the Monitoring tab is also regarded in the context of overload protection.

Accessing the Monitoring Configuration Screen

To access the Monitoring configuration pane:

1. Do one of the following according to the component you want to configure for monitoring:

   • Processing Tier: In the domain navigation pane, expand OCSB, expand Processing Tier, expand Tier Management and then select Monitoring And Overload Protection.

   • Orchestration Engine: In the domain navigation pane, expand OCSB, expand Processing Tier, and then select Orchestration Engine.

   • Interworking Module: In the domain navigation pane, expand OCSB, expand Processing Tier, expand Interworking Modules and then select the module you want to configure for monitoring.

   • Supplementary Module: In the domain navigation pane, expand OCSB, expand Processing Tier, expand Supplementary Modules and then select the module you want to configure for monitoring.

   • SS7 SSUs: In the domain navigation pane, expand OCSB, expand Signaling Tier and then select the SSU you want to configure for monitoring.

2. Click the Monitoring tab.

   Table 15-8 describes the subtabs in the Monitoring configuration pane.

Table 15-8 Monitoring Subtabs

Subtab	Description
General	Enables you to specify parameters that determine the general behavior of the notification mechanism. See "General" for more information.
State Changed Notifications	Enables you to configure generation of notifications when a value of an attribute of a specified Runtime MBean changes. See "State Changed Notifications" for more information.
Threshold Crossed Notifications	Enables you to configure generation of notifications when a threshold is passed. See "Threshold Crossed Notifications" for more information.

General

The General subtab enables you to specify parameters that determine a general behavior of the Runtime MBeans.

Table 15-9 describes configuration parameters in the General subtab.

Table 15-9 General Monitoring Parameters

Name	Type	Description
Enable Runtime MBeans	BOOL	Specifies whether JMX Runtime MBeans are enabled. Possible values: TRUE FALSE Default value: TRUE
Enable Notifications	BOOL	Specifies whether JMX notifications are enabled. Possible values: TRUE FALSE Default value: FALSE
Notification Sample Interval (sec)	INT	Specifies the interval between consecutive sampling of counters. Counters are sampled every few seconds to check whether to invoke notifications. Default value: 30

State Changed Notifications

The State Changed Notifications subtab enables you to configure a notification that Service Controller generates when an attribute of a specified Runtime MBean changes to a specified value.

The State Changed Notifications subtab contains a table in which each row represents an individual notification trigger condition based on an attribute of a specific Runtime MBean.

Table 15-10 describes configuration parameters in the State Changed Notifications tab.

Table 15-10 State Changed Notifications

Field	Type	Description
Name	STRING	Specifies a notification name
Enabled	BOOL	Specifies whether the notification is enabled. Possible values: TRUE FALSE Default value: TRUE
MBean Type	STRING	Specifies a type of the Runtime MBean to be monitored
MBean Attribute	STRING	Specifies an attribute of the MBean defined in the MBean Type field to be monitored. Notice that in this parameter, you can specify only status attributes. Status attributes indicate a state of a resource.
Value	STRING	Specifies an attribute value that triggers generation of the notification
Server Filter	STRING	Specifies a filter that must be applied on the "server" key property on an MBean's instance name. If this parameter is defined, only the MBean instances with the registration name that matches the filter trigger the notification. The value of this parameter must be defined in the form of a regular expression. Default value: \S* (no filter)
Resource Filter	STRING	Specifies a filter that must be applied on the "name" key property of an MBean's instance name. If this parameter is defined, only the MBean instances with the registration name that matches the filter trigger the notification. The value of this parameter must be defined in the form of a regular expression. For example, to monitor MessageByOperationRuntimeMbean's counters of a specific operation, set ResourceFilter to "\S*InitialDP\S*". Default value: \S* (no filter)
Message	STRING	Specifies a message to be set in the "message" field of the notification. Default value: "notification"

Threshold Crossed Notifications

The Threshold Crossed Notifications subtab enables you to configure generation of notifications when a threshold is passed. The Threshold Crossed Notifications subtab contains a table in which each row represents an individual notification triggering condition based on an attribute of a specific Runtime MBean.

Table 15-11 describes configuration parameters in the Threshold Notifications tab.

Table 15-11 Threshold Crossed Notifications Fields

Field	Type	Description
Name	STRING	Specifies a unique notification name
Enabled	BOOL	Specifies whether the notification is enabled. Possible values: TRUE FALSE Default value: TRUE
MBean Type	STRING	Specifies a type of the Runtime MBean to be monitored
MBean Counting Method	STRING	Specifies the counting method. Possible values: CurrentIntervalDeltaValue PreviousIntervalDeltaValue CurrentGeneralValue PreviousShortIntervalDeltaValue Select CurrentIntervalDeltaValue.
MBean Attribute	STRING	Specifies an attribute of the MBean defined in the MBean Type field to be monitored
Class	STRING	Specifies a notification class. Possible values: High A notification is triggered when a Runtime MBean counter or gauge crosses an upper threshold. Low A notification is triggered when a Runtime MBean counter or gauge crosses an lower threshold. Default value: High
Threshold Value	INT	Specifies a high threshold, when the Class field is set to High, or low threshold, when the Class field is set to Low.
Threshold Ceased Value	INT	Specifies a threshold for which the "ceased" notification must be triggered
Server Filter	STRING	Specifies a filter that must be applied on the "server" key property on an MBean's instance name. If this parameter is defined, only the MBean instances with the registration name that matches the filter trigger the notification. The value of this parameter must be defined in the form of a regular expression. Default value: \S* (no filter)
Resource Filter	STRING	Specifies a filter that must be applied on the "name" key property of an MBean's instance name. If this parameter is defined, only the MBean instances with the registration name that matches the filter trigger the notification. The value of this parameter must be defined in the form of a regular expression. For example, to monitor MessageByOperationRuntimeMbean's counters of a specific operation, set ResourceFilter to "\S*InitialDP\S*". Default value: \S* (no filter)
Threshold Crossed Message	STRING	Specifies a text for the notification message that Service Controller generates when a threshold is crossed.
Threshold Ceased Message	STRING	Specifies a text for the notification message that Service Controller generates when a notification is ceased.