Ultra Messaging

Overview Copied

The Ultra Messaging (UM) integration enables Geneos to monitor status and performance data coming from applications based on the Ultra Messaging high-performance message streaming (UMS) application.

When set up, the integration and its associated API plug-in comprise the Ultra Messaging plug-in (UMPI). The UMPI supports the following:

• Monitoring of the UMS application.
• Monitoring of dynamic routers or gateways generated by the UM Router Daemon (called the tnwgd).

Intended audience Copied

This guide is directed towards experienced Geneos users who want to set up an integration between Geneos and UMS applications. This is also intended for users who will be using Active Console to monitor data from the Ultra Messaging environment.

The Ultra Messaging Monitoring integration requires a Linux machine. As a user, you should be familiar with general system administration on this platform.

Prerequisites Copied

The following requirements must be met before the installation and setup of the template:

• A Linux machine where the UMPI and the tnwgdcan run.
• The machine where the UMPI runs must be able to communicate with UMS applications using UMS protocols.
• The UMPI must be able to communicate with the tnwgd using HTTP.
• This requires an additional licence to use. Please contact your ITRS Account Manager for more information.

Integration steps Copied

The Ultra Messaging Monitoring integration involves the following tasks:

1. Download the integration files.
2. Set up the API sampler.
3. Associate the API plug-in with a managed entity.
4. Set up the UMPI start-up script.
5. Run the UMPI start-up script.

Download the integration files Copied

1. On the ITRS Downloads page, download the Ultra Messaging integration files (geneos-umpi-2.2.4.tar.gz).
2. Save the files on the Linux machine where you want to run the Ultra Messaging Monitoring integration.

The integration files include the following sub-folders:

• examples — contains the configuration templates and start-up script you need to set up the integration.
• UMS_X.X — contains the source files that run the Ultra Messaging integration.

Set up the API sampler Copied

1. In the Gateway Setup Editor, create a new sampler by right-clicking the Samplers folder.
2. Enter a name for this sampler. For example, enter the name UMS in the Name field.
3. Under the Plugin field, click the drop-down list and select api.
4. Click Save current document to apply your changes.

Associate the API plug-in with a managed entity Copied

1. In the Gateway Setup Editor, create a new managed entity by right-clicking the Managed entities folder.
2. Enter a name for this managed entity. For example, enter the name UM in the Name field.
3. In the Options field, select the probe on which you want the sampler to run.
4. Under the Sampler field, click Add new .
5. In the text field under Ref, type the name of the API sampler you created.
6. Click Save current document to apply your changes.

Set up the UMPI start-up script Copied

1. From the Ultra Messaging integration files you downloaded, go to the examples folder.
2. Open start_umpi in a text editor.
3. Replace the values in brackets with the respective details from your system. For more information, see Appendix — Ultra Messaging plug-in start-up script variables.

Run the UMPI start-up script Copied

1. Open the Terminal.
2. Enter the following command:

bash$ chmod u+x start_umpi

Success

After you run the integration script, the umpiConfig dataview appears under the managed entity that you configured for the UMS.

Installation of client commands Copied

In the examples folder, the umpi.setup.xml contains a configuration for the UMS client commands.

In order to use this file, follow these steps:

1. Open umpi.setup.xml in a text editor.
2. Find all instances of “umpicmd”.
3. Update the directory for “umpicmd” to reflect the location of your integration files. For example, /usr/local/23west/umpicmd becomes /home/user/umpi/geneos-umpi-2.2.4/UMS_6.5/Linux_x86_64/glibc2.5.
4. Update all instances of this directory.
5. Save your changes.

Shutdown script Copied

If you want to shut down the UMPI, follow these steps:

1. Locate the PID file in the {LogLocation} you specified in Appendix — Ultra Messaging plug-in start-up script variables.
2. Open the Terminal.
3. Enter the following command, specifying the {LogLocation} and the PID file on your system. For example:

bash$ kill $(cat /home/user/log/geneos-umpi.pid )

Success

This command kills the process associated with the UMPI.

umpiConfig view Copied

Common UMS headlines and columns Copied

Each operational and full UMS view has a common set of headlines and columns that are used alongside the headlines and columns specific for each view.

Common headlines Copied

List of common headlines that appear in operational and full views:

Common columns Copied

List of common columns that appear in operational and full views:

Operational UMS views Copied

Each UMS source and receiver operational view has a common set of headlines and columns. If a column is not available for a particular transport type then each relevant cell in the operational view is blank.

Note

Operational views for contexts and event queues contain a subset of the information available in the relevant full view.

Source views Copied

List of operational headlines for UMPIUMS source views:

List of operational columns for UMPIUMS source views:

Receiver views Copied

List of operational headlines for UMPIUMS receiver views:

List of operational columns for UMPIUMS receiver views:

Metrics and dataviews Copied

Context views Copied

By default, geneos-umpi displays a subset of data available for a UMS object. This subset is referred to as operational views. The tables below show the complete set of data items available through the use of full commands.

Headlines and columns that are common for all views are also displayed, see Common UMS headlines and columns for a full list.

Note

For contexts, the names of columns in the operational views and in full views are the same.

List of headlines for UMPI context views:

List of derived columns for UMPI context views:

List of native columns for UMPI context views:

Active sort order of UMPI context views:

Status sort order of UMPI context views:

Event queue views Copied

By default, geneos-umpi displays a subset of data available for a UMS object. This subset is referred to as operational views. The tables below show the complete set of data items available through the use of full commands.

Headlines and columns that are common for all views are also displayed, see Common UMS headlines and columns for a full list.

Note

For event queues, the names of columns in the operational views and in full views are the same.

List of headlines for UMPI event queue views:

Note

There are no derived columns for event queue views.

List of native columns for UMPI event queues views (there are no derived columns in event queue views):

Active sort order of UMPI event queue views:

Status sort order of UMPI event queue views:

TCP source views Copied

By default, geneos-umpi displays a subset of data available for a UMS object. This subset is referred to as operational views. The tables below show the complete set of data items available through the use of full commands.

Headlines and columns that are common for all views are also displayed, see Common UMS headlines and columns for a full list. Note: For source views, the names of columns in the operational views and in full views may differ. For more information about different columns in operational source views, see Operational views - Source views.

List of headlines for UMPI TCP source views:

List of native columns for UMPI TCP source views (there are no derived columns in TCP source views):

Active sort order of UMPI TCP source views:

Status sort order of UMPI TCP source views:

TCP receiver views Copied

By default, geneos-umpi displays a subset of data available for a UMS object. This subset is referred to as operational views. The tables below show the complete set of data items available through the use of full commands.

Headlines and columns that are common for all views are also displayed, see Common UMS headlines and columns for a full list.

Note: For receiver views, the names of columns in the operational views and in full views may differ. For more information about different columns in operational receiver views, see Operational views - Receiver views.

List of headlines for UMPI TCP receiver views:

List of derived columns for UMPI TCP receiver views:

List of native columns for UMPI TCP receiver views:

Active sort order of UMPI TCP receiver views:

Status sort order of UMPI TCP receiver views:

LBT-RU source views Copied

By default, geneos-umpi displays a subset of data available for a UMS object. This subset is referred to as operational views. The tables below show the complete set of data items available through the use of full commands.

Headlines and columns that are common for all views are also displayed, see Common UMS headlines and columns for a full list. Note: For source views, the names of columns in the operational views and in full views may differ. For more information about different columns in operational source views, see Operational views - Source views.

List of headlines for UMPI LBT-RU source views:

List of derived columns for UMPI LBT-RU source views:

List of native columns for UMPI LBT-RU source views:

Active sort order of UMPI LBT-RU source views:

Status sort order of UMPI LBT-RU source views:

LBT-RU receiver views Copied

By default, geneos-umpi displays a subset of data available for a UMS object. This subset is referred to as operational views. The tables below show the complete set of data items available through the use of full commands.

Headlines and columns that are common for all views are also displayed, see Common UMS headlines and columns for a full list.

Note: For receiver views, the names of columns in the operational views and in full views may differ. For more information about different columns in operational receiver views, see Operational views - Receiver views.

List of headlines for UMPI LBT-RU receiver views:

List of derived columns for UMPI LBT-RU receiver views:

List of native columns for UMPI LBT-RU receiver views:

Active sort order of UMPI LBT-RU receiver views:

Status sort order of UMPI LBT-RU receiver views:

LBT-RM source views Copied

By default, geneos-umpi displays a subset of data available for a UMS object. This subset is referred to as operational views. The tables below show the complete set of data items available through the use of full commands.

Headlines and columns that are common for all views are also displayed, see Common UMS headlines and columns for a full list. Note: For source views, the names of columns in the operational views and in full views may differ. For more information about different columns in operational source views, see Operational views - Source views.

List of headlines forUMPI LBT-RM source views:

List of derived columns for UMPI LBT-RM source views:

List of native columns for UMPI LBT-RM source views:

Active sort order of UMPI LBT-RM source views:

Status sort order of UMPI LBT-RM source views:

LBT-RM receiver views Copied

By default, geneos-umpi displays a subset of data available for a UMS object. This subset is referred to as operational views. The tables below show the complete set of data items available through the use of full commands.

Headlines and columns that are common for all views are also displayed, see Common UMS headlines and columns for a full list.

Note: For receiver views, the names of columns in the operational views and in full views may differ. For more information about different columns in operational receiver views, see Operational views - Receiver views.

List of headlines for UMPI LBT-RM receiver views:

List of derived columns for UMPI LBT-RM receiver views:

List of native columns for UMPI LBT-RM receiver views:

Active sort order of UMPI LBT-RM receiver views:

Status sort order of UMPI LBT-RM receiver views:

LBT-IPC source views Copied

By default, geneos-umpi displays a subset of data available for a UMS object. This subset is referred to as operational views. The tables below show the complete set of data items available through the use of full commands.

Headlines and columns that are common for all views are also displayed, see Common UMS headlines and columns for a full list. Note: For source views, the names of columns in the operational views and in full views may differ. For more information about different columns in operational source views, see Operational views - Source views.

List of headlines for UMPI LBT-IPC source views:

List of derived columns for UMPI LBT-IPC source views:

List of native columns for UMPI LBT-IPC source views:

Active sort order of UMPI LBT-IPC source views:

UMPI LBT-IPC source has no status views.

LBT-IPC receiver views Copied

By default, geneos-umpi displays a subset of data available for a UMS object. This subset is referred to as operational views. The tables below show the complete set of data items available through the use of full commands.

Headlines and columns that are common for all views are also displayed, see Common UMS headlines and columns for a full list.

Note: For receiver views, the names of columns in the operational views and in full views may differ. For more information about different columns in operational receiver views, see Operational views - Receiver views.

List of headlines for UMPI LBT-IPC receiver views:

List of derived columns for UMPI LBT-IPC receiver views:

List of native columns for UMPI LBT-IPC receiver views:

Active sort order of UMPI LBT-IPC receiver views:

Status sort order of UMPI LBT-IPC receiver views:

LBT-RDMA source views Copied

By default, geneos-umpi displays a subset of data available for a UMS object. This subset is referred to as operational views. The tables below show the complete set of data items available through the use of full commands.

Headlines and columns that are common for all views are also displayed, see Common UMS headlines and columns for a full list. Note: For source views, the names of columns in the operational views and in full views may differ. For more information about different columns in operational source views, see Operational views - Source views.

List of headlines for UMPI LBT-RDMA source views:

List of derived columns for UMPI LBT-RDMA source views:

List of native columns for UMPI LBT-RDMA source views:

Active sort order of UMPI LBT-RDMA source views:

UMPI LBT-RDMA source has no status views.

LBT-RDMA receiver views Copied

By default, geneos-umpi displays a subset of data available for a UMS object. This subset is referred to as operational views. The tables below show the complete set of data items available through the use of full commands.

Headlines and columns that are common for all views are also displayed, see Common UMS headlines and columns for a full list.

Note: For receiver views, the names of columns in the operational views and in full views may differ. For more information about different columns in operational receiver views, see Operational views - Receiver views.

List of headlines UMPI LBT-RDMA receiver views:

List of derived columns for UMPI LBT-RDMA receiver views:

List of native columns for UMPI LBT-RDMA receiver views:

Active sort order of UMPI LBT-RDMA receiver views:

Status sort order of UMPI LBT-RDMA receiver views:

UMS 5.2 Gateway daemon tnwgd views Copied

The UMPI displays up to three Gateway related views. Gateway related views are displayed if at least one Gateway is configured on the API sampler using a TNWGD_URLnn configuration parameter. Portal specific views (GW-PeerPortals and GW-EndpointPortals) appear if at least one portal of the appropriate type is found on a configured Gateway that is providing monitoring statistics correctly (specifically where the value of the OK column of the relevant row in the GW-tnwgd view is Y).

List of UMPIGW-tngwd view columns:

List of UMPIGW-PeerPortals view columns:

List of UMPIGW-EndpointPortals view columns:

Dynamic router daemon tnwgd views Copied

The UMPI displays up to three router related views. Router related views are displayed if at least one router is configured on the API sampler using a TNWGD_URLnnn configuration parameter. Portal specific views (peerPortals and endPointPortals) appear if at least one portal of the appropriate type is found on a configured router that is providing monitoring statistics correctly (specifically where the value of the OK column of the relevant row in the dynamicRouters view is Y).

List of UMPIdynamicRouters view columns:

List of UMPIpeerPortals view columns:

List of UMPIendPointPortals view columns:

Defunct views Copied

The UMPI routinely checks for activity from its monitored objects. When an object stops sending statistics, the UMPI removes that object, where applicable, from its activity and status views, and places the object in a defunct view.

The TIMEOUTsampler parameter determines how long the UMPI waits before it declares an object defunct.

If the UMPI receives statistics from a defunct object, then it removes the object from the defunct view and reinstates it in the relevant activity and status views, where applicable. If no objects remain in the defunct view, then the UMPI removes the view.

Defunct objects are automatically discarded after a configurable time period. The DEFUNCT_TIMEOUT sampler parameter determines how long the UMPI waits before it discards defunct objects.

To view the complete list of sampler parameters, see the API sampler parameters.

Appendix — Ultra Messaging plug-in startup script variables Copied

The start_umpi file is a default template for the start-up script, which sets up the Ultra Messaging integration. You need to replace the bracketed fields following your integration directories.

Note

Remove the brackets ({}) when adding you system credentials into the startup script.

#!/bin/bash

# Template start-up script for the Geneos UltraMessaging plugin, geneos-umpi.
# See the plug-in manual for a further explanation of this script.

# The install location of the required plug-in executable.
export UMPI_DIR={InstallLocation}

# The location to which the plug-in can write log files
export LOG_DIR={LogLocation}

# The location of the relevant UM release.
export UM_DIR={UMLocation}

# Set the library search path.
export LD_LIBRARY_PATH=$UM_DIR/lib:$UMPI_DIR:$LD_LIBRARY_PATH

$UMPI_DIR/geneos-umpi UM \
    --hostname=localhost \
    --port=7036 \
    --sampler=UltraMessaging \
    --detach=$LOG_DIR \
    --log=geneos-umpi.log \
    --pidfile=geneos-umpi.pid \
    --license=geneos-umpi.lic \
    --verbose

# start_umpi

Note

In the startup script, notice the line --verbosenear the end of the file. You may change this to --brief or --debug. This setting determines whether the UMPI returns brief or verbose logs and error messages.