Sun Java System Message Queue 4.1 Administration Guide

Chapter 6 Physical Destinations

A Message Queue message is routed to its consumer clients by way of a physical destination on a message broker. The broker manages the memory and persistent storage associated with the physical destination and configures its behavior. The broker also maintains a specialized physical destination, the dead message queue, whose properties differ somewhat from those of other destinations. This chapter describes how to use the Message Queue Command utility (imqcmd) to manage physical destinations.

In a broker cluster, you create a physical destination on one broker and the cluster propagates it to all the others. Because the brokers cooperate to route messages across the cluster, client applications can consume messages from destinations on any broker in the cluster. Only the broker to which a message was originally produced manages persistence and acknowledgment for that message.

This chapter covers the following topics:


Note –

For provider independence and portability, client applications typically use destination administered objects to interact with physical destinations. Chapter 7, Administered Objects describes how to configure such administered objects for use by client applications. For a general conceptual introduction to physical destinations, see the Message Queue Technical Overview.


Command Utility Subcommands for Physical Destination Management

The Message Queue Command utility (imqcmd) enables you to manage physical destinations interactively from the command line. See Chapter 13, Command Line Reference for general reference information about the syntax, subcommands, and options of the imqcmd command, andChapter 15, Physical Destination Property Reference for specific information on the configuration properties used to specify physical destination behavior.

Table 6–1 lists the imqcmd subcommands for physical destination management. For full reference information about these subcommands, see Table 13–6.

Table 6–1 Physical Destination Subcommands for the Command Utility

Subcommand 

Description 

create dst

Create physical destination 

destroy dst

Destroy physical destination 

pause dst

Pause message delivery for physical destination 

resume dst

Resume message delivery for physical destination 

purge dst

Purge all messages from physical destination 

compact dst

Compact physical destination 

update dst

Set physical destination properties 

list dst

List physical destinations 

query dst

List physical destination property values 

metrics dst

Display physical destination metrics 

Creating and Destroying Physical Destinations

The subcommand imqcmd create dst creates a new physical destination:

   imqcmd create dst  -t destType  -n destName
                      [ [-o property=value] … ]

You supply the destination type (q for a queue or t for a topic) and the name of the destination. The name must conform to the following rules:

For example, the following command creates a queue destination named XQueue:

   imqcmd create dst  -t q  -n XQueue

The imqcmd create dst command may also optionally include any property values you wish to set for the destination, specified with the -o option. For example, the following command creates a topic destination named hotTopic with a maximum message length of 5000 bytes:

   imqcmd create dst  -t t  -n hotTopic  -o maxBytesPerMsg=5000

See Chapter 15, Physical Destination Property Reference for reference information about the physical destination properties that can be set with this option. (For auto-created destinations, you set default property values in the broker’s instance configuration file; see Table 14–3 for information on these properties.)

To destroy a physical destination, use the imqcmd destroy dst subcommand:

   imqcmd destroy dest  -t destType  -n destName

This purges all messages at the specified destination and removes it from the broker; the operation is not reversible.

For example, the following command destroys the queue destination named curlyQueue:

   imqcmd destroy dest  -t q  -n curlyQueue  -u admin

Note –

You cannot destroy the dead message queue.


Pausing and Resuming a Physical Destination

Pausing a physical destination temporarily suspends the delivery of messages from producers to the destination, from the destination to consumers, or both. This can be useful, for instance, to prevent destinations from being overwhelmed when messages are being produced much faster than they are consumed. You must also pause a physical destination before compacting it (see Managing Physical Destination Disk Utilization).

To pause the delivery of messages to or from a physical destination, use the imqcmd pause dst subcommand:

   imqcmd pause dest  [-t destType  -n destName]
                      [-pst pauseType]

If you omit the destination type and name (-t and -n options), all physical destinations will be paused. The pause type (-pst) specifies what type of message delivery to pause:

PRODUCERS

Pause delivery from message producers to the destination

CONSUMERS

Pause delivery from the destination to message consumers

ALL

Pause all message delivery (both producers and consumers)

If no pause type is specified, all message delivery will be paused.

For example, the following command pauses delivery from message producers to the queue destination curlyQueue:

   imqcmd pause dst  -t q  -n curlyQueue  -pst PRODUCERS  -u admin

The following command pauses delivery to message consumers from the topic destination hotTopic:

   imqcmd pause dst  -t t  -n hotTopic  -pst CONSUMERS  -u admin

This command pauses all message delivery to and from all physical destinations:

   imqcmd pause dst  -u admin

Note –

In a broker cluster, since each broker in the cluster has its own instance of each physical destination, you must pause each such instance individually.


The imqcmd resume dst subcommand resumes delivery to a paused destination:

   imqcmd resume dest  [-t destType  -n destName]

For example, the following command resumes message delivery to the queue destination curlyQueue:

   imqcmd resume dst  -t q  -n curlyQueue  -u admin

If no destination type and name are specified, all destinations are resumed. This command resumes delivery to all physical destinations:

   imqcmd resume dst  -u admin

Purging a Physical Destination

Purging a physical destination deletes all messages it is currently holding. You might want to do this when a destination’s accumulated messages are taking up too much of the system’s resources, such as when a queue is receiving messages but has no registered consumers to which to deliver them, or when a topic’s durable subscribers remain inactive for long periods of time.

To purge a physical destination, use the imqcmd purge dst subcommand:

   imqcmd purge dst  -t destType  -n destName

For example, the following command purges all accumulated messages from the topic destination hotTopic:

   imqcmd purge dst  -t t  -n hotTopic  -u admin

Note –

In a broker cluster, since each broker in the cluster has its own instance of each physical destination, you must purge each such instance individually.



Tip –

When restarting a broker that has been shut down, you can use the Broker utility’s -reset messages option to clear out its stale messages: for example,

   imqbrokerd -reset messages  -u admin

This saves you the trouble of purging physical destinations after restarting the broker.


Updating Physical Destination Properties

The subcommand imqcmd update dst changes the values of specified properties of a physical destination:

   imqcmd update dst  -t destType  -n destName
                      -o property1=value1  [ [-o property2=value2] … ]

The properties to be updated can include any of those listed in Table 15–1 (with the exception of the isLocalOnly property, which cannot be changed once the destination has been created). For example, the following command changes the maxBytesPerMsg property of the queue destination curlyQueue to 1000 and the maxNumMsgs property to 2000:

imqcmd update dst  -t q  -n curlyQueue  -u admin
                   -o maxBytesPerMsg=1000
                   -o maxNumMsgs=2000

Note –

The type of a physical destination is not an updatable property; you cannot use the imqcmd update dst subcommand to change a queue to a topic or a topic to a queue.


Viewing Physical Destination Information

To list the physical destinations on a broker, use the imqcmd list dst subcommand:

   imqcmd list dst  -b hostName:portNumber  [-t destType]  [-tmp]

This lists all physical destinations on the broker identified by hostName and portNumber of the type (queue or topic) specified by destType. If the -t option is omitted, both queues and topics are listed. For example, the following command lists all physical destinations on the broker running on host myHost at port number 4545:

   imqcmd list dst  -b myHost:4545

Note –

The list of queue destinations always includes the dead message queue (mq.sys.dmq) in addition to any other queue destinations currently existing on the broker.


If you specify the -tmp option, temporary destinations are listed as well. These are destinations created by clients, normally for the purpose of receiving replies to messages sent to other clients.

The imqcmd query dst subcommand displays information about a single physical destination:

   imq query dst  -t destType  -n destName

For example, the following command displays information about the queue destination curlyQueue:

   imqcmd query dst  -t q  -n curlyQueue  -u admin

Example 6–1shows an example of the resulting output. You can use the imqcmd update dst subcommand (see Updating Physical Destination Properties) to change the value of any of the properties listed.


Example 6–1 Physical Destination Information Listing


------------------------------------
Destination Name    Destination Type
------------------------------------
curlyQueue              Queue

On the broker specified by:

-------------------------
Host         Primary Port
-------------------------
localhost    7676

Destination Name                      curlyQueue
Destination Type                      Queue
Destination State                     RUNNING
Created Administratively              true

Current Number of Messages            0
Current Total Message Bytes           0
Current Number of Producers           0
Current Number of Active Consumers    0
Current Number of Backup Consumers    0

Max Number of Messages                unlimited (-1)
Max Total Message Bytes               unlimited (-1)
Max Bytes per Message                 unlimited (-1)
Max Number of Producers               100
Max Number of Active Consumers        1
Max Number of Backup Consumers        0

Limit Behavior                        REJECT_NEWEST
Consumer Flow Limit                   1000
Is Local Destination                  false
Local Delivery is Preferred           false
Use Dead Message Queue                true


To display metric information about a physical destination, use the imqcmd metrics dst subcommand:

   imqcmd metrics dst   -t destType  -n destName
                       [-m metricType]
                       [-int interval]
                       [-msp numSamples]

The -m option specifies the type of metric information to display:

The -int and -msp options specify, respectively, the interval (in seconds) at which to display the metrics and the number of samples to display in the output. The default values are 5 seconds and an unlimited number of samples.

For example, the following command displays cumulative totals for messages and packets handled by the queue destination curlyQueue:

   imqcmd metrics dst  -t q  -n curlyQueue  -m ttl  -u admin

Example 6–2 shows an example of the resulting output.


Example 6–2 Physical Destination Metrics Listing


-----------------------------------------------------------------------------------
   Msgs        Msg Bytes          Msg Count         Total Msg Bytes (k)     Largest
 In   Out     In       Out    Current  Peak  Avg  Current   Peak     Avg    Msg (k)
-----------------------------------------------------------------------------------
3128  3066  1170102  1122340    128    409   29     46      145      10       < 1
4858  4225  1863159  1635458    144    201   33     53      181      42       < 1
2057  1763   820804   747200     84    377   16     71      122      79       < 1


For a more detailed description of the use of the Command utility to report physical destination metrics, see Physical Destination Metrics.

Managing Physical Destination Disk Utilization

Because of the way message storage is structured in a file-based persistent data store (see File-Based Persistence), disk space can become fragmented over time, resulting in inefficient utilization of the available resources. Message Queue’s Command utility (imqcmd) provides subcommands for monitoring disk utilization by physical destinations and for reclaiming unused disk space when utilization drops.

To monitor a physical destination’s disk utilization, use the imqcmd metrics dst subcommand:

   imqcmd metrics dst  -m dsk  -t destType  -n destMame

This displays the total number of bytes of disk space reserved for the destination’s use, the number of bytes currently in use to hold active messages, and the percentage of available space in use (the disk utilization ratio). For example, the following command displays disk utilization information for the queue destination curlyQueue:

   imqcmd metrics dst  -m dsk  -t q  -n curlyQueue  -u admin

Example 6–3 shows an example of the resulting output.


Example 6–3 Destination Disk Utilization Listing


--------------------------------------
Reserved   Used      Utilization Ratio
--------------------------------------
804096     675533    84
1793024    1636222   91
2544640    2243808   88


The disk utilization pattern depends on the characteristics of the messaging application using a particular physical destination. Depending on the flow of messages into and out of the destination and their relative size, the amount of disk space reserved might grow over time. If messages are produced at a higher rate than they are consumed, free records should generally be reused and the utilization ratio should be on the high side. By contrast, if the rate of message production is comparable to or lower than the consumption rate, the utilization ratio will likely be low.

As a rule, you want the reserved disk space to stabilize and the utilization ratio to remain high. If the system reaches a steady state in which the amount of reserved disk space remains more or less constant with utilization above 75%, there is generally no need to reclaim unused disk space. If the reserved space stabilizes at a utilization rate below 50%, you can use the imqcmd compact dst subcommand to reclaim the disk space occupied by free records:

   compact dst  [-t destType  -n destName]

This compacts the file-based data store for the designated physical destination. If no destination type and name are specified, all physical destinations are compacted.

You must pause a destination (with the imqcmd pause subcommand) before compacting it, and resume it (with imqcmd resume) afterward (see Pausing and Resuming a Physical Destination):

   imqcmd pause dst    -t q  -n curlyQueue  -u admin
   imqcmd compact dst  -t q  -n curlyQueue  -u admin
   imqcmd resume dst   -t q  -n curlyQueue  -u admin

Tip –

If a destination’s reserved disk space continues to increase over time, try reconfiguring its maxNumMsgs, maxBytesPerMsg, maxTotalMsgBytes, and limitBehavior properties (see Physical Destination Properties).


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 of 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. This can provide information that is useful for troubleshooting the system.

Managing the Dead Message Queue

The physical destination configuration property useDMQ controls a destination’s use of the dead message queue. Physical destinations are configured to use the dead message queue by default; to disable a destination from using it, set the destination’s useDMQ property to false:

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

You can enable or disable the use of the dead message queue for all auto-created physical destinations on a broker by setting the broker’s imq.autocreate.destination.useDMQ broker property:

   imqcmd update bkr  -o imq.autocreate.destination.useDMQ=false

You can manage the dead message queue with the Message Queue Command utility (imqcmd) just as you manage other queues, but 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–2, default values for the dead message queue’s configuration properties sometimes differ from those of ordinary queues.

Table 6–2 Dead Message Queue Treatment of Physical Destination Properties

Property 

Variant Treatment by Dead Message Queue 

maxNumMsgs

Default value is 1000, rather than -1 (unlimited) as for ordinary queues.

maxTotalMsgBytes

Default value is 10m (10 megabytes), rather than -1 (unlimited) as for ordinary queues.

limitBehavior

Default value is REMOVE_OLDEST, rather than REJECT_NEWEST as for ordinary queues.

Flow control is not supported for the dead message queue.  

maxNumProducers

Does not apply to the dead message queue.  

isLocalOnly

Permanently set to false in broker clusters; the dead message queue in a cluster is always a global physical destination.

localDeliveryPreferred

Does not apply to the dead message queue.  


Tip –

By default, the dead message queue stores entire messages. If you do not plan to restore dead messages, you can reduce the size of the dead message queue by setting the broker’s imq.destination.DMQ.truncateBody property to true:

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

This will discard the body of all messages and retain only the headers and property data.


Enabling Dead Message Logging

The broker configuration property logDeadMsgs controls the logging of events related to the dead message queue. When dead message logging is enabled, the broker will log the following events:

Dead message logging is disabled by default. The following command enables it:

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

Note –

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.