Event formatter changes with MQ 9.2.4

IBM has just announced MQ 9.2.4. No matter how hard you search the announcement letters you will still not be able to find anything about the event formatter changes that I was able to slip into the release. That’s because changes to samples don’t normally deserve highlighting in formal marketing documents. But I hope this change still turns out to be useful.

Based on things I’ve found while writing earlier posts, and some customer requests and questions, I took the opportunity to make a couple of small changes to the amqsevt event formatter program.

The amqsevt sample is a program that takes MQ event messages and converts them from PCF into either JSON or “english-ish” text.

In this post, I showed how it could be used to take events and send them to Loki – a JSON-ingester. But I had to tweak the output slightly using the jq program to make it more suitable for centralisation. And I did something similar with the output of the REST-based configuration dumper. The latest changes remove the need for that separate jq step, getting rid of another component when you want to script the processing of events.

Enhanced output options

In MQ 9.2.4, amqsevt has been extended to

• Add the queue manager name to the output for the JSON formats
• Write an entire event on a single line (a new -o json_compact option)

The queue manager name is important when you send output from multiple systems to a central location for further analysis or reporting. This is much more likely to be done with the JSON variant.

And a number of tools expect to receive JSON data in a single-line format. One tool that I’ll make use of in a few moments is the amqsput sample.

This example, despite overflowing in the panel, really is just a single line.

$ amqsevt -m QM1 -b -q SYSTEM.ADMIN.QMGR.EVENT -o json_compact
 { "eventSource" : { "objectName": "SYSTEM.ADMIN.QMGR.EVENT",                   "objectType" : "Queue",                   "queueMgr" : "QM1"}, "eventType" : {     "name" : "Queue Mgr Event",     "value" : 44   }, "eventReason" : {     "name" : "Queue Mgr Active",     "value" : 2222   }, "eventCreation" : {     "timeStamp"  : "2021-10-29T07:56:03Z",     "epoch"      : 1635494163   }, "eventData" : {   "queueMgrName" : "QM1",   "hostName" : "mydesktop.hursley.uk.ibm.com",   "reasonQualifier" : "Failover Not Permitted" } }

One scenario that people have asked about is about using the MQ REST API to read event messages. That is not directly possible as the messages are in the binary PCF format and are therefore not readable through the REST interface. But by using amqsevt as an intermediary, we can now do things like put reformatted output back as a text message to a queue that REST users can work with.

Before, I had scripts that used jq with some programming in its own language to modify the output. Now I can have an even easier script. You can start it as an MQ service for environments where local programs are available. Or a script could use client connections for remote queue managers. This does not need any additional programs – just the standard MQ-shipped samples.

A simple service

The key line in a SERVICE script can be as simple as

amqsevt -m <qmgr> -o json_compact | amqsput <q> <qmgr>

The hardcoded buffer size for amqsput should be large enough for all events, even when expanded into JSON. And we don’t need to name the specific event queues as, by default, amqsevt opens all of the normal locations. The single-line format means that the entire event appears as a single message on the output queue.

Now I can use the MQ REST interface to get event messages from the secondary queue as text data.

$ curl -X DELETE -Ss -u 'mqguest:passw0rd' --header 'ibm-mq-rest-csrf-token: random' --header 'Accept: text/plain' -k https://localhost:9443/ibmmq/rest/v2/messaging/qmgr/QM1/queue/EVENT.TEXT/message

{ "eventSource" : { "objectName": "SYSTEM.ADMIN.QMGR.EVENT",                   "objectType" : "Queue",                   "queueMgr" : "QM1"}, "eventType" : {     "name" : "Queue Mgr Event",     "value" : 44   }, "eventReason" : {     "name" : "Queue Mgr Active",     "value" : 2222   }, "eventCreation" : {     "timeStamp"  : "2021-10-29T07:56:03Z",     "epoch"      : 1635494163   }, "eventData" : {   "queueMgrName" : "QM1",   "hostName" : "mydesktop.hursley.uk.ibm.com",   "reasonQualifier" : "Failover Not Permitted" } }

Of course, you might prefer to send the event messages to somewhere else that works with JSON messages – Loki as I wrote about before, Splunk or an ELK stack perhaps.

Summary

These are small changes that you could make yourself to a sample program. But I hope this makes it easier to combine and use the programs as-is when they are shipped with the MQ product.

This post was last updated on November 24th, 2021 at 01:12 pm