Nastel XRay for MQ overview
Nastel XRay for MQ

Nastel has a free version of its MQ tracing solution called Nastel XRay for MQ available here. In this post I will give an overview of its purpose, its use, and how to install it.

Purpose

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
      • Inefficient logic
    • Identify applications not conforming to “standards”
      • Not providing expiry
      • Not resetting message ID
    • Observe timings of calls based on different scenarios
      • Persistence
      • Different environments
    • Verify correct processing of error conditions
      •  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.

How It’s Used

The dashboards that come with the free installation include:

  • MQ Error Analysis
  • MQ Call Analysis
  • Search for Message Data

You can also create your own dashboards by using the jKQL query language.

The MQ Call Analysis dashboard

There are various viewlets.

Summary

In this case, this shows a summary of all of the MQ calls captured by the queue manager.

MQ Calls by Type

This viewlet breaks down the MQ calls collected by their type.

In this case, we can see a lot of MQOPEN, MQCLOSE and MQCONNX calls which may be interesting sometimes, but in many cases, you will want to focus on the puts and gets. That could be done by modifying the query run to display the data or in the data collected itself.

MQ Object Breakdown

This displays what queues were used, but it could contain topics and other objects for some call types. This viewlet shows the total MQ calls against each MQ queue.

Persistence Percentages

This displays the breakdown by persistence. Many organizations require persistent messages, so this viewlet would be useful to identify which applications are sending non-persistent messages.

You can easily drill into the data to see which queues were in this group. In all viewlets, you can drill in by clicking on the pie chart or the bar chart. Clicking the non-persistent portion of the chart opens a new window at the bottom of the display showing the non-persistent calls.

MQ Calls over Time

This shows the MQ calls being done over the latest day.

MQ Calls by Application

This viewlet will be useful in determining which applications are being traced.

The MQ Error Analysis Dashboard

This dashboard has details specific to MQ errors that are occurring. The following are the viewlets

Summary

The first summary shows the total number of MQ errors by queue manager and the second shows the total number by MQ error code.

MQ Calls by Completion Code

This shows the errors versus the total number of calls. In this case, 60 requests resulted in an error, just over 8 percent.

MQ Exception List

This shows the breakdown of the errors by type. In this case, the majority were inhibited put events. You can link to see which requests these were.

The Search for Message Data Dashboard

When you click on this tab, a dialog will be presented.

Enter a string from the message payload, for example Payment. The viewlet will refresh and display the matching requests.

You can select the envelope icon next to the message preview to view the entire message

Alternatively the general search field can be used to search across all data elements, including the payload, but also the queue name, queue manager name, user, and so on.

Installation

There are two versions available – one hosted in the cloud and one is in a docker container so can be installed on-premise. In this blog post I talk through my experience of using the cloud based one monitoring a Windows environment.

There are two components to XRay.

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

You download the probe software from here.

You register to use the server here.

Configure the probe

Uncompress the probe software and run \XRayStarterPack\run\XRay_setup.cmd

It will ask you to enter:

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.

Configure the XRay Dashboards

Log in to the XRay server and click on Go to Dashboard

Go to the repository list where all the samples are as well as your own repository at the top

Select your repository

The next dialog box will ask you to create a dashboard. Just click cancel on that as we want to import the ones that came in the download of the probe software. On the top right corner of the screen, click on the Main Menu icon and select Import/Export > Dashboards.

Import the file \XRayStarterPack\XRayStarterPack\dashboard\NastelXRayMQStarterPackDashboard.json

After a short pause, the list of dashboards will be presented. Select All and click Open.

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.

Conclusion

Hopefully this blog post has given you an idea of how to use the free version of Nastel XRay for MQ and will get you started using it. Feel free to mail me at sgarforth@nastel.com if you need help or leave comments below.