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:
- Gets the message from the queue.
- Processes the message to extract the event data.
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:
- 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
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.