Up until now, MQ Error logs have only been in human readable format. This makes it challenging for other applications to digest the information in these logs.

We’ve been looking at how to make that easier, so as of MQs continuous delivery release 9.0.4 it is now possible to have the same information in JSON format. This is more a technology preview than a fully fledged feature so some of the specifics may change in the future. However if you’re happy to experiment please read on…

How to enable JSON format error log.

This is an opt-in feature, and by setting an environment variable AMQ_ADDITIONAL_JSON_LOG with the value 1 prior to running MQ commands, for example starting MQ with strmqm, it will generate JSON formatted error logs as well as the original format.

Where are these JSON formatted error logs.

They are located in the same directories as the AMQLOG01/2/3.LOG files and have names AMQLOG01/2/3.json. As with the original error logs there are separate JSON error log files for each queue manage and also for system errors.

What is contained in a JSON formatted error log

Here is a sample JSON entry (it’s been reformatted for readability)

{
"ibm_messageId": "AMQ5051I",
"arith_insert_2": 1,
"comment_insert_1": "LOGGER-IO",
"ibm_datetime": "2017-11-16T09:54:26.331Z",
"ibm_serverName": "QM1",
"type": "mq_log",
"host": "machine.somewhere.ibm.com",
"loglevel": "INFO",
"module": "amqzmut0.c:1650",
"ibm_sequence": "1510826066_332014693",
"ibm_processId": 7846,
"ibm_threadId": 4,
"ibm_version": "9.0.4.0",
"ibm_processName": "amqzmuc0",
"ibm_userName": "somebody",
"ibm_installationName": "Installation3",
"ibm_installationDir": "/opt/mqm",
"message": "AMQ5051I: The queue manager task 'LOGGER-IO' has started."
}

and here is the textual equivalent


16/11/17 09:54:26 - Process(7846.4) User(somebody) Program(amqzmuc0)
Host(machine.somewhere.ibm.com) Installation(Installation3)
VRMF(9.0.4.0) QMgr(QM1)
Time(2017-11-16T09:54:26.331Z)
ArithInsert2(1)
CommentInsert1(LOGGER-IO)

AMQ5051I: The queue manager task 'LOGGER-IO' has started.

EXPLANATION:
The critical utility task manager has started the LOGGER-IO task. This task has
now started 1 times.
ACTION:
None.

In general, the JSON form has more information than it’s textual version with a notable exception. There is no Explanation or Action entries, but these are be generated using the mqrc command, for example


mqrc –n 1 –n 1 –c LOGGER-IO AMQ5051

All of the JSON entries

Below is a table of possible entries that could occur in a JSON error log. Most JSON error logs will only contain subset. In the sample above there are two inserts, but potential there could be up to five inserts

Name Optional Description
ibm_messageId No message identifier for example AMQ5051I
ibm_arithInsert1 Yes first numerical insert value
ibm_arithInsert2 Yes second numerical insert value
ibm_commentInsert1 Yes first string insert value
ibm_commentInsert2 Yes second string insert value
ibm_commentInsert3 Yes third string insert value
ibm_datetime No ISO8601 format of the date and time when the message was generated
ibm_serverName Yes name of the queue manager
type No type of error log currently only “mq_log”
host No name of the host machine
loglevel No severity of the error log, i.e. ERROR
module No internal details of where the message was generated
ibm_sequence No unique reference number
ibm_remotehost Yes IP address of remote machine
ibm_processId No o/s reference for the process generating the message
ibm_threadId No o/s reference for the thread generating the message.
ibm_version No MQ version
ibm_processName No name of the process generating the message
ibm_userName No real user id of the process generating the message
ibm_installationName No name of the associated installation
ibm_installationDir No location of the installed files

Useful Knowledge center links:

Error Logs https://www.ibm.com/support/knowledgecenter/SSFKSJ_9.0.0/com.ibm.mq.tro.doc/q114840_.htm

4 comments on"Introducing MQ Error Logs in JSON Format"

  1. The -n and -c parameters to mqrc don’t appear to be documented in KC. Also, I am using MQ V911 and they don’t appear to work either, they just cause the usage to be shown. The usage does contain them however. I have also tried on V904, V905, and V910. I am using exactly the same command as you described above. Only difference would appear to be that you were on Unix (your Installation Path is /opt/mqm) whereas I am on Windows.

    • LaurenceBonney January 28, 2019

      Hi Morag, good spot! I’ll get the KC updated to include those two options.

      I’ve given it a try and its working for me on Linux and Windows. Note that you must specify the -c and/or -n inserts prior to adding the AMQnnnnn message code, for example:

      $ mqrc -c wibble AMQ8024I

      32804 0x00008024 urcMS_STA_CHINIT_OK

      MESSAGE:
      IBM MQ channel initiator started.

      EXPLANATION:
      The channel initiator for queue wibble has been started.

      ACTION:
      None.

      If a command takes multiple inserts you’d add them with multiple -c/-n options.

      The original example was misleading and left the unparameterised message code at the start of the options list, which although technically would work on Unixes based on the way the MQ command parsing works but isn’t the intended way the command should be used, so I’ve updated the blog post to put it at the end.

  2. The environment variable AMQ_ADDITIONAL_JSON_LOG does not appear to be documented in KC. Or at least a search does not find it.

    • LaurenceBonney January 28, 2019

      Hi Morag, since this blog was released we’ve updated MQ to support configuring JSON logging via the DiagnosticMessages ini file stanza, the environment variable was only a stop gap measure and as such did not go into the Knowledge Center once we finished its implementation.

      A good jumping off point to read up on how to configure JSON logging for MQ is here.

      A quick example defining a new qm.ini log stanza to create a basic JSON log for a qmgr to match the data in the traditional AMQERR formatted log files:

      DiagnosticMessages:
      Service = File
      Name = JSONLogs
      FilePrefix = AMQERR
      Format = json # json is the default

Join The Discussion

Your email address will not be published.