|
UMDS User Guide
|
The UMDS Server has a simple web server which provides operational information. This information is important for monitoring the operation and performance of these components. However, while the web-based presentation is convenient for manual, on-demand monitoring, it is not suitable for automated collection and recording of operational information for continuous monitoring and historical analysis.
The Daemon Statistics feature supports the background publishing of their operational information via UM messages. Monitoring systems can now subscribe to this information in much the same way that UM transport statistics can be subscribed.
The operational information is published as messages of different types sent over a normal UM topic source (topic name configurable). Each message is in the form of a binary, C-style data structure.
There are generally two categories of messages: config and stats. A given instance of a category "config" message does not have content which changes over time. An instance of a category "stats" message has content that does change over time. The daemon-specific documentation indicates which messages are in which category.
Each message type is configured for a publishing interval. When the publishing interval for a message type expires, the possible messages are checked to see if its content has materially changed since the last interval. If not, then the message is not republished. The publishing interval for a stat message is typically set to shorter periods to see those changes as they occur.
The messages published are in binary form and map onto the C data structures defined for each message type.
The byte order of the structure fields is defined as the host endian architecture of the publishing daemon. Thus, if a monitoring host receiving the messages has the same endian architecture, the binary structures can be used directly. If the monitoring host has the opposite endian architecture, the receiver must byte-swap the fields.
The message structure is designed to make it possible for a monitoring application to detect a mismatch in endian architecture. Detection and byte swapping is demonstrated with daemon-specific example monitoring applications.
Each message sent by the daemon consists of a standard header followed by a message-type-specific set of fields. The standard header contains a version field which identifies the version of the C include file used to build the daemon.
The UMDS Server is built with the include file umdsdmonmsgs.h. With each daemon statistics message sent by the UMDS Server, it sets the header version field to LBM_UMDSD_DMON_VERSION. With each new release of the UMDS package, if that include file changes in a substantive way, the value of LBM_UMDSD_DMON_VERSION is increased. In this way, a monitoring application can determine if it is receiving messages from a store daemon whose data structures match the monitoring application's structure definitions.
The daemon can optionally be configured to accept command-and-control requests from monitoring applications. There are two categories of these requests: "snapshot" and "config". "Snapshot" requests tell the daemon to immediately republish the desired stats and/or configs without waiting until the next publishing interval. These requests might be sent by a monitoring application which has only just started running and needs a full snapshot of the operational information. "Config" requests tell the daemon to modify an operational parameter of the running daemon.
The monitoring application sends a request to the daemon, and the daemon sends status messages in response. The exchanges are made via standard UM topicless immediate Request Response messaging. Informatica recommends the use of Unicast Immediate Messaging (UIM) for sending the requests using lbm_unicast_immediate_request(). To use UIM effectively, Informatica recommends configuring the daemon monitor context for a specific UIM interface and port using: request_tcp_port (context) and request_tcp_interface (context). This enables the monitoring application to know how to address the request UIMs to the proper daemon.
The request message is formatted as a simple ASCII string. For the SRS service, the request message is formatted as a JSON message. The request is sent as a non-topic unicast immediate request message. The daemon reacts by parsing the request and sending a UM response with a success/failure response. If the request was parsed successfully, the daemon then performs the requested operation (republishing the data or modifying the operational parameter). There are daemon-specific example applications which demonstrate the use of this request feature.
The different message types are:
Each one has a specific structure associated with it, as detailed in the file umdsdmonmsgs.h.
Note that message type ending with "CFG" is in the config category. All others are in the stats category. See Daemon Statistics Structures for information on how the two categories are handled differently.
A monitoring application receiving these messages must detect if there is an endian mismatch (see Daemon Statistics Binary Data). The header structure umdsd_dstat_msg_hdr_t_stct contains a 16-bit field named magic which is set equal to LBM_UMDS_DMON_MAGIC. The receiving application should compare it to LBM_UMDS_DMON_MAGIC and LBM_UMDS_DMON_ANTIMAGIC. Anything else would represent a serious problem.
If the receiving app sees:
magic == LBM_UMDS_DMON_MAGIC
then it can simply access the binary fields directly. However, if it sees:
magic == LBM_UMDS_DMON_ANTIMAGIC
then most (but not all) binary fields need to be byte-swapped. See umdsdmon.c for an example, paying special attention to the macros COND_SWAPxx (which conditionally swaps based on the magic test) and the functions byte_swapXX() (which performs the byte swapping).
UMDS Daemon Statistics data structures sometimes contain string buffers. Strings in these data structures are always null-terminated. These messages are generally sent as fixed-length equal to the sizes of the structures, and therefore include all of the declared bytes of the string fields, even if the contained string uses fewer bytes than declared. For example, the structure umdsd_dstat_connection_summary_record_stct contains the field user_name which is a char array of size UMDS_DSTAT_CFG_EL_NAME_SZ + 1. If user_name is set to "p1", then only 3 bytes of the buffer are used (including the null string terminator). However, all UMDS_DSTAT_CFG_EL_NAME_SZ + 1 bytes will be sent in the UMDS_DSTATTYPE_CONNSUMMARY message type.
There is one exception to this rule: UMDS_DSTATTYPE_CFG.
The UMDS_DSTATTYPE_CFG message is of type umdsd_dstat_config_msg_stct, which contains the structure umdsd_dstat_config_record_stct, which contains the field data. This field is variable length and contains a null-terminated string.
UMDS daemon statistics are configured by the UMDS Element "<daemon-monitor>" in the UMDS Server Configuration File.
The UMDS Daemon supports a monitoring application to send a specific set of requests to control the operation of Daemon Statistics. The remote-snapshot-request and remote-config-changes-request configuration elements control whether the Store enables this request feature (defaults to disabled).
If enabled, the monitoring application can send a command message to the UMDS in the form of a topicless unicast immediate "request" message (see lbm_unicast_immediate_request() with NULL for topic). The format of the message is a simple ascii string, with or without null termination. Due to the simple format of the message, no data structure is defined for it.
When the UMDS receives and validates the command, it sends a UM response message back to the requesting application containing a status message (which is not null-terminated). If the status was OK, the Store also performs the requested action.
The example program umdsdcmd.c demonstrates the correct way to send the messages and receive the responses.
Commands enabled by remote-snapshot-request:
Commands enabled by remote-config-changes-request:
mallinfo 5worksum 5workdet 5
The following files are provided in source code form to assist users in writing monitoring applications using the UMDS Daemon Statistics feature.
umdsdmon.c and umdsdcmd.c on Windows platform).