Creating situations to monitor IBM MQ messages

By using the message monitoring feature of the IBM® MQ Monitoring Agent, you can create situations to monitor the header and content of IBM MQ messages.

1. Configure the IBM MQ Monitoring Agent with the monitoring options for the queue to enable message monitoring situations and the returned values that trigger the situation.
   1. Enable situations to be created for message monitoring by using the MSGSITMON and MSGSITACCOUNT parameters in the SET MANAGER, SET GROUP or SET QACCESS statements.
      For example,

      MSGSITMON (YES)
      MSGSITACCOUNT (MQAGENT)

      Remember: You must set the MSGSITMON value to YES to enable messages monitoring situations. You must also specify the MSGSITACCOUNT parameter. Otherwise, the MSGSITMON parameter alone does not take effect.
   2. Decide whether you want to see all the values from the data sample that triggers the situation by specifying the MSGACCESS parameter value for the queue.

      MSGACCESS (NONE)

      You cannot check the data that triggers the message monitoring situation event.

      MSGACCESS (RETRY)

      You cannot check the data that triggers the message monitoring situation event.

      MSGACCESS (DESC)

      You can check the data that triggers the message monitoring situation event, but you cannot see the message content.

      MSGACCESS (DATA)

      You can check all the values from the data sample that triggers the message monitoring situation event.

      MSGACCESS (DELETE)

      You can check all the values from the data sample that triggers the message monitoring situation event.

2. Use the Situation Editor to create the message monitoring situation by using attributes from the Message Summary attribute group.
   Remember:

   • Only the following patterns are supported to filter queue names:
     • Queue name that does not start with the given string: STR(Queue Name, 1) != <value>
     • Queue name that starts with the given string: STR(Queue Name, 1) = <value>
     • Queue name that contains the given string: SCAN(Queue Name) == <value>
     • Queue name that is the given string: Queue Name == <value>
   • Use the Msg Count Filter attribute to specify the number of messages that are returned for each eligible queue in the situations. You can set only one Msg Count Filter value in one situation, and it applies to all the queues that are specified in the situation.
   • When there is no Msg Count Filter value defined in a situation, only one message is returned for each queue if the situation is true for multiple queues. If the situation is true for only one queue, 500 messages can be returned.
   • A maximum of 500 messages can be monitored by a situation.
   For example, to detect when the first message on a non-system queue has gone through backout processing, specify the following formula in the situation:

   Backout Count > 0 AND Msg Count Filter == 1 AND STR(Queue Name) != 1,SYSTEM

   To detect an application has queued a message that signifies a particular type of error on the application error queue, specify the following formula in the situation:

   Queue Name == EXAMPLE.QUEUE 1 AND SCAN(Msg Content) == 'TYPE 1'

   To detect that the first message on a queue has not changed since the last situation interval, specify the following formula in the situation:

   Msg Count Filter == 1 AND Queue Name == EXAMPLE.QUEUE.MQ15i AND CHANGE(Message Tag 64bit) == 0

3. When the situation fires, use the initial situation values table view in the event results workspace to check the attribute values that trigger the situation. All or partial data can be returned, depending on the MSGACCESS parameter that you specified for the queue.