Getting Started Using Nastel XRay for MQ
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.
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
- Different environments
- Verify correct processing of error conditions
- Queue Full, Queue not found, etc.
- Identify applications doing “unnecessary” calls
- 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.
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.
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
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.
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:
- the url of the XRay server i.e. https://data.jkoolcloud.com
- your Access Token which you were given during the account registration. (If you need to find this again then go to https://www.nastel.com/xray/memberand click on “Set up XRay for MQ”)
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.
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
You could actually have done this as soon as you’d configured the probe.
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 email@example.com if you need help or leave comments below.