Notification Service Monitor

Description

The notification service monitor adds monitoring capabilities to the TAO Notification Service so that potential problems can be detected in time to take remedial action.

The monitoring and control capability is enabled and configured via a service configuration directive. The impact on normal operation of the Notification Service should be minimized whether or not Monitoring and Control is configured.

Using the Notification Service Monitor

Configuration

The monitor is enabled via the Service Configurator. These instructions assume that ACE and TAO are built as dynamic libraries. If you are using static libraries, read these instructions first, then refer to the special procedures for static libraries section below. The following Service Configurator commands will enable the monitor:

  dynamic TAO_MonitorAndControl Service_Object * TAO_CosNotification_MC:_make_TAO_MonitorAndControl () ""
  dynamic TAO_MC_Notify_Service Service_Object * TAO_CosNotification_MC_Ext:_make_TAO_MC_Notify_Service () ""

When the notification service is initialized, the monitor will start up in it's own thread (using it's own ORB) and work in conjunction with the notification service to provide statistics through an IDL interface.

The TAO_MonitorAndControl object accepts the following options:

Option	Description
-NoNameSvc	Instructs the monitor not to register itself with the Name Service. Otherwise, it will be registered as TAO_MonitorAndControl.
-ORBArg <parameter>	Passes <parameter> to the monitor's ORB upon initialization. There is no limit to the number of times this argument can be provided.
-o <file>	Write the IOR of the monitor out to <file>.

Obtaining a reference to the Monitor

The object reference to the Notification Service Monitor can be obtained one of following ways (depending upon the options passed upon configuration of the monitor):

CORBA::Object_var obj = orb->string_to_object ("corbaloc:iiop:<host>:<port>/TAO_MonitorAndControl");
CORBA::Object_var obj = orb->string_to_object ("corbaname:iiop:<nshost>:<nsport>#TAO_MonitorAndControl");
CORBA::Object_var obj = orb->string_to_object ("file://<path to IOR file>");

Retrieving statistics from the Monitor

The IDL interface provides a set of methods to obtain statistic names as well as to obtain the statistics themselves.

Numeric data is stored in a structure with the following definition:

  struct Numeric
  {
    /// The number of samples currently taken into account
    unsigned long count;

    /// The average of the accumulated samples.
    double average;

    /// The sum of the squares of the samples.
    double sum_of_squares;

    /// The minimum sample value recorded
    double minimum;

    /// The maximum sample value recorded
    double maximum;

    /// The last sample value recored
    double last;
  };

Text lists are stored in a sequence of strings known as NameList.

These types may be returned as part of a Union depending on the method. The Data union has the following definition:

  enum DataType { DATA_NUMERIC, DATA_TEXT };
  union Data switch (DataType) {
    case DATA_NUMERIC: Numeric num;
    case DATA_TEXT: NameList list;
  };

The get_statistic_names() method returns a NameList which contains the names that are currently known by the statistic monitor. This list will change over time.

The get_statistic(in string name) returns a Data union which contains either a Numeric object or a NameList, depending upon the type of statistic associated with the provided name. If the name does not correspond to a known statistic, the InvalidName exception will be thrown.

The get_statistics(in NameList names) returns a DataList, which is a sequence of Data. The order of the DataList is the same order as provided within the NameList. If any one name provided within the list does not correspond to a known statistic, the InvalidName exception will be thrown.

The clear_statistics(in NameList names) method clears all accumulated statistic data for the provided names. If any one name provided within the list does not correspond to a known statistic, the InvalidName exception will be thrown.

The get_and_clear_statistics(in NameList names) method is a combination of get_statistics() and clear_statistics().

Affecting the Notification Service with the Monitor

The shutdown_event_channel(in string name). If the name does not correspond to an event channel, the InvalidName exception will be thrown.

Special Procedures for Static Libraries

If ACE and TAO are built as static libraries, follow the instructions above with these modifications:

On the mwc.pl command used to generate the build files, add the -features -features "notify_monitor_control=1" option. For example to build for VC9, the mwc command would look like:
- ```
mwc.pl -type vc9 -static -features "notify_monitor_control=1" TAO_ACE.mwc
```

Replace the "dynamic" service configuration commands with a "static" commands. Note that these commands have different syntaxes.
For example if the service configuration commands for a dynamic build are (Lines wrapped for illustrative purposes. In the service conf file the following should appear on two lines):

  dynamic TAO_MonitorAndControl Service_Object *
    TAO_CosNotification_MC:_make_TAO_MonitorAndControl ()
    "-o monitor.ior
    -ORBArg \"-ORBInitRef -ORBArg NameService=corbaloc:iiop:localhost:10637/NameService\""

  dynamic TAO_MC_Notify_Service Service_Object *
    TAO_CosNotification_MC_Ext:_make_TAO_MC_Notify_Service ()
    "-DispatchingThreads 1"

you should replace them with

  static TAO_MonitorAndControl
    "-o monitor.ior
    -ORBArg -ORBInitRef
      -ORBArg NameService=corbaloc:iiop:localhost:10637/NameService"

  static TAO_MC_Notify_Service "-DispatchingThreads 1"

Please note that the parser for the static service configuration directives does not honor escaped quotes, so the -ORBArg option must appear separately for each argument to the Notification Service MC's ORB.