What instrumentation events are

 


Overview

In WebSphere MQ, an instrumentation event is a logical combination of conditions that is detected by a queue manager or channel instance. Such an event causes the queue manager or channel instance to put a special message, called an event message, on an event queue. WebSphere MQ instrumentation events provide information about errors, warnings, and other significant occurrences in a queue manager. You can use these events to monitor the operation of queue managers.

Conditions that can give rise to instrumentation events include:

  • A threshold limit for the number of messages on a queue is reached.
  • A channel instance is started or stopped.
  • A queue manager becomes active, or is requested to stop.
  • An application tries to open a queue specifying a user ID that is not authorized
  • Objects are created, deleted, changed or refreshed

Putting a message on the dead-letter queue can cause an event to be generated if the event conditions are met.

 

Event notification through event queues

When an event occurs, the queue manager puts an event message on the appropriate event queue, if defined. The event message contains information about the event that you can retrieve by writing a suitable MQI application program that:

You can define event queues either as local queues, alias queues, or as local definitions of remote queues. If you define all your event queues as local definitions of the same remote queue on one queue manager, you can centralize your monitoring activities.

You must not define event queues as transmission queues, because event messages have formats that are incompatible with the format of messages required for transmission queues.

Shared event queues are local queues defined with the QSGDISP(SHARED) value. For more information about defining shared queues, see the WebSphere MQ for z/OS System Setup Guide.

 

Types of event

WebSphere MQ instrumentation events come in the following types:

Queue manager events
Definitions of resources within queue managers. For example, an application tries to put a message to a queue that does not exist.

Channel events
Reported by channels as a result of conditions detected during their operation. For example, when a channel instance is stopped.

Performance events
Notifications that a threshold condition has been reached by a resource. For example, a queue depth limit has been reached.

Configuration events
Notifications about the attributes of an object. They are generated automatically when the object is created, changed, or deleted, and are also generated by explicit requests. For example, when a namelist is created.

For each queue manager, each category of event has its own event queue. All events in that category result in an event message being put onto the same queue.

Event queue: Contains messages from:
SYSTEM.ADMIN.QMGR.EVENT Queue manager events
SYSTEM.ADMIN.CHANNEL.EVENT Channel events
SYSTEM.ADMIN.PERFM.EVENT Performance events
SYSTEM.ADMIN.CONFIG.EVENT Configuration events

By incorporating instrumentation events into your own system management application, you can monitor the activities across many queue managers, across many different nodes, for multiple WebSphere MQ applications. In particular, you can monitor all the nodes in your system from a single node (for those nodes that support WebSphere MQ events).

Instrumentation events can be reported through a user-written reporting mechanism to an administration application that can present the events to an operator.

Instrumentation events also enable applications acting as agents for other administration networks, for example NetView, to monitor reports and create the appropriate alerts.

 

Queue manager events

Queue manager events are related to the use of resources within queue managers, such as an application trying to put a message to a queue that does not exist. The event messages for queue manager events are put on the SYSTEM.ADMIN.QMGR.EVENT queue. The following queue manager event types are supported:

  • Authority
  • Inhibit
  • Local
  • Remote
  • Start and stop

For each event type in this list, there is a queue manager attribute that enables or disables the event type.

The conditions that give rise to the event include:

  • An application issues an MQI call that fails. The reason code from the call is the same as the reason code in the event message.

    A similar condition can occur during the internal operation of a queue manager, for example, when generating a report message. The reason code in an event message might match an MQI reason code, even though it is not associated with any application. Do not assume that, because an event message reason code looks like an MQI reason code, the event was necessarily caused by an unsuccessful MQI call from an application.

  • A command is issued to a queue manager and processing this command causes an event. For example:

    • A queue manager is stopped or started.
    • A command is issued where the associated user ID is not authorized for that command.

 

Authority events

Authority events report an authorization, such as an application trying to open a queue for which it does not have the required authority, or a command being issued from a user ID that does not have the required authority.

For more information about the event data returned in authority event messages see:

Not Authorized (type 1)
Not Authorized (type 2)
Not Authorized (type 3)
Not Authorized (type 4)

 

Inhibit events

Inhibit events indicate that an MQPUT or MQGET operation has been attempted against a queue, where the queue is inhibited for puts or gets.

For more information about the event data returned in inhibit event messages, see:

Get Inhibited
Put Inhibited

 

Local events

Local events indicate that an application (or the queue manager) has not been able to access a local queue or other local object. For example, an application might try to access an object that has not been defined.

For more information about the event data returned in local event messages, see:

Alias Base Queue Type Error
Unknown Alias Base Queue
Unknown Object Name

 

Remote events

Remote events indicate that an application (or the queue manager) cannot access a (remote) queue on another queue manager. For example, the transmission queue to be used might not be correctly defined.

For more information about the event data returned in the remote event messages, see:

Default Transmission Queue Type Error
Default Transmission Queue Usage Error
Queue Type Error
Remote Queue Name Error
Transmission Queue Type Error
Transmission Queue Usage Error
Unknown Default Transmission Queue
Unknown Remote Queue Manager
Unknown Transmission Queue

 

Start and stop events

Start and stop events indicate that a queue manager has been started or has been requested to stop or quiesce.

Stop events are not recorded unless the default message-persistence of the SYSTEM.ADMIN.QMGR.EVENT queue is defined as persistent.

For more information about the event data returned in the start and stop event messages, see:

Queue Manager Active
Queue Manager Not Active

 

Channel events

Channel events are reported by channels as a result of conditions detected during their operation, such as when a channel instance is stopped. Channel events are generated:

  • By a command to start or stop a channel.
  • When a channel instance starts or stops.
  • When a channel receives a conversion error warning when getting a message.
  • When an attempt is made to create a channel automatically; the event is generated whether the attempt succeeds or fails.

Notes:

  1. Client connections on MQSeries for OS/390 Version 2, MQSeries Version 5, or later products, do not cause Channel Started or Channel Stopped events.

When a command is used to start a channel, an event is generated. Another event is generated when the channel instance starts. However, starting a channel by a listener, runmqchl, or a queue manager trigger message does not generate an event; in this case the only event generated is when the channel instance starts.

A successful start or stop channel command generates at least two events. These events are generated for both queue managers connected by the channel (unless one of the queue managers does not support events, as they do in versions of MQSeries for AS/400(R) previous to V3R2). Channel event messages are put onto the SYSTEM.ADMIN.CHANNEL.EVENT queue, if it is available. Otherwise, they are ignored.

If a channel event is put onto an event queue, an error condition causes the queue manager to create an event as usual.

For more information about the event data returned in the channel event messages, see:

Channel Activated
Channel Auto-definition Error
Channel Auto-definition OK
Channel Conversion Error
Channel Not Activated
Channel Started
Channel Stopped
Channel Stopped By User

 

SSL events

The only SSL event is the Channel SSL Error event. This event is reported when a channel using the SSL fails to establish an SSL connection.

For more information about the event data returned in the message specific to the SSL event, see Channel SSL Error

 

Performance events

These events report that a resource has reached a threshold condition. For example, a queue depth limit might have been reached.

Performance events relate to conditions that can affect the performance of applications that use a specified queue. They are not generated for the event queues themselves.

The event type is returned in the command identifier field in the message data.

If a queue manager tries to put a queue manager event or performance event message on an event queue and an error that would normally create an event is detected, another event is not created and no action is taken.

MQGET and MQPUT calls within a unit of work can generate performance events regardless of whether the unit of work is committed or backed out.

There are two types of performance event:

 

Queue depth events

Queue depth events relate to the number of messages on a queue; that is how full, or empty, the queue is. These event is supported for shared queues.

 

Queue service interval events

Queue service interval events relate to whether messages are processed within a user-specified time interval. These events are not supported for shared queues.

 

Event message data summary

Event type
Event name
topic
Authority events
Not authorized (type 1)
Not authorized (type 2)
Not authorized (type 3)
Not authorized (type 4)
"Not Authorized (type 1)"
"Not Authorized (type 2)"
"Not Authorized (type 3)"
"Not Authorized (type 4)"
Channel events
Channel activated
Channel auto-Definition Error
Channel auto-Definition OK
Channel conversion Error
Channel not Activated
Channel started
Channel stopped
Channel stopped by user
"Channel Activated"
"Channel Auto-definition Error"
"Channel Auto-definition OK"
"Channel Conversion Error"
"Channel Not Activated"
"Channel Started"
"Channel Stopped"
"Channel Stopped By User"
Configuration events
Create object
Change object
Delete object
Refresh object
"Create object (z/OS only)"
"Change object (z/OS only)"
"Delete object (z/OS only)"
"Refresh object (z/OS only)"
IMS Bridge events
Bridge started
Bridge stopped
"Bridge Started (z/OS only)"
"Bridge Stopped (z/OS only)"
Inhibit events
Get inhibited
Put inhibited
"Get Inhibited"
"Put Inhibited"
Local events
Alias base queue type error
Unknown alias base queue
Unknown object name
"Alias Base Queue Type Error"
"Unknown Alias Base Queue"
"Unknown Object Name"
Performance events
Queue depth high
Queue depth low
Queue full
Queue service interval high
Queue service interval OK
"Queue Depth High"
"Queue Depth Low"
"Queue Full"
"Queue Service Interval High"
"Queue Service Interval OK"
Remote events
Default transmission queue type error
Default transmission queue usage error
Queue type error
Remote queue name error
Transmission queue type error
Transmission queue usage error
Unknown default transmission queue
Unknown remote queue manager
Unknown transmission queue
"Default Transmission Queue Type Error"
"Default Transmission Queue Usage Error"
"Queue Type Error"
"Remote Queue Name Error"
"Transmission Queue Type Error"
"Transmission Queue Usage Error"
"Unknown Default Transmission Queue"
"Unknown Remote Queue Manager"
"Unknown Transmission Queue"
SSL events
Channel SSL error
"Channel SSL Error"
Start and stop


events

Queue manager active
Queue manager not active
"Queue Manager Active"
"Queue Manager Not Active"

 

WebSphere is a trademark of the IBM Corporation in the United States, other countries, or both.

 

IBM is a trademark of the IBM Corporation in the United States, other countries, or both.