Introducing MQ Error Logs in JSON Format
ElliotGregory
Published on 05/12/2017 / Updated on 28/01/2019
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
TAGS JSON, LOGGING, MQ
by ElliotGregory
4 comments on"Introducing MQ Error Logs in JSON Format"
- Morag HughsonJanuary 27, 2019
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.
Reply (Edit)
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.
- Morag HughsonJanuary 27, 2019
The environment variable AMQ_ADDITIONAL_JSON_LOG does not appear to be documented in KC. Or at least a search does not find it.
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