Geneos
You are currently viewing an older version of the documentation. You can find the latest documentation here.

Ultra Messaging Monitoring User Guide

Overview

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

This guide is directed towards experienced Geneos users who want to set up an integration between Geneos and UMS applications.

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

Prerequisites

The following requirements must be met prior to 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

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

  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

  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

  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

  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 startup script variables.

Run the UMPI start-up script

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

    3. 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. For more information, see the umpiConfig view.

Installation of client commands

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

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 startup script variables.
  2. Open the Terminal.
  3. Enter the following command, specifying the {LogLocation} and the PID file on your system. For example:

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

    Success: This command kills the process associated with the UMPI.

Further reading

The Ultra Messaging plug-in provides powerful customisable views on dynamic routers and gateways, powered by the tnwgd. After you have set up the integration, you can learn about its dataviews and plug-in configuration in the Ultra Messaging Monitoring Technical Reference.

Appendix — Ultra Messaging plug-in startup script variables

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
Variable Example value Description
{InstallLocation} /home/user/umpi/geneos-umpi-2.2.4/UMS_6.5/Linux_x86_64 The directory where you unpacked the Ultra Messaging integration files downloaded from the ITRS Downloads page.
{LogLocation} /home/user/umpi

The directory where you want the UMPI to write its output files:

  • log files
  • process identifier (PID) files
{UMLocation} /home/user/lib/29west The directory where your UMS application is running.

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. For more information on commands available to the UMPI, see the UMPI daemon command synopsis in Ultra Messaging Monitoring Technical Reference