IBM MQ

Introducing MQ Error Logs in JSON Format 

Wed March 04, 2020 03:04 PM

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 JSONLOGGINGMQ

by ElliotGregory

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

  1. 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.

 

  1. 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

 

Entry Details

Statistics
0 Favorited
3 Views
1 Files
0 Shares
0 Downloads
Attachment(s)
pdf file
Introducing MQ Error Logs in JSON Format.pdf   115K   1 version
Uploaded - Wed March 04, 2020

Tags and Keywords

Related Entries and Links

No Related Resource entered.