Using the Dead Message Queue

The dead message queue, mq.sys.dmq, is a system-created physical destination that holds the dead messages of a broker and its other physical destinations. The dead message queue is a tool for monitoring, tuning system efficiency, and troubleshooting. For a definition of the term “dead message” and a more detailed introduction to the dead message queue, see the Message Queue Technical Overview.

The broker automatically creates a dead message queue when it starts. The broker places messages on the queue if it cannot process them, or if their time-to-live has expired. In addition, other physical destinations can use the dead message queue to hold discarded messages. Use of the dead message queue provides information that is useful for troubleshooting the system.

Configuring Use of the Dead Message Queue

By default, a physical destination is configured to use the dead message queue. You can disable a physical destination from using the dead message queue, or enable it to do so, by setting the physical destination property useDMQ .

The following example creates a queue called myDist that uses the dead message queue by default:

imqcmd create dst -n myDist -t q

The following example disables use of the dead message queue for the same queue:

imqcmd update dst -n myDist -t q -o useDMQ=false

You can enable all auto-created physical destinations on a broker to use the dead message queue, or disable them from doing so, by setting the imq.autocreate.destination.useDMQ broker property.

Managing the Dead Message Queue

You can use the Message Queue Command utility (imqcmd) to manage the dead message queue as you manage other queues, with some differences. For example, because the dead message queue is system-created, you cannot create, pause, or destroy it. Also, as shown in Table 6–3, default values for the dead message queue sometimes differ from those of normal queues.

Dead Message Queue Properties

You configure the dead message queue as you configure other queues, but certain physical destination properties do not apply or have different default values. Table 6–3 lists queue properties that the dead message queue handles in a unique way.

Table 6–3 Dead Message Queue Treatment of Standard Physical Destination Properties

Property	Unique Treatment by Dead Message Queue
limitBehavior	The default value for the dead message queue is REMOVE_OLDEST. (The default value for other queues is REJECT_NEWEST.) Flow control is not supported on the dead message queue.
localDeliveryPreferred	Does not apply to the dead message queue.
maxNumMsgs	The default value for the dead message queue is 1000. The default value for other queues is -1 (unlimited).
maxNumProducers	Does not apply to the dead message queue.
maxTotalMsgBytes	The default value for the dead message queue is 10 MB. The default value for other queues is -1 (unlimited).
isLocalOnly	In a broker cluster, a dead message queue is always a global physical destination and this property is permanently set to false.

Message Contents

A broker can place an entire message on the dead message queue, or it can discard the message body contents, retaining just the header and property data. By default, the dead message queue stores entire messages.

If you want to reduce the size of the dead message queue and if you do not plan to restore dead messages, consider setting the imq.destination.DMQ.truncateBody broker property to true:

imqcmd update bkr -o imq.destination.DMQ.truncateBody=true

This will discard the message body and retain only the headers and property data.

Enabling Dead Message Logging

Dead message logging is disabled by default. Enabling dead message logging allows the broker to log the following events:

• The broker moves a message to the dead message queue

• The broker discards a message from the dead message queue and from any physical destination that does not use the dead message queue

• A physical destination reaches its limits

The following command enables dead message logging:

imqcmd update bkr -o imq.destination.logDeadMsgs=true

Dead message logging applies to all physical destinations that use the dead message queue. You cannot enable or disable logging for an individual physical destination.