WMQ policies

Policy and Event Pack Content

A reminder that base MQ policies and events are already installed by default.   In addition, Policy and Event Packs are provided for MQ Accounting and Statistics.

Some background information on the MQ Accounting and Statistics messages is provided here to guide you in the use of these Policy and Event Packs. Of course, for the full details on MQ Accounting and Statistics messages, see the IBM MQ documentation. Fundamentally, these messages are written to a pair of queues (one for Accounting and another for Statistics) on each appropriately configured queue manager. The queue manager writes one group of such messages to the queue per interval (ACCTINT for Accounting Messages and STATINT for Statistics messages). There are two separate types of accounting messages (ACCTMQI and ACCTQ) and three separate types of Statistics messages (STATMQI, STATQ, and STATCHL) that can be individually enabled or disabled. If the ProcessMQAcctMessages Extension Preference is set, then the MVMM MQ Monitoring Extension (QPMON) will read any messages from that queue and publish the information contained in those messages as attributes of the queue manager and local queue objects. Similarly, if the ProcessMQStatMessages Extension Preference is set, QPMON will read any messages written by MQ to the statistics queue and publish the values as attributes of the queue manager, queues, or channels (remember the third type of Statistics message, STATCHL).

IMPORTANT NOTE: Accounting and Statistics Messages provide a great deal of useful information on the performance and behavior of MQ applications and can be very useful. However, the VERY LARGE number of attributes introduced by this processing has a cost. Implementation of this function (either through these Policy and Event Packs or on your own) will noticeably increase the memory footprint of QPMON. To prevent this memory cost from applying to agents where the function is not enabled, QPMON does not add these attributes until the appropriate preference is set and QPMON is restarted. Thus, it is necessary to restart QPMON after applying these Policy and Event Packs before they take effect. Similarly, if you wish to remove these Policy and Event Packs, a restart of QPMON will be required before the resources are freed.

The Policy and Event Packs each contain one History Templates (MQAccounting, MQStatistics, or MQAccounting_Plus_Statistics) that collects the appropriate historical data for reporting and trending and enables the flow of this data to the ProactiveNet Service (if that service is configured). In addition, they contain several hundred event triggers to handle event conditions around the accounting and statistics data. Event templates combining each of these triggers with the BEM_Generic, EMail_Generic, and LogToFile_Generic actions are supplied.  You can, of course, use these event and history templates directly in your own policies or copy and customize them as usual. The Policy and Event Packs also supply Policy Definitions to assemble these into blocks that can be simply applied. As usual for Policy and Event Packs, three levels of Policy are supplied. The _Basic policy collects history but does no event association. The _Standard_ActionType policies follows good general practice and is the easiest way to get started. The _ALL_ActionType policies implement all events and history supplied by the event packs. Note that these _ALL policies are intended for examination in a sandbox environment to remove any events that do not apply.

MQ Accounting - WMQ_Acct_EventPack.zip

History Templates

MQAccounting:ComMQSoftwareWebSphereMQLocalQueue
MQAccounting:ComMQSoftwareWebSphereMQQueueManager

Event Triggers and Templates

There are many triggers and templates to obtain a list of the triggers and templates contained in this zip use the following command being careful to use the -n option to prevent an actual import. It is recommended you redirect the output to a file and use an editor to search for desired triggers or templates. Both the triggers and templates follow a naming convention of WMQ_<object type>_Acct_<trigger description>_<action>.

mqsimport -n --event-trigger ".*" --event-template ".*" Samples/EventPacks/WMQ/WMQ_AcctStat_EventPack.zip -p BMCSOFTWARE SA

Agent Policies

• WMQ_Agents_Acct_Basic
• WMQ_Agents_Acct_Standard_BEM
• WMQ_Agents_Acct_Standard_EMail
• WMQ_Agents_Acct_Standard_LogToFile
• WMQ_Agents_Acct_ALL_BEM
• WMQ_Agents_Acct_ALL_EMail
• WMQ_Agents_Acct_ALL_LogToFile

Note that the child policy artifacts (Expressions, Policy Actions, Object Policies, and Object Policy Groups) are not listed here but are automatically imported with their parent Agent Policy.

MQ Statistics - WMQ_Stat_EventPack.zip

History Templates

• MQStatistics:ComMQSoftwareWebSphereMQClusterReceiverChannel
• MQStatistics:ComMQSoftwareWebSphereMQClusterSenderChannel
• MQStatistics:ComMQSoftwareWebSphereMQLocalQueue
• MQStatistics:ComMQSoftwareWebSphereMQQueueManager
• MQStatistics:ComMQSoftwareWebSphereMQReceiverChannel
• MQStatistics:ComMQSoftwareWebSphereMQRequesterChannel
• MQStatistics:ComMQSoftwareWebSphereMQSenderChannel
• MQStatistics:ComMQSoftwareWebSphereMQServerChannel

Event Triggers

There are many triggers and templates, to obtain a list of the triggers and templates contained in this zip use the following command being careful to use the -n option to prevent an actual import.   It is recommended you redirect the output to a file and use an editor to search for desired triggers or templates.   Both the triggers and templates follow a naming convention of WMQ_<object type>_Stat_<trigger description>_<action>.

mqsimport -n --exclude-associations --event-trigger ".*" --event-template ".*" Samples/EventPacks/WMQ/WMQ_AcctStat_EventPack.zip -p BMCSOFTWARE SA

Agent Policies

• WMQ_Agents_Stat_Basic
• WMQ_Agents_Stat_Standard_BEM
• WMQ_Agents_Stat_Standard_EMail
• WMQ_Agents_Stat_Standard_LogToFile
• WMQ_Agents_Stat_ALL_BEM
• WMQ_Agents_Stat_ALL_EMail
• WMQ_Agents_Stat_ALL_LogToFile

Note that the child policy artifacts (Expressions, Policy Actions, Object Policies, and Object Policy Groups) are not listed here but are automatically imported with their parent Agent Policy.

MQ Accounting and MQ Statistics - WMQ_acctStat_EventPack.zip

HistoryTemplates

• MQStatistics:ComMQSoftwareWebSphereMQClusterReceiverChannel
• MQStatistics:ComMQSoftwareWebSphereMQClusterSenderChannel
• MQAccounting_Plus_Statistics:ComMQSoftwareWebSphereMQLocalQueue
• MQAccounting_Plus_Statistics:ComMQSoftwareWebSphereMQQueueManager
• MQStatistics:ComMQSoftwareWebSphereMQReceiverChannel
• MQStatistics:ComMQSoftwareWebSphereMQRequesterChannel
• MQStatistics:ComMQSoftwareWebSphereMQSenderChannel
• MQStatistics:ComMQSoftwareWebSphereMQServerChannel

Event Triggers and Event Templates

All From Both WMQ_Acct_EventPack plus WMQ_Stat_EventPack

There are many triggers and templates, to obtain a list of the triggers and templates contained in this zip use the following command being careful to use the -n option to prevent an actual import.   It is recommended you redirect the output to a file and use an editor to search for desired triggers or templates.   Both the triggers and templates follow a naming convention of WMQ_<object type>_Acct|Stat_<trigger description>_<action>.

mqsimport -n --exclude-associations --event-trigger ".*" --event-template ".*" Samples/EventPacks/WMQ/WMQ_AcctStat_EventPack.zip -p BMCSOFTWARE SA

Agent Policies

• WMQ_Agents_AcctPlusStat_Basic
• WMQ_Agents_AcctPlusStat_Standard_BEM
• WMQ_Agents_AcctPlusStat_Standard_EMail
• WMQ_Agents_AcctPlusStat_Standard_LogToFile
• WMQ_Agents_AcctPlusStat_ALL_BEM
• WMQ_Agents_AcctPlusStat_ALL_EMail
• WMQ_Agents_AcctPlusStat_ALL_LogToFile

Note that the child policy artifacts (Expressions, Policy Actions, Object Policies, and Object Policy Groups) are not listed here but are automatically imported with their parent Agent Policy.

Using the Policy and Event Pack

MQ Accounting and MQ Statisics are two distinct functions, but some of the information overlaps between them. Thus, you should consider which one to use. It is recommended that you consult the IBM documentation for details in making this decision. 

If you choose to use Accounting only, then enable this as follows:

At a command prompt in your MVMM Server Home Directory, run

where SA is a MVMM Administrative UserId. You will be prompted for the password. Note that you must use the / or \ as appropriate to your MVMM server OS.
When this is complete, the artifacts will appear in your Middleware Monitor Console.

If you choose to use Statistics only, then enable this as follows:

At a command prompt in your MVMM Server Home Directory, run

where SA is a MVMM Administrative User Id. You will be prompted for the password. Note that you must use the / or \ as appropriate to your MVMM server OS.
When this is complete, the artifacts will appear in your Middleware Monitor Console.

If you choose to use both Accounting and Statistics, then enable this as follows:

At a command prompt in your MVMM Server Home Directory, run

where SA is a MVMM Administrative User Id. You will be prompted for the password. Note that you must use the / or \ as appropriate to your MVMM server OS.
When this is complete, the artifacts will appear in your Middleware Monitor Console.

WMQ_Agents_Minimal

As is typical for Minimal level supplied policies, the WMQ_Agents_Minimal Agent Policy registers very limited monitoring. 

In general, you should use this policy when you wish to control your monitoring manually by selecting individual objects for monitoring. 

WMQ_Agents_Minimal registers the BMM agent for history collection using the SAMPLE history template and applies the Basic BMM Extension Object Policy (see BMM (Self Monitoring) Policies). It then has one main Object Policy Group (WMQ_POLICY_Minimal, see below).

As shown above, this Minimal Policy directly applies a Basic Object Policy to Queue Managers (selecting them for monitoring and registering them for history collection with the SAMPLE history template. It also contains one nested Object Policy Group (WMQ_SYSTEMQUEUES_Basic) that selects the core system queues (SYSTEM.ADMIN.COMMAND.QUEUE, SYSTEM.CHANNEL.INITQ, SYSTEM.CLUSTER.TRANSMIT.QUEUE, SYSTEM.DEAD.LETTER.QUEUE, and SYSTEM.DEFAULT.INITIATION.QUEUE) for monitoring and registers them for history collection using the SAMPLE history template.

WMQ_Agents_Basic

The WMQ_Agents_Basic Agent Policy applies the same actions to BMM agents and extensions and to MQ queue managers and System Queues as the Minimal level. 

However, it adds Basic level Object Policies for Local Queues, Channels (all types), and Topics. For each of these, it selects the Non-System objects for monitoring and registers them for history using the SAMPLE history template. You should use this policy when you want to ensure that all of your objects are monitored, but you want to configure events on your own.

WMQ_Agents_Standard_EventTarget

The Standard level of monitoring is, as always, the general recommendation for normal systems. 

Because the Standard level does Events as well as selection for monitoring and history, you need to choose the variant that matches the target (TrueSight Operations=BEM, EMail, or LogToFile) that you want to receive your events. Note that some configuration is necessary (see Policies-and-Event-Packs-overview) to connect to your Event Manager, email server, or log file. As is normal for Standard level policies, the WMQ_Agents_Standard_EventTarget policies apply the Standard level of monitoring against the BMM agents and extensions (see BMM (Self Monitoring) Policies) and then provide a single main Object Policy Group (WMQ_POLICY_Standard_EventTarget) with nested object Polices and Groups.

WMQ_POLICY_Standard_EventTarget directly applies Object Policies to all Queue Managers and Transmission Queues (Local Queues with their USAGE property set to XMIT). It is beyond the scope of this document to describe all of the event actions applied on these individual objects. In addition, WMQ_POLICY_Standard_EventTarget applies nested Object Policy Groups to Channels, Local Queues, Topics, and MQ Event Messages. Note that there are multiple Object Policy Groups for Channels and Local Queues that apply to different subsets of those objects.

MQ Channels can be broken down into two types: those that should always be running and those for which it is acceptable to be Inactive (although a status Stopped, Retrying, etc. is still a problem). Each of these groups can apply to all channel types so these Object Policy Groups contain nested Object Policies for each channel type (Sender, Receiver, Cluster Sender, Telemetry, Server Connection, ...). All non-System channels are covered by the WMQ_Channels_Standard_BEM. In addition to selection for monitoring and history collection, alerts are configured if they are STOPPED or (where appropriate by type) RETRYING and escalating alerts are configured for when the Short and Long Retry Counts are exhausted. For those channels with a Channel Description containing the string "BMM:ALWAYSRUNNING", additional alerts are configured for when the channel is in any state except RUNNING. Note that to get the AlwaysRunning policy to apply, you must modify the MQ Channel itself to set the Description (or modify the Expression on the Object Policy).

MQ Local Queues are more complex. As with Channels, WMQ_LocalQ_Standard_EventTarget applies a standard set of alerts to all non-SYSTEM Local Queues including selection for monitoring, history collection, and alerts for Queue Full, Queue over the High depth threshold, queue projected to be full in less than N Minutes, Queue Put or Get Disabled, and a high number of uncommitted messages on the queue.

Beyond that, there are several special groups of queues that warrant special alerts.

The first of these is the Application Error Queue. The WMQ_LocalQ_AppErrorQ_EventTarget Object Policy applies by default to queues whose name ends in FAIL, FAILURE, BACKOUT, BO, or ERROR. Note that you can change that Expression to match your naming convention. For these queues, an alert is added whenever there is a message on one of these queues. WMQ_LocalQ_DLQs_EventTarget is handled very much the same. By default, it applies to the SYSTEM.DEAD.LETTER.QUEUE only (although as with App Error Queues, you can change the Expression). 

The next groups of queues are Triggered Queues (those with the TRIGGER attribute) and Initiation Queues. Since those queues should have active readers or trigger those readers to start very quickly when messages arrive, these queues have additional alerts for MsgsNotProcessed (QDepth > 0 and MsgDeqRate = 0) and Oldest Message Age greater than a threshold (see Customizing-thresholds). Note that the Initiation Queues policy is applied to SYSTEM.DEFAULT.INITIATION.QUEUE by default but you can change that Expression to include custom initiation queues that you use. Some of your own application local queues may not be triggered, but it may be equally important that there always be a reader against them. The WMQ_LocalQ_OnlineQs_EventTarget Obejct Policy Group is meant to handle this. It applies the oldest message age and messages no processed alerts to all Local Queues containing the string "BMM:ONLINE" in their Description. (Note that you need to either modify the Local Queue Description or the Expression for this to match any queues). 

There are some application local queues that are intended to hold batches of messages for applications that run on a periodic basis. It is acceptable for such queues to have unprocessed messages, perhaps for long periods of time, but you typically want to alert when such queues are full or breach a threshold. Because this threshold might be different from standard queues, this applies specially to Local Queues with a description containing the string "BMM:BATCH".

Finally, a special set of Object Polices are applied to the key system queues (SYSTEM.ADMIN.COMMAND.QUEUE, SYSTEM.CHANNEL.INITQ, SYSTEM.CLUSTER.TRANSMIT.QUEUE, SYSTEM.DEAD.LETTER.QUEUE, and SYSTEM.DEFAULT.INITIATION.QUEUE).

Topics are much more straightforward than Queues and Channels. The Standard level WMQ policies apply to all non-SYSTEM Topics. These topics are selected for monitoring and history and are registered for alerts when they are pub or sub disabled and when they have no subscribers (as that could lead to messages going nowhere).

Finally, if MQ Event Messages are enabled on the queue manager (for example AUTHOREV(ENABLED) for MQ Authority Events), this is detected by the Expressions in the Object Policies in the MQEventQProcessing Object Policy Group. In that case, the BMM agent policy is automatically set to enable BMM processing of those messages and alerts are registered to handle and forward all event messages of that type to the selected Event Target. For example, if a queue manager has LOCALEV(ENABLED), the ProcessMQQMgrEvents Extension Preference is automatically set to True for that MQ monitoring extension and the UnknownObjectName, UnknownAliasBaseQ, and AliasBaseQTypeError Event Templates are registered with that Queue Manager.

WMQ_Agents_ALL_EventTarget

The WMQ_Agents_ALL_EventTarget Agent Policy registers a large number of additional events for every object type.

In addition, it registers events (e.g. Put Disabled) against Alias and Remote queues. This policy is intended to illustrate the scope of what is possible. It is strongly recommended that you do not enable this policy directly in a production environment.  Instead, you can enable it in a well-controlled testing environment to experiment with policies and to select the event templates that are relevant to your specific environment before creating a customized policy that removes the associations that you do not want.

Where to go from here

Now that you have imported the Policy and Event Pack for this technology, go to Getting started with policies to enable them.