|
| |
| Sun Java System Message Queue 3.5 SP1 Administration Guide | |
Chapter 6
Broker and Application ManagementThis chapter explains how to perform tasks related to managing the broker and the services it provides. Some of these tasks are independent of any particular client application. These include:
Other broker tasks are performed on behalf of specific applications; these include managing physical destinations, durable subscriptions, and transactions:
- Message Queue messages are routed to their receivers or subscribers by way of broker destinations. You are responsible for creating these destinations on the broker.
- Message Queue allocates and maintains resources for durable subscribers even when clients that have durable subscriptions become inactive. You use the Message Queue Command tool to get information about durable subscriptions and to destroy durable subscriptions or purge their messages in order to save Message Queue resources.
- Message Queue transactions and distributed transactions are tracked by a broker. You might need to manually commit or roll back transactions if a failure takes place.
This chapter explains how you use the Command utility (imqcmd) to perform all these tasks. You can accomplish a number of these same tasks by using the Administration Console, the graphical interface to the Message Queue message server. For more information, see Chapter 4, "Administration Console Tutorial."
Command UtilityThe Command utility allows you to manage the broker and the services it provides. This section describes the basic imqcmd command syntax, provides a listing of subcommands, and summarizes imqcmd options. Subsequent sections explain how you use these commands to accomplish specific tasks.
Syntax of the imqcmd Command
The general syntax of the imqcmd command is as follows:
imqcmd subcommand argument [options]
imqcmd -h|H
imqcmd -vNote that if you specify the -v, -h, or -H options, no subcommands specified on the command line are executed. For example, if you enter the following command, version information is displayed but the restart subcommand is not executed.
imqcmd restart bkr -v
imqcmd Subcommands
The Command utility (imqcmd) includes the subcommands listed in Table 6-1: The subcommands are described in more detail in the task-oriented sections of this chapter.
Summary of imqcmd Options
Table 6-2 lists the options to the imqcmd command. For a discussion of their use, see the following task-based sections.
Table 6-2 imqcmd Options
Option
Description
-b hostName:port
Specifies the name of the broker’s host and its port number. The default value is localhost:7676.
To specify port only: -b :7878
To specify name only: -b somehost-c clientID
Specifies the ID of the durable subscriber to a topic. See "Managing Durable Subscriptions".
-d destinationName
Specifies the name of the topic. Used with the list dur and destroy dur subcommands. See "Managing Durable Subscriptions".
-f
Performs action without user confirmation.
-h
Displays usage help. Nothing else on the command line is executed.
-H
Displays usage help, attribute list, and examples. Nothing else on the command line is executed.
-int interval
Specifies the interval, in seconds, at which the metrics bkr, metrics dst, and metrics svc subcommands display metrics output.
-javahome path
Specifies an alternate Java 2 compatible runtime to use (default is to use the runtime on the system or the runtime bundled with Message Queue).
-m metricType
Specifies the type of metric information to display. Use this option with the metrics dst, metrics svc, or metrics bkr subcommand. The value of metricType depends on whether the metrics are generated for a destination, a service, or a broker.
-msp numSamples
Specifies the number of metric samples the metrics bkr, metrics dst, and metrics svc subcommands display in their metrics output.
-n argumentName
Specifies the name of the subcommand argument. Depending on the subcommand, this might be the name of a service, a physical destination, a durable subscription, a connection ID, or a transaction ID.
-o attribute=value
Specifies the value of an attribute. Depending on the subcommand argument, this might be the attribute of a broker (see "Managing a Broker"), service (see "Managing Connection Services"), or destination (see "Managing Destinations").
-p password
Specifies your (the administrator’s) password. If you omit this value, you will be prompted for it.
-pst pauseType
Specifies whether producers, consumers, or both are paused when pausing a destination. See "Managing Destinations".
-rtm timeout
Specifies the initial (retry) timeout period (in seconds) of an imqcmd subcommand. The timeout is the length of time the imqcmd subcommand will wait after making a request to the broker. Each subsequent retry of the subcommand will use a timeout value that is a multiple of the initial timeout period. Default: 10
-rtr numRetries
Specifies the number of retries attempted after an imqcmd subcommand first times out. Default: 5
-s
Silent mode. No output will be displayed.
-secure
Specifies a secure administration connection to the broker using the ssladmin connection service (see "Step 4. Configuring and Running SSL-based Clients").
-svn serviceName
Specifies the service for which connections are listed. See "Getting Connection Information".
-t destType
Specifies the type of a destination: t (topic) or q (queue). See "Managing Destinations".
-tmp
Displays temporary destinations. See Table 6-9.
-u userName
Specifies your (the administrator’s) name. If you omit this value, you will be prompted for it.
-v
Displays version information. Nothing else on the command line is executed.
You must specify the options for host name and port number (-b), user name (-u), password (-p), and secure connection (-secure) each time you issue a imqcmd subcommand. If you don’t specify the host name and port number, it uses the default values. If you don’t specify user name and password information, you will be prompted for them. If you don’t specify -secure, then the connection will not be secure.
Note
To be able to use the -secure option, you must first set up and enable the ssladmin service on the target broker instance, as described in "Setting Up an SSL-based Service Over TCP/IP".
Using imqcmd Commands
In order to use imqcmd commands to manage the broker, you must do the following:
See "Starting a Broker". You can use the Command utility only to administer brokers that are already running; you cannot use it to start a broker.
- Specify the target broker using the -b option unless the broker is running on the local host, on port 7676.
- Specify the proper administrator user name and password. If you do not do this, you will be prompted for it. Either way, be aware that every operation you perform using imqcmd will be authenticated against a user repository. For more information, see "Authenticating Users".
When you install Message Queue, a default flat-file user repository is installed. The repository is shipped with two entries: one for an admin user and one for a guest user. These entries allow you to connect to the broker instance without doing any additional work. For example, if you are just testing Message Queue, you can run the imqcmd utility using the default user name and password (admin/admin).
If you are setting up a production system, you will need to do some additional work to authenticate and authorize administrative users (see Chapter 8, "Managing Security"). In particular, you need to make entries in the Message Queue user repository (see "Using a Flat-File User Repository"). You also have the option of using an LDAP directory server for your user repository (see "Using an LDAP Server for a User Repository").
Example imqcmd Usage
The following examples illustrate the use of the imqcmd command:
- To list the properties of the broker running on localhost at port 7676:
imqcmd query bkr -u admin -p admin
- To list the properties of the broker running on myserver at port 1564; the user’s name is alladin, the user’s password is abracadabra.
imqcmd query bkr -b myserver:1564 -u alladin -p abracadabra
Managing a BrokerThe Command utility includes subcommands that you can use to perform the following broker management tasks:
To manage connection services for a broker, see "Managing Connection Services". To manage broker destinations, see "Managing Destinations"
Table 6-3 lists the imqcmd subcommands used to manage brokers. If no host name or port is specified, the default (localhost:7676)is assumed.
Table 6-3 imqcmd Subcommands Used to Manage a Broker
Subcommand Syntax
Description
metrics bkr [-b hostName:port]
[-m metricType]
[-int interval]
[-msp numSamples]Displays broker metrics for the default broker or a broker at the specified host and port.
Use the -m option to specify the type of metric to display:
ttl Displays metrics on messages and packets flowing into and out of the broker. (default metric type)
rts Displays metrics on rate of flow of messages and packets into and out of the broker (per second).
cxn Displays connections, virtual memory heap, and threads.
Use the -int option to specify the interval (in seconds) at which to display the metrics. The default is 5 seconds.
Use the -msp option to specify the number of samples displayed in the output. The default is an unlimited number (infinite).
pause bkr [-b hostName:port]
Pauses the default broker or a broker at the specified host and port. See "Pausing and Resuming a Broker".
query bkr -b hostName:port
Lists the current settings of properties of the default broker or a broker at the specified host and port. Also shows the list of running brokers (in a multi-broker cluster) that are connected to the specified broker.
reload cls
Applies only to broker clusters. Forces all the brokers in a cluster to reload the imq.cluster.brokerlist property and update cluster information. See "Adding Brokers to a Cluster" for more information.
restart bkr [-b hostName:port]
Shuts down and restart the default broker or a broker at the specified host and port.
Note that this command restarts the broker using the options specified when the broker was first started. If you want different options to be in effect, you must shutdown the broker and then start it again, specifying the options you want.
resume bkr [-b hostName:port]
Resumes the default broker or a broker at the specified host and port.
shutdown bkr [-b hostName:port]
Shuts down the default broker or a broker at the specified host and port.
update bkr [-b hostName:port]
-o attribute=value
[-o attribute=value1]…Changes the specified attributes for the default broker or a broker at the specified host and port.
Remember that you must specify the broker host name and port number when using any of the subcommands listed in Table 6-3 unless you are targeting the broker running on localhost at port 7676
Displaying Broker Information
To query and display information about a single broker, use the query bkr subcommand. For example:
imqcmd query bkr -u admin -p admin
This command produces output like the following:
Updating Broker Properties
You can use the update bkr subcommand to update any of the broker properties listed in Table 6-4. Note that updates to the broker are automatically written to the broker’s instance configuration file.
Table 6-4 Broker Properties Updated by imqcmd
Property
Reference
imq.autocreate.queue
imq.autocreate.topic
imq.autocreate.queue.maxNumActiveConsumers
imq.autocreate.queue.maxNumBackupConsumers
imq.cluster.url
imq.log.level
imq.log.file.rolloversecs
imq.log.file.rolloverbytes
imq.system.max_count
imq.system.max_size
imq.message.max_size
imq.portmapper.port
For example, the following command turns off the auto-creation of queue destinations:
imqcmd update bkr -o “imq.autocreate.queue=false”
-u admin -p adminControlling the Broker’s State
After you start the broker, you can use the following imqcmd subcommands to control the state of the broker.
Pausing and Resuming a Broker
However, pausing a broker does not suspend the admin connection service, letting you perform administration tasks needed to regulate the flow of messages to the broker. For example, if a particular destination is bombarded with messages, you can pause the broker and take any of the following actions that might help you fix the problem: trace the source of the messages, limit the size of the destination, or destroy the destination.
Pausing a broker also does not suspend the cluster connection service. However message delivery within a cluster depend on the delivery functions performed by the different brokers in the cluster.
The following command pauses the broker running on myhost at port 1588.
(You can also pause individual connection services—see "Pausing and Resuming a Connection Service"—as well as individual destinations—see "Pausing and Resuming Destinations")
Shutting Down and Restarting a Broker
- Shutting down the broker. Shutting down the broker terminates the broker process. This is a graceful termination: the broker stops accepting new connections and messages, it completes delivery of existing messages, and it terminates the broker process. The following command shuts down the broker running on ctrlsrv at port 1572
- Restarting the broker. Shuts down and restarts the broker. The following command restarts the broker running on localhost at port 7676:
Displaying Broker Metrics
To display metrics information about a broker, use the metrics bkr subcommand. For example, to get the rate of message flow into and out of the broker at ten second intervals:
imqcmd metrics bkr -m rts -int 10 -u admin -p admin
This command produces output like the following:
--------------------------------------------------------
Msgs/sec Msg Bytes/sec Pkts/sec Pkt Bytes/sec
In Out In Out In Out In Out
--------------------------------------------------------
0 0 27 56 0 0 38 66
10 0 7365 56 10 10 7457 1132
0 0 27 56 0 0 38 73
0 10 27 7402 10 20 1400 8459
0 0 27 56 0 0 38 73
For a more detailed description of the use of imqcmd to report broker metrics, see "Monitoring Tools".
Managing Connection ServicesThe Command utility includes subcommands that allow you to perform the following connection service management tasks:
For an overview of Message Queue connection services, see "Connection Services".
Table 6-5 lists the imqcmd subcommands used to manage connection services. If no host name or port is specified, the default (localhost:7676)is assumed.
Table 6-5 imqcmd Subcommands Used to Manage Connection Services
Subcommand Syntax
Description
list svc [-b hostName:port]
Lists all connection services on the default broker or on a broker at the specified host and port.
metrics svc -n serviceName
[-b hostName:port]
[-m metricType]
[-int interval]
[-msp numSamples]Displays metrics for the specified service on the default broker or on a broker at the specified host and port.
Use the -m option to specify the type of metric to display:
ttl Displays metrics on messages and packets flowing into and out of the broker by way of the specified service. (default metric type)
rts Displays metrics on rate of flow of messages and packets into and out of the broker (per second) by way of the specified service.
cxn Displays connections, virtual memory heap, and threads.
Use the -int option to specify the interval (in seconds) at which to display the metrics. The default is 5 seconds.
Use the -msp option to specify the number of samples displayed in the output. The default is an unlimited number (infinite).
pause svc -n serviceName
[-b hostName:port]Pauses the specified service running on the default broker or on a broker at the specified host and port. You cannot pause the admin service.
query svc -n serviceName
[-b hostName:port]Displays information about the specified service running on the default broker or on a broker at the specified host and port.
resume svc -n serviceName
[-b hostName:port]Resumes the specified service running on the default broker or on a broker at the specified host and port.
update svc -n serviceName
[-b hostName:port]
-o attribute=value
[-o attribute=value1]…Updates the specified attribute of the specified service running on the default broker or on a broker at the specified host and port. For a description of service attributes, see Table 6-7.
A broker supports connections from both application clients and administration clients. The connection services currently available from a Message Queue broker are shown in Table 6-6. The values in the Service Name column are the values you use to specify a service name for the -n option. As shown in the table, each service is specified by the service type it uses—NORMAL (application clients) or ADMIN (administration clients)—and an underlying transport layer.
Table 6-6 Connection Services Supported by a Broker
Service Name
Service Type
Protocol Type
jms
NORMAL
tcp
ssljms (Enterprise Edition)
NORMAL
tls (SSL-based security)
httpjms (Enterprise Edition)
NORMAL
http
httpsjms (Enterprise Edition)
NORMAL
https (SSL-based security)
admin
ADMIN
tcp
ssladmin (Enterprise Edition)
ADMIN
tls (SSL-based security)
Listing Connection Services
To list available connection services on a broker, use a command like the following:
imqcmd list svc [-b hostName:portNumber] -u admin -p admin
For example, the following command lists the services available for the broker running on the host myServer on port 6565.
imqcmd list svc -b MyServer:6565 -u admin -p admin
The following command lists all services on the broker running on localhost at port 7676:
imqcmd list svc -u admin -p admin
The command will output information like the following:
------------------------------------------------
Service Name Port Number Service State
------------------------------------------------
admin 41844 (dynamic) RUNNING
httpjms - UNKNOWN
httpsjms - UNKNOWN
jms 41843 (dynamic) RUNNING
ssladmin dynamic UNKNOWN
ssljms dynamic UNKNOWN
Displaying Connection Service Information
To query and display information about a single service, use the query subcommand. For example,
imqcmd query svc -n jms -u admin -p admin
This command produces output like the following:
Service Name jms
Service State RUNNING
Port Number 60920 (dynamic)
Current Number of Allocated Threads 0
Current Number of Connections 0
Min Number of Threads 10
Max Number of Threads 1000
Updating Connection Service Properties
You can use the update subcommand to change the value of one or more of the service properties listed in Table 6-7.
Table 6-7 Connection Service Properties Updated by imqcmd
Property
Description
port
The port assigned to the service to be updated (does not apply to httpjms or httpsjms). A value of 0 means the port is dynamically allocated by the Port Mapper.
minThreads
The minimum number of threads assigned to the service.
maxThreads
The maximum number of threads assigned to the service.
The following command changes the minimum number of threads assigned to the jms service to 20.
imqcmd update svc -n jms -o “minThreads=20”
Displaying Connection Service Metrics
To display metrics information about a single service, use the metrics subcommand. For example, to get cumulative totals for messages and packets handled by the jms connection service:
imqcmd metrics svc -n jms -m ttl -u admin -p admin
This command produces output like the following:
-------------------------------------------------
Msgs Msg Bytes Pkts Pkt Bytes
In Out In Out In Out In Out
-------------------------------------------------
164 100 120704 73600 282 383 135967 102127
657 100 483552 73600 775 876 498815 149948
For a more detailed description of the use of imqcmd to report connection service metrics, see "Monitoring Tools".
Pausing and Resuming a Connection Service
To pause any service other than the admin service (which cannot be paused), use a command like the following:
imqcmd pause svc -n serviceName -u admin -p admin
Pausing a service has the following effects:
- The broker stops accepting new client connections on the paused service. If a Message Queue client attempts to open a new connection, it will get an exception.
- All the existing connections on the paused service are kept alive, but the broker suspends all message processing on such connections until the service is resumed. (For example, if a client attempts to send a message, the send() method will block until the service is resumed.)
- The message delivery state of any messages already received by the broker is maintained. (For example, transactions are not disrupted and message delivery will resume when the service is resumed.)
To resume a service, use a command like the following:
imqcmd resume svc -n serviceName -u admin -p admin
Getting Connection InformationThe Command utility includes subcommands that allow you to list and get information about connections.
Table 6-8 lists the imqcmd subcommands that apply to connections. If no host name or port is specified, they are assumed to be localhost, 7676.
Table 6-8 imqcmd Subcommands Used to Manage Connection Services
Subcommand Syntax
Description
list cxn [-svn serviceName]
[-b hostName:port]Lists all connections of the specified service name on the default broker or on a broker at the specified host and port. If the service name is not specified, all connections are listed.
query cxn -n connectionID
[-b hostName:port]Displays information about the specified connection on the default broker or on a broker at the specified host and port.
To query and display information about a single connection service, use the query subcommand. For example,
imqcmd query cxn -n 421085509902214374 -u admin -p admin
This command produces output like the following:
Connection ID 421085509902214374
User guest
Service jms
Producers 0
Consumers 1
Host 111.22.333.444
Port 60953
Client ID
Client Platform
Managing DestinationsAll Message Queue messages are routed to their consumer clients by way of queue and topic destinations created on a particular broker.
The Command utility includes subcommands that allow you to perform the following destination management tasks:
For an introduction to destinations, see "Physical Destinations".
Table 6-9 provides a summary of the imqcmd destination subcommands. Remember to specify the host name and port of the broker if this is not the default broker (localhost:7676).
Table 6-9 imqcmd Subcommands Used to Manage Destinations
Subcommand Syntax
Description
compact dst [-t destType
-n destName]Compacts the built-in file-based data store for the destination of the specified type and name. If no destination type and name are specified, then all destinations are compacted. Destinations must be paused before they can be compacted.
create dst -t destType
-n destName
[-o attribute=value]
[-o attribute=value1]…Creates a destination of the specified type, with the specified name, and the specified attributes. Destination names must contain only alphanumeric characters (no spaces) and can begin with an alphabetic character or the characters “_” and “$”. They cannot begin with the character string “mq.”
destroy dst -t destType
-n destNameDestroys the destination of the specified type and name.
list dst [-t destType] [-tmp]
Lists all destinations of the specified type, with option of listing temporary destinations as well (see "Temporary Destinations").
The type argument can have two values:
destType = q (queue)
destType = t (topic)If the type is not specified, all destinations of all types are listed.
metrics dst -t destType
-n destName
[-m metricType]
[-int interval]
[-msp numSamples]Displays metrics information for the destination of the specified type and name.
Use the -m option to specify the type of metric to display:
ttl Displays metrics on messages and packets flowing into and out of the destination and residing in memory. (default metric type))
rts Displays metrics on rate of flow of messages and packets into and out of the destination (per second) and other rate information.
con Displays consumer-related metrics.
dsk Displays disk usage metrics.
Use the -int option to specify the interval (in seconds) at which to display the metrics. The default is 5 seconds.
Use the -msp option to specify the number of samples displayed in the output. The default is an unlimited number (infinite).
pause dst [-t destType
-n destName]
[-pst pauseType]Pauses the delivery of messages to consumers (-pst CONSUMERS), or from producers (-pst PRODUCERS), or both (-pst ALL), for the destination of the specified type and name. If no destination type and name are specified, then all destinations are paused. The default is ALL.
purge dst -t destType
-n destNamePurges messages at the destination of the specified type and name.
query dst -t destType
-n destNameLists information about the destination of the specified type and name.
resume dst [-t destType
-n destName]Resumes the delivery of messages for the paused destination of the specified type and name. If no destination type and name are specified, then all destinations are resumed.
update dst -t destType
-n destName
-o attribute=value
[-o attribute=value1]…Updates the value of the specified attributes at the specified destination.
The attribute name may be any of the attributes described in Table 6-10.
Creating Destinations
When creating a destination, you must specify the following:
Many of the destination attributes are used to manage broker memory resources and message flow. For example, you can specify the maximum number of producers allowed for a destination or the maximum number (or size) of messages allowed in a destination. These limits are similar to those that can be set on a broker-wide basis using broker configuration properties (see "Managing Memory Resources and Message Flow"). You can also specify how the broker responds when these limits are reached.
There are also destination attributes that apply only to queue destinations. These are used to specify the number of active and backup consumers used in load-balanced delivery of messages to multiple consumers (see "Queue Destinations").
Table 6-10 describes the attributes that apply for each type of destination. You can set the attribute values when you create or update a destination. For auto-created destinations you set default property values in the broker’s instance configuration file (see "Configuration Files").
Table 6-10 Destination Attributes
Destination
TypeAttribute
Default Value
Description
Queue &
TopicmaxNumMsgs1
-1
(unlimited)Specifies maximum number of unconsumed messages allowed in the destination.
Queue &
TopicmaxTotalMsgBytes1
-1
(unlimited)Specifies the maximum total amount of memory (in bytes) allowed for unconsumed messages in the destination.
Queue &
TopiclimitBehavior
REJECT_
NEWESTSpecifies how the broker responds when a memory-limit threshold is reached. Values are:
FLOW_CONTROL — slows down producers
REMOVE_OLDEST — throws out oldest messages
REMOVE_LOW_PRIORITY — throws out lowest priority messages according to age of the messages (producing client receives no notification of message deletion)
REJECT_NEWEST — rejects the newest messages (producing client gets exception for rejection of persistent messages, but no notification for rejection of non-persistent messages)
Queue &
TopicmaxBytesPerMsg
-1
(unlimited)Specifies maximum size (in bytes) of any single message allowed in the destination (producing client gets exception for rejection of persistent messages, but no notification for rejection of non-persistent messages.
Queue &
TopicmaxNumProducers1
-1
(unlimited)Specifies maximum number of producers allowed for the destination. When this limit is reached, no new producers can be created.
Queue only
maxNumActiveConsumers
1
Specifies the maximum number of consumers that can be active in load-balanced delivery from a queue destination. A value of -1 means an unlimited number. (Platform Edition limits this value to 2.)
Queue only
maxNumBackupConsumers
0
Specifies the maximum number of backup consumers that can take the place of active consumers, if any fail during load-balanced delivery from a queue destination. A value of -1 means an unlimited number.
Queue &
TopicconsumerFlowLimit
Topics: 1000
Queues: 1000
Specifies the maximum number of messages that will be delivered to a consumer in a single batch. In load-balanced queue delivery, this is the initial number of queued messages routed to active consumers before load-balancing commences (see "Queue Delivery to Multiple Consumers"). This limit can be overridden by a lower value specified for the destination’s consumers on their respective connections (see information on Connection Factory attributes in the Message Queue Java Client Developer’s Guide). A value of -1 means an unlimited number.
Queue only
localDeliveryPreferred
false
Applies only to load-balanced queue delivery in broker clusters. Specifies that messages be delivered to remote consumers only if there are no consumers on the local broker. Requires that the destination not be restricted to local-only delivery (isLocalOnly = false).
Queue &
TopicisLocalOnly
false
Applies only to broker clusters. Specifies that a destination is not replicated on other brokers, and is therefore limited to delivering messages only to local consumers (consumers connected to the broker on which the destination is created). This attribute cannot be updated once the destination has been created.
1. In a cluster environment, this property applies to each instance of the destination in the cluster, rather than collectively to all instances in the cluster.
Note that a destination name must contain only alphanumeric characters (no spaces) and can begin with an alphabetic character or the characters “_” and “$”. It cannot begin with the character string “mq,” which is reserved for metrics topic destinations (see Table 2-8.
Listing Destinations
You can get information about a destination’s current attribute values, about the number of producers or consumers associated with a destination, and about messaging metrics, such as the number and size of messages in the destination.
To find a destination about which you want to get information, you can first list all destinations on a particular broker using the list dst subcommand. For example, to get a list of all destinations on the broker running on myHost at port 4545, enter the following command:
imqcmd list dst -b myHost:4545
The list dst subcommand can optionally specify the type of destination to list or optionally include temporary destinations (using the -tmp option). Temporary destinations are created by clients, normally for the purpose of receiving replies to messages sent to other clients (see "Temporary Destinations").
Displaying Destination Information
To get information about a destination’s current attribute values, use the query dst subcommand, such as in the following command:
imqcmd query dst -t q -n XQueue -u admin -p admin
This command produces output like the following:
------------------------------------
Destination Name Destination Type
------------------------------------
XQueue Queue
On the broker specified by:
-------------------------
Host Primary Port
-------------------------
localhost 7676
Destination Name XQueue
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 100
Is Local Destination false
Local Delivery is Preferred false
The output also shows the number of producers and consumers associated with the destination. For queue destinations, this would include both active and backup consumers.
You can use the update dst subcommand to change the values of one or more attributes (see "Updating Destination Attributes").
Updating Destination Attributes
You can change the attributes of a destination by using the update dst subcommand and the -o option to specify the attribute to update. You can use the -o option more than once if you want to update more than one attribute. For example, the following command changes the maxBytesPerMsg attribute to 1000 and the MaxNumMsgs to 2000:
imqcmd update dst -t q -n myQueue -o “maxBytesPerMsg=1000”
-o “maxNumMsgs=2000” -u admin -p adminSee Table 6-10 for a list of the attributes that you can update.
You cannot use the update dst subcommand to update the type of a destination or to update the isLocalOnly attribute.
Displaying Destination Metrics
To get message metrics information about a destination, use the metrics dst subcommand, such as in the following command:
imqcmd metrics dst -t q -n XQueue -m ttl -u admin -p admin
This command produces output like the following:
-----------------------------------------------------------------------------
Msgs Msg Bytes Msg Count Total Msg Bytes (k) Largest
In Out In Out Current Peak Avg Current Peak Avg Msg (k)
-----------------------------------------------------------------------------
200 200 147200 147200 0 200 0 0 143 71 0
300 200 220800 147200 100 200 10 71 143 64 0
300 300 220800 220800 0 200 0 0 143 59 0
For a more detailed description of the use of imqcmd to report destination metrics, see "Monitoring Tools".
Pausing and Resuming Destinations
You can pause a destination to control the delivery of messages from producers to the destination, or from the destination to consumers, or both. In particular, you can pause the flow of messages into a destination to help prevent destinations from being overwhelmed with messages when production of messages is much faster than consumption.
To pause the delivery of messages to or from a destination, use the pause dst subcommand, as in the following command:
imqcmd pause dst -n myQueue -t q -pst PRODUCERS -u admin -p admin
imqcmd pause dst -n myTopic -t t -pst CONSUMERS -u admin -p admin
In the case where you have paused a destination and want to resume delivery, enter the following command:
imqcmd resume dst -n myQueue -t q
In a multi-broker cluster, instances of the destination reside on each broker in the cluster. You must pause each of these destinations individually.
Purging Destinations
You can purge all messages currently queued at a destination. Purging a destination means that all messages queued at the physical destination are deleted. You might want to purge messages when the messages accumulated at a destination are taking up too much of the system’s resources. This might happen when a queue does not have any registered consumer clients and is receiving many messages. It might also happen if inactive durable subscribers to a topic do not become active. In both cases, messages are held unnecessarily.
To purge messages at a destination, use the purge dst subcommand, as in the following commands:
imqcmd purge dst -n myQueue -t q -u admin -p admin
imqcmd purge dst -n myTopic -t t -u admin -p admin
In the case where you have shut down the broker and do not want old messages to be delivered when you restart it, use the -reset messges option to purge stale messages; for example:
imqbrokerd -reset messages -u admin -p admin
This saves you the trouble of purging destinations after restarting the broker.
In a multi-broker cluster, instances of the destination reside on each broker in the cluster. You must purge each of these destinations individually.
Destroying Destinations
To destroy a destination, use the destroy dst subcommand, as in the following command:
imqcmd destroy dst -t q -n myQueue -u admin -p admin
Destroying a destination purges all messages at that destination and removes it from the broker; the operation is not reversible.
Compacting Destinations
If you are using the built-in file-based data store (as opposed to a plugged-in JDBC-compliant data store) as the persistent store for messages, you can monitor disk utilization and compact the disk when necessary.
The file-based message store is structured so that messages are stored in directories according to the destinations in which they are being held. In each destination’s directory, most messages are stored in one file consisting of variable-sized records, the variable-sized record file. (To alleviate fragmentation, messages whose size exceeds a configurable threshold will be stored in their own individual files.) As messages of varying sizes are persisted and then removed from the variable-sized record file, holes may develop in the file where free records are not being re-used.
To manage unused free records, the Command utility includes subcommands for monitoring disk utilization per destination and for reclaiming free disk space when utilization drops.
Monitoring a Destination’s Disk Utilization
To monitor a destination’s disk utilization, use the following imqcmd subcommand:
imqcmd metrics dst -t q -n myQueue -m dsk -u admin -p admin
This command produces output like the following:
--------------------------------------
Reserved Used Utilization Ratio
--------------------------------------
806400 804096 99
1793024 1793024 100
2544640 2518272 98
The columns in the subcommand output have the following meaning:
Table 6-11 Destination disk Utilization Metrics
Metric
Description
Reserved
Disk space in bytes used by all records, including records that hold active messages and free records waiting to be reused
Used
Disk space in bytes used by records that hold active messages
Utilization Ratio
Quotient of used disk space divided by reserved disk space. The higher the ratio, the more the disk space is being used to hold active messages.
Reclaiming Unused Destination Disk Space
The disk utilization pattern depends on the characteristics of the messaging application that uses a particular destination. Depending on the relative flow of messages into and out of a destination, and the relative size of messages, the reserved disk space might grow over time.
If the message producing rate is greater than the message consuming rate, then free records should generally be reused and the utilization ratio should be on the high side. However, if the message producing rate is similar to or smaller than the message consuming rate, you can expect that the utilization ratio will be low.
In general, you want the reserved disk space to stabilize and the utilization to remain high. As a rule of thumb, if the system reaches a steady state in which the amount of reserved disk space stays pretty much constant and the utilization rate is high (above 75%), there is no need to reclaim the unused disk space. If the system reaches a steady state and the utilization rate is low (below 50%), you can compact the disk to reclaim the disk space occupied by free records.
If the reserved disk space continues to increase over time, you should reconfigure the destination’s memory management by setting destination memory limit properties and limit behaviors (see Table 6-10).
To Reclaim Unused Destination Disk Space
If destination type and name are not specified, then these operations are performed for all destinations.
Managing Durable SubscriptionsYou might need to use imqcmd subcommands to manage a broker’s durable subscriptions. A durable subscription is a subscription to a topic that is registered by a client as durable; it has a unique identity and it requires the broker to retain messages for that subscription even when its consumer becomes inactive. Normally, the broker may only delete a message held for a durable subscriber when the message expires.
Table 6-12 provides a summary of the imqcmd durable subscription subcommands. Remember to specify the host name and port of the broker if this is not the default (localhost:7676) broker.
Table 6-12 imqcmd Subcommands Used to Manage Durable Subscriptions
Subcommand
Description
list dur -d destName
Lists all durable subscriptions for the specified destination.
destroy dur -n subscrName
-c client_idDestroys the specified durable subscription with the specified Client Identifier (see "Client Identifiers").
purge dur -n subscrName
-c client_idPurges all messages for the specified durable subscription with the specified Client Identifier (see "Client Identifiers").
For example, the following command lists all durable subscriptions to the topic SPQuotes
imqcmd list dur -d SPQuotes
For each durable subscription to a topic, the list dur subcommand returns the name of the durable subscription, the client ID of the user, the number of messages queued to this topic, and the state of the durable subscription (active/inactive). For example:
Name Client ID Number of Durable Sub
Messages State
----------------------------------------------------------------
myDurable myClientID 1 INACTIVE
You can use the information returned from the list dur subcommand to identify a durable subscription you might want to destroy or for which you want to purge messages. Use the name of the subscription and the client ID to identify the subscription. For example:
imqcmd destroy dur -n myDurable -c myClientID
Managing TransactionsAll transactions initiated by client applications are tracked by the broker. These can be simple Message Queue transactions or distributed transactions managed by an XA resource manager (see "Local Transactions"). Each transaction has a Message Queue transaction ID—a 64 bit number that uniquely identifies a transaction on the broker. Distributed transactions also have a distributed transaction ID (XID) assigned by the distributed transaction manager—up to 128 bytes long. Message Queue maintains the association of an Message Queue transaction ID with an XID.
For distributed transactions, in cases of failure, it is possible that transactions could be left in a PREPARED state without ever being committed. Hence, as an administrator you might need to monitor and then roll back or commit transactions left in a prepared state.
Table 6-13 provides a summary of the imqcmd transactions subcommands. Remember to specify the host name and port of the broker if this is not the default (localhost:7676) broker.
Table 6-13 imqcmd Subcommands Used to Manage Transactions
Subcommand
Description
list txn
Lists all transactions, being tracked by the broker.
query txn -n transaction_id
Lists information about the specified transaction.
commit txn -n transaction_id
Commits the specified transaction.
rollback txn -n transaction_id
Rolls back the specified transaction.
For example, the following command lists all transactions in a broker.
imqcmd list txn
For each transaction, the list subcommand returns the transaction ID, state, user name, number of messages or acknowledgements, and creation time. For example:
---------------------------------------------------------------
Transaction ID State User name # Msgs/ Creation time
# Acks
---------------------------------------------------------------
64248349708800 PREPARED guest 4/0 1/30/02 10:08:31 AM
64248371287808 PREPARED guest 0/4 1/30/02 10:09:55 AM
The command shows all transactions in the broker, both local and distributed. You can only commit or roll back transactions in the PREPARED state. You should only do so if you know that the transaction has been left in this state by a failure and is not in the process of being committed by the distributed transaction manager.
For example, if the broker’s auto-rollback property is set to false (see Table 2-4), then you have to manually commit or roll back transactions found in a PREPARED state at broker startup.
The list subcommand also shows the number of messages that were produced in the transaction and the number of messages that were acknowledged in the transaction (#Msgs/#Acks). These messages will not be delivered and the acknowledgements will not be processed until the transaction is committed.
The query subcommand lets you see the same information plus a number of additional values: the Client ID, connection identification, and distributed transaction ID (XID). For example,
imqcmd query txn -n 64248349708800
produces output like the following:
Client ID
Connection guest@192.18.116.219:62209->jms:62195
Creation time 1/30/02 10:08:31 AM
Number of acknowledgements 0
Number of messages 4
State PREPARED
Transaction ID 64248349708800
User name guest
XID
6469706F6C7369646577696E6465723130313234313431313030373230
The commit and rollback subcommands can be used to commit or roll back a distributed transaction. As mentioned previously, only a transaction in the PREPARED state can be committed or rolled back. For example:
imqcmd commit txn -n 64248349708800
It is also possible to configure the broker to automatically roll back transactions in the PREPARED state at broker startup. See the imq.transaction.autorollback property in Table 2-4 for more information.