Getting Started Using Nastel XRay for MQ On-Prem Version

In my previous blog post, Getting Started Using Nastel XRay for MQ, I gave an overview of Nastel’s free MQ tracing/monitoring/diagnostics solution, available here, and I described how to install and set up the cloud version. This has proved to be very popular but some people would prefer not to send data to the cloud, even if it’s just metadata, so in this post I go through the steps to set up on-premise version.

image001
Nastel XRay for MQ

Purpose

I won’t repeat the whole overview as you can read it in the previous post, but as reminder, the purpose of the Nastel XRay for IBM MQ is to analyse applications making MQ calls and determine their behaviour. Examples of the value of tracing include:

  • Tracking individual application calls:
    • Identify applications doing “unnecessary” calls
      1. Inefficient logic
    • Identify applications not conforming to “standards”
      1. Not providing expiry
      2. Not resetting message ID
    • Observe timings of calls based on different scenarios
      1. Persistence
      2. Different environments
    • Verify correct processing of error conditions
      1. Queue Full, Queue not found, etc.
    • Summarise application calls:
      • Identify Patterns
    • Problem determination:
      • What is the application actually doing?

Many other use cases are possible, for example these MQ events can be used as part of business transaction tracking scenarios.

Installation

There are two components to XRay.

  • The Nastel XRay server which hosts all the collected data for search, analytics, visualization, automation etc.
  • The probe collects the information from MQ. It runs in your MQ environment (or connects remotely to it)

Installing Docker

For on-premise we use the Docker version of the XRay server, which is only available on Linux, although the monitored MQ can be on any platform.

The documentation says that in order to run as a Docker container, the following minimum requirements must be met:

  • 16 GB of RAM (I tried running with 3GB and found that it hung when setting up Solr).
  • 4 virtual processors

I didn’t already have Docker installed so I typed ‘docker’ on the command line and it said

The program 'docker' is currently not installed. You can install it by typing:
sudo apt install docker.io

so that’s what I did, and it installed easily.

It turns out that it’s also really important to run the following command (and log out and in again) to put the user into the docker group, otherwise you can hit problems with the Nastel Xray install.

sudo usermod -a -G docker $USER

Installing the XRay Server

On the first page, click on the Register for Nastel XRay Docker Edition button. Once you’re through the registration process you will be given a link to download the software and another to view the documentation.

Once downloaded, uncompress the software using unzip or your preferred extraction software, and switch to the docker directory

cd XRayStarterPack/docker

There are various scripts in that folder to help you manage the installation. There is one program which provides a menu to call the others:

./xray_menu.sh

Select option 1

1. Deploy XRay Starter Pack containers

This downloads the Docker images, creates the containers and executes them. This is typically only run once. It will ask you for your XRay advertised host name – this just means the host that you’re installing on that the probes will be publishing too. You can normally press enter and accept the default although in may case it was a virtual host with complicated networking so I entered the actual ip address at this point.

It may also ask you for the location of two license files. Just press enter to accept the defaults.

The download time will depend on your bandwidth and then there’s a five minute wait while it configures everything.

Then it will say:

You can reach XRay by this url: http://apsvr:8080/xray

You can stream data to this url: http://apsvr:6580

or similar (my hostname is apsvr).

At this point you can go to a web browser and go to the XRay url and login with user Admin and password admin. Of course, you will change these once you’re up and running.

image003
image004

Once you’re logged in, click on Go to Dashboard

This will take you to the sample repository and the sample dashboards:

image006

You should take a look around these, guided by the installation document.

Then you can switch to your own repository where your own data and dashboards will go.

image008

On the cloud version you would have to import the dashboards but on the Docker version this has already been done.

Installing the Probes

Now you need to install the probes onto your MQ machine. In my case this was onto a separate Windows machine. So, I downloaded the same zip file that I’d put onto Linux and unzipped it on Windows.

run \XRayStarterPack\run\XRay_setup.cmd

It will ask you to enter:

  • the url of the XRay server, so in my case this was http://apsvr:6580
  • your Access Token – for the docker version this is DefaultToken

Next you need to edit

\XRayStarterPack\run\ibm-mq-trace-events\XRayMQ_parser.xml

If the probe is running locally then you just need to provide the queue manager name. Alternatively, you can use a client server connection in which case you’d have to provide the connection information too.

To monitor a second local queue manager just copy the stanza and add the next queue manager name but also change the stream name so that each one is unique. You could also monitor a second queue manage on a second machine by installing the probe on that machine too.

Configure MQ

Switch on activity trace by setting the queue manager property ACTVTRC(ON).

This means that everything will be traced. This is great for getting started. However if you run tools such as MQ Explorer you will find that it generates far too much data so once you’re up and running you’ll want to go back and edit mqat.ini to include or exclude data some applications and functions from the trace.

Run the probe

Now you can start collecting data and seeing it in the dashboards by running the probe on the managed machine with

\XRayStarterPack\run\ibm-mq-trace-events\run.bat

You could actually have done this as soon as you’d configured the probe.

Dashboards

Very soon you should start to see the data appearing in the dashboards

image010

You could also look at the raw events. Click on the plus sign at the bottom:

image012

To get to the jKQL (jKool Query language) command line. If you type in get event it will list all the trace events that it’s received.

image013

Try clicking around on some of the hyperlinks within this. You will notice that all the dashboard viewlets were created with jKQL commands which you can edit too. If you’re feeling adventurous you could even read the jKQL Users Guide here.

Conclusion

The free version is the full function product with the limit that single user can stream 500MB of event data per day and store them for 5 days. If you’re careful about what data you capture this could be sufficient for many use cases. Hopefully this blog post has given you an idea of how to use Nastel XRay for MQ on premise and will get you started using it.