The "lbmmon" library is used in two ways:

Source: Applications and UM daemons use lbmmon to publish UM statistics.
Receiver: A monitoring collector uses lbmmon to receive and parse UM statistics.

The lbmmon source APIs are usually not called directly by user applications. Instead, most users configure Automatic Monitoring, which implicitly uses lbmmon's source APIs. The lbmmon receiver APIs are called by the UM Monitoring Collector Service (MCS) or by a User-Developed Collector.

Informatica recommends the use of automatic monitoring and the MCS. This relieves the user from writing to the lbmmon API.

"lbmmon" API <-

An application requesting transport monitoring is called a monitor source, and an application accepting statistics is a monitor receiver. These monitoring objects deal only with transport session statistics and should not be confused with UM sources and UM receivers, which deal with UM messages. Statistics for both UM sources and UM receivers can be forwarded by a monitor source application.

Both a monitor source and monitor receiver consist of a monitoring context and control thread and two selectable modules:

A format module, responsible for serializing and de-serializing the statistics. The proper transmission between monitor source and monitor receiver requires this serialization.
A transport module that is responsible for sending and receiving statistics data.

You can substitute format and transport modules of your own choosing or creation. UM Monitoring provides the following sample modules:

LBMMON CSV format module.
LBMMON PB format module for protocol buffers.
LBMMON LBM transport module.
LBMMON SNMP transport module. (but see deprecation).
LBMMON UDP transport module (but see deprecation).

To view the source code for all LBMMON transport modules, see LBMMON Example source code.

Monitoring Process Flow <-

The overall process flow appears in the diagram below.

Your application creates the monitor source controller, specifying the format and transport modules to use. It also calls lbmmon functions to start monitoring an UM context, UM source or UM receiver.
The monitor source controller passes those statistics to the format module serialization function.
The monitor source controller passes the resulting serialized data to the transport module send function.
The transport module transmits the data over some transport medium (such as a network).
The monitor receiver controller transport module receives the serialized data. (Your monitoring application has already created the monitor receiver controller specifying the format and transport modules to use, along with the application callback functions to use upon the receipt of UM source or UM receiver statistics data.)
The monitor receiver controller calls the format module's de-serialization function.
Finally, the monitor receiver controller passes the statistics to your monitoring application via the specified application callback functions.

Your applications only calls functions in the controller modules, which calls the appropriate functions in the transport and format modules.

API Framework Flexibility <-

The segregation of UM Monitoring into control, format, and transport modules provides flexibility for monitor receivers in two ways.

Allows you to use languages for which no UM API or binding exists.
Allows you to use monitoring products which do not integrate with UM.

As an example, assume you have a Perl application which currently gathers statistics from other network applications (or, you are simply most comfortable working in Perl for such tasks). There is no Perl binding for UM. However, Perl can handle UDP packets very nicely, and can pick apart CSV data easily. By implementing a UDP transport module to be used by the monitor sources, your Perl application can read the UDP packets and process the statistics.

To use the UDP transport module, the lbmmon APIs must be used. The automatic monitoring feature cannot be configured to use the UDP transport module. However, note that the UDP transport module is deprecated.

The following sections present more discussion and sample source code about starting monitor sources, monitor receivers and the LBMMON format and transport modules.

Creating a Monitoring Source <-

Informatica recommends using Automatic Monitoring instead of creating your own monitoring source.

The following examples demonstrate how to use the UM Monitoring API to enable monitoring in your application.

First, create a monitoring source controller:

lbm_context_t * ctx;
lbm_src_t * src;
lbm_rcv_t * rcv;
lbmmon_sctl_t * monctl;
if (lbmmon_sctl_create(&monctl, lbmmon_format_csv_module(), NULL, lbmmon_transport_lbm_module(), NULL) == -1)
{
  fprintf(stderr, "lbmmon_sctl_create() failed\n");
  exit(1);
}

The above code tacitly assumes that the ctx, src, and rcv variables have been previously assigned via the appropriate UM API calls.

The monitoring source controller object must be passed to subsequent calls to reference a specific source controller. One implication of this is that it is possible to have multiple monitoring source controllers within a single application, each perhaps monitoring a different set of objects.

In the above example, the default CSV format module and default UM transport module are specified via the provided module functions lbmmon_format_csv_module() and lbmmon_transport_lbm_module().

Specifying the Object to Monitor <-

Once a monitoring source controller is created, the application can monitor a specific context using:

if (lbmmon_context_monitor(monctl, ctx, NULL, 10) == -1)
{
  fprintf(stderr, "lbmmon_context_monitor() failed\n");
  exit(1);
}

The above example indicates that statistics for all transports on the specified context will be gathered and sent every 10 seconds.

A UM source can be monitored using:

if (lbmmon_src_monitor(monctl, src, NULL, 10) == -1)
{
  fprintf(stderr, "lbmmon_src_monitor() failed\n");
  exit(1);
}

Finally, an UM receiver can be monitored using:

if (lbmmon_rcv_monitor(monctl, rcv, NULL, 10) == -1)
{
  fprintf(stderr, "lbmmon_rcv_monitor() failed\n");
  exit(1);
}

The two above examples also request that statistics for all transports on the specified source or receiver be gathered and sent every 10 seconds.

Statistics can also be gathered and sent in an on-demand manner. Passing 0 for the Seconds parameter to lbmmon_context_monitor(), lbmmon_src_monitor(), or lbmmon_rcv_monitor() prevents the automatic gathering and sending of statistics. To trigger the gather/send process, use:

lbmmon_sctl_sample(monctl);

Such a call will perform a single gather/send action on all monitored objects (contexts, sources, and receivers) which were registered as on-demand.

As part of application cleanup, the created monitoring objects should be destroyed. Each individual object can be de-registered using lbmmon_context_unmonitor(), lbmmon_src_unmonitor(), or lbmmon_rcv_unmonitor(). Finally, the monitoring source controller can be destroyed using:

lbmmon_sctl_destroy(monctl);

Any objects which are still registered will be automatically de-registered by lbmmon_sctl_destroy().

Receiving Monitoring Data <-

Informatica recommends using the Monitoring Collector Service (MCS) instead of writing your own collector.

To make use of the statistics, an monitoring collector application must be running that receives the monitor data. This application creates a monitoring receive controller, and specifies callback functions which are called upon the receipt of source or receiver statistics data.

See Example lbmmon.c for C code implementing a monitoring receive controller. Or see Example lbmmon.java for equivalent Java code.

Monitoring Transport Modules <-

The lbmmon library comes with three pre-written transport modules:

The LBM Transport Module - recommended for applications and daemons at UM version 6.14 and beyond.
The UDP Transport Module - legacy.
The SNMP Transport Module - legacy.

For an application or UM daemon to publish its UM statistics, you can choose the desired transport module, typically by configuration (monitor_transport (context) and monitor_transport (event_queue)).

Each transport module can have options that control its behavior. Those options are supplied via an option string. The exact format of the option string can vary according to the format module being used. The format options string is typically supplied by configuration (monitor_transport_opts (context) and monitor_transport_opts (event_queue)).

The LBM Transport Module <-

The LBM transport module publishes statistics using a UM source.

The transport options string is in the form of name/value pairs separated by semicolons. The following name/value pairs are available:

config=file_name specifies a configuration file. This file is processed in a manner similar to lbm_config(). However, unlike lbm_config(), the current default attributes are not changed. Instead, the options parsed from the configuration file are applied only to the UM objects created by the module.
topic=topic_name specifies the topic name to use for sending and receiving statistics. By default, the topic /29west/statistics is used.
wctopic=topic_pattern specifies (for monitor receivers only) a wildcard pattern to be used to receive statistics.
context|option_name=option_value specifies UM a configuration option for the monitoring context.
source|option_name=option_value specifies UM a configuration option for the source used to publish monitoring data.
receiver|option_name=option_value specifies UM a configuration option for the receiver used to subscribe to monitoring data.
wildcard_receiver|option_name=option_value specifies UM a configuration option for the wildcard receiver used to subscribe to monitoring data.

As an example, assume your application needs to use a special configuration file for statistics. The following call allows your application to customize the UM transport module using the configuration file stats.cfg.

lbmmon_sctl_t * monctl;
const char * tropt = "config=stats.cfg";
if (lbmmon_sctl_create(&monctl, lbmmon_format_csv_module(), NULL, lbmmon_transport_lbm_module(), tropt) == -1)
{
  fprintf(stderr, "lbmmon_sctl_create() failed\n");
  exit(1);
}

If your application also needs to use a specific topic for statistics, the following code specifies that, in addition to the configuration file, the topic StatisticsTopic be used for statistics.

lbmmon_sctl_t * monctl;
const char * tropt = "config=stats.cfg;topic=StatisticsTopic";
if (lbmmon_sctl_create(&monctl, lbmmon_format_csv_module(), NULL, lbmmon_transport_lbm_module(),
tropt) == -1)
{
  fprintf(stderr, "lbmmon_sctl_create() failed\n");
  exit(1);
}

It is important to use the same topic and configuration for both monitor sources and receivers. Otherwise your applications may send the statistics, but the monitor receiver won't be able to receive them.

To view the source code for the LBM transport module, see Source code for lbmmontrlbm.c.

The UDP Transport Module <-

Starting in UM 6.14, monitoring transports UDP and SNMP are deprecated in favor of LBM. We do not plan to remove existing UDP or SNMP functionality, and will continue to support them in their current states. But we do not plan to enhance UDP or SNMP in the future.

In particular, UDP datagrams are limited in size to 64K bytes, but when a Store daemon is enabled for protocol buffer format, message sizes can exceed that limit. This is not a risk for CSV format.

The UDP transport module publishes statistics using a simple UDP datagram. It can send or receive UDP unicast, UDP broadcast, and UDP multicast.

Note: To use the UDP transport module, the lbmmon APIs must be used. The automatic monitoring feature cannot be configured to use the UDP transport module.

The transport options string is in the form of name/value pairs separated by semicolons. The following name/value pairs are available:

address=dest_ip specifies the unicast IP address to which statistics are sent via UDP. Applicable to sender only.
port=port_num is the IP port packets are sent to. Defaults to 2933.
interface=interface_spec specifies the network interface over which multicast UDP is sent or received. See Specifying Interfaces for formats.
mcgroup=ip is the multicast group on which to send and receive UDP packets.
bcaddress=ip specifies the broadcast address to which UDP packets are sent. Applicable to sender only.
ttl=val specifies the TTL for each multicast UDP packet. Applicable to sender only.

To view the source code for the UDP transport module, see Source code for lbmmontrudp.c.

The SNMP Transport Module <-

Starting in UM 6.14, monitoring transports UDP and SNMP are deprecated in favor of LBM. We do not plan to remove existing UDP or SNMP functionality, and will continue to support them in their current states. But we do not plan to enhance UDP or SNMP in the future.

To take advantage of new monitoring capabilities, Informatica requests that users migrate to the LBM transport.

The SNMP transport module publishes statistics using a UM source, much like The LBM Transport Module. However, for user convenience, some configuration options are hard-coded to be compatible with the UM SNMP agent component.

To view the source code for the SNMP transport module, see Source code for lbmmontrlbmsnmp.c.

Monitoring Format Modules <-

The lbmmon library comes with two pre-written format modules:

The PB Format Module - recommended for applications and daemons at UM version 6.14 and beyond.
The CSV Format Module - legacy.

For an application or UM daemon to publish its UM statistics, you can choose the desired format module. For UM versions prior to 6.14, only CSV was available. For UM 6.14 and beyond, you can choose CSV or PB, typically by configuration (monitor_format (context) and monitor_format (event_queue)).

A statistics collector subscribes to UM statistics. For UM versions prior to 6.14, only CSV was available. For UM 6.14 and beyond, both are available for use, depending on the format of statistics messages received.

Pre-6.14 collectors (with no knowledge of PB) will work the same as they always have when run with 6.14 and beyond. But they will not process UM statistics arriving in PB format. Informatica recommends updating collector applications to support both formats.

Each format module can have options that control its behavior. Those options are supplied via an option string. The exact format of the option string can vary according to the format module being used. In UM versions 6.14 and beyond, the format options string is typically supplied by configuration (monitor_format_opts (context) and monitor_format_opts (event_queue)).

The PB Format Module <-

The PB format module formats UM statistics as Google Protocol Buffers.

The format options string is in the form of name/value pairs separated by semicolons. The following name/value pairs are available:

passthrough=mode - used by monitoring receiver.

Where "mode" can be one of three values:

off - The receive controller will deserialize the message for you and deliver via the LBM statistics C structures or Java classes. This is the default.
on - the receive controller will pass the received message directly to the callback without any deserializing of either PB or CSV messages. The application must be able to handle either raw CSV messages or protocol buffers.
convert - No deserialization. Protocol buffer messages are passed directly to the application. CSV messages are converted into protocol buffers, which passed directly to the application.

The advantage of "convert" is that the collector can accept both older CSV and newer protocol buffer statistics, but your code can be written to only understand protocol buffers.

For monitoring receivers (collectors), Informatica recommends the PB format module with the "passthrough=convert" format option. This allows the receive controller to correctly process both PB and CSV statistics.

To view the source code for the PB format module, see Source code for lbmmonfmtpb.c.

The CSV Format Module <-

Starting in UM 6.14, CSV is deprecated in favor of The PB Format Module. We do not plan to remove existing CSV functionality, and we will continue to support it in its current state. But we do not plan to enhance CSV in the future.

The CSV format module formats UM statistics as simple comma-separated values.

The format options string is in the form of name/value pairs separated by semicolons. The following name/value pairs are available:

separator=character
specifies a single character to be used as field separator. Defaults to comma.
passthrough=mode - used by monitoring receiver.
where "mode" is "off", "on", or "convert". Defaults to "off".

To view the source code for the CSV format module, see Source code for lbmmonfmtcsv.c.