Chapter 12. Management Tools and Consoles

12.1. Command-line utilities

12.1.1. Command-line Management utilities

The command-line tools are management and diagnostic tools for use at the shell prompt.

Table 12.1. Command-line Management utilities

Utility Description
qpid-config Display and configure exchanges, queues, and bindings in the broker
qpid-tool Access configuration, statistics, and control within the broker
qpid-queue-stats Monitor the size and enqueue/dequeue rates of queues in a broker
qpid-ha Configure and view clusters
qpid-route Configure federated routes among brokers
qpid-stat Display details and statistics for various broker objects
qpid-printevents Subscribes to events from a broker and prints details of events raised to the console window
Report a bug

12.1.2. Using qpid-config

  1. View the full list of commands by running the qpid-config --help command from the shell prompt: 
    $ qpid-config --help

Usage:  qpid-config [OPTIONS]
qpid-config [OPTIONS] exchanges [filter-string]
qpid-config [OPTIONS] queues    [filter-string]
qpid-config [OPTIONS] add exchange <type> <name> [AddExchangeOptions]
qpid-config [OPTIONS] del exchange <name>
..[output truncated]...
  2. View a summary of all exchanges and queues by using the qpid-config without options: 
    $ qpid-config

Total Exchanges: 6
	  topic: 2
	headers: 1
	 fanout: 1
	 direct: 2
   Total Queues: 7
	durable: 0
    non-durable: 7
  3. List information on all existing queues by using the queues command: 
    $ qpid-config queues
Queue Name                                Attributes
=================================================================
my-queue                                  --durable 
qmfc-v2-hb-localhost.localdomain.20293.1  auto-del excl --limit-policy=ring 
qmfc-v2-localhost.localdomain.20293.1     auto-del excl 
qmfc-v2-ui-localhost.localdomain.20293.1  auto-del excl --limit-policy=ring 
reply-localhost.localdomain.20293.1       auto-del excl 
topic-localhost.localdomain.20293.1       auto-del excl --limit-policy=ring
  4. Add new queues with the add queue command and the name of the queue to create: 
    $ qpid-config add queue queue_name
  5. To delete a queue, use the del queue command with the name of the queue to remove: 
    $ qpid-config del queue queue_name
  6. List information on all existing exchanges with the exchanges command. Add the -r option ("recursive") to also see binding information: 
    $ qpid-config -r exchanges

Exchange '' (direct)
	bind pub_start => pub_start
	bind pub_done => pub_done
	bind sub_ready => sub_ready
	bind sub_done => sub_done
	bind perftest0 => perftest0
	bind mgmt-3206ff16-fb29-4a30-82ea-e76f50dd7d15 => mgmt-3206ff16-fb29-4a30-82ea-e76f50dd7d15
	bind repl-3206ff16-fb29-4a30-82ea-e76f50dd7d15 => repl-3206ff16-fb29-4a30-82ea-e76f50dd7d15
Exchange 'amq.direct' (direct)
	bind repl-3206ff16-fb29-4a30-82ea-e76f50dd7d15 => repl-3206ff16-fb29-4a30-82ea-e76f50dd7d15
	bind repl-df06c7a6-4ce7-426a-9f66-da91a2a6a837 => repl-df06c7a6-4ce7-426a-9f66-da91a2a6a837
	bind repl-c55915c2-2fda-43ee-9410-b1c1cbb3e4ae => repl-c55915c2-2fda-43ee-9410-b1c1cbb3e4ae
Exchange 'amq.topic' (topic)
Exchange 'amq.fanout' (fanout)
Exchange 'amq.match' (headers)
Exchange 'qpid.management' (topic)
	bind mgmt.# => mgmt-3206ff16-fb29-4a30-82ea-e76f50dd7d15
  7. Add new exchanges with the add exchange command. Specify the type (direct, topic or fanout) along with the name of the exchange to create. You can also add the --durable option to make the exchange durable: 
    $ qpid-config add exchange direct exchange_name --durable
  8. To delete an exchange, use the del exchange command with the name of the exchange to remove: 
    $ qpid-config del exchange exchange_name
Report a bug

12.1.3. Using qpid-tool

  1. The qpid-tool creates a connection to a broker, and commands are run within the tool, rather than at the shell prompt itself. To create the connection, run the qpid-tool at the shell prompt with the name or IP address of the machine running the broker you wish to view. You can also append a TCP port number with a : character: 
    $ qpid-tool localhost

Management Tool for QPID
qpid:
  2. If the connection is successful, qpid-tool will display a qpid: prompt. Type help at this prompt to see the full list of commands: 
    qpid: help
Management Tool for QPID

Commands:
list                    - Print summary of existing objects by class 
list <className>        - Print list of objects of the specified class
list <className> all    - Print contents of all objects of specified class
...[output truncated}...
  3. qpid-tool uses the word objects to refer to queues, exchanges, brokers and other such devices. To view a list of all existing objects, type list at the prompt: 
    # qpid-tool
Management Tool for QPID
qpid: list
Summary of Objects by Type:
    Package                 Class         Active  Deleted
    =======================================================
    org.apache.qpid.broker  exchange      8       0
    org.apache.qpid.broker  broker        1       0
    org.apache.qpid.broker  binding       16      12
    org.apache.qpid.broker  session       2       1
    org.apache.qpid.broker  connection    2       1
    org.apache.qpid.broker  vhost         1       0
    org.apache.qpid.broker  queue         6       5
    org.apache.qpid.broker  system        1       0
    org.apache.qpid.broker  subscription  6       5
  4. You can choose which objects to list by also specifying a class: 
    qpid: list system
Object Summary:
    ID   Created   Destroyed  Index
    ========================================================================
    167  07:34:13  -          UUID('b3e2610e-5420-49ca-8306-dca812db647f')
  5. To view details of an object class, use the schema command and specify the class: 
    qpid: schema queue
Schema for class 'qpid.queue':
Element                Type          Unit         Access      Notes   Description
===================================================================================================================
vhostRef               reference                  ReadCreate  index
name                   short-string               ReadCreate  index
durable                boolean                    ReadCreate
autoDelete             boolean                    ReadCreate
exclusive              boolean                    ReadCreate
arguments              field-table                ReadOnly            Arguments supplied in queue.declare
storeRef               reference                  ReadOnly            Reference to persistent queue (if durable)
msgTotalEnqueues       uint64        message                          Total messages enqueued
msgTotalDequeues       uint64        message                          Total messages dequeued
msgTxnEnqueues         uint64        message                          Transactional messages enqueued
msgTxnDequeues         uint64        message                          Transactional messages dequeued
msgPersistEnqueues     uint64        message                          Persistent messages enqueued
msgPersistDequeues     uint64        message                          Persistent messages dequeued
msgDepth               uint32        message                          Current size of queue in messages
msgDepthHigh           uint32        message                          Current size of queue in messages (High)
msgDepthLow            uint32        message                          Current size of queue in messages (Low)
byteTotalEnqueues      uint64        octet                            Total messages enqueued
byteTotalDequeues      uint64        octet                            Total messages dequeued
byteTxnEnqueues        uint64        octet                            Transactional messages enqueued
byteTxnDequeues        uint64        octet                            Transactional messages dequeued
bytePersistEnqueues    uint64        octet                            Persistent messages enqueued
bytePersistDequeues    uint64        octet                            Persistent messages dequeued
byteDepth              uint32        octet                            Current size of queue in bytes
byteDepthHigh          uint32        octet                            Current size of queue in bytes (High)
byteDepthLow           uint32        octet                            Current size of queue in bytes (Low)
enqueueTxnStarts       uint64        transaction                      Total enqueue transactions started
enqueueTxnCommits      uint64        transaction                      Total enqueue transactions committed
enqueueTxnRejects      uint64        transaction                      Total enqueue transactions rejected
enqueueTxnCount        uint32        transaction                      Current pending enqueue transactions
enqueueTxnCountHigh    uint32        transaction                      Current pending enqueue transactions (High)
enqueueTxnCountLow     uint32        transaction                      Current pending enqueue transactions (Low)
dequeueTxnStarts       uint64        transaction                      Total dequeue transactions started
dequeueTxnCommits      uint64        transaction                      Total dequeue transactions committed
dequeueTxnRejects      uint64        transaction                      Total dequeue transactions rejected
dequeueTxnCount        uint32        transaction                      Current pending dequeue transactions
dequeueTxnCountHigh    uint32        transaction                      Current pending dequeue transactions (High)
dequeueTxnCountLow     uint32        transaction                      Current pending dequeue transactions (Low)
consumers              uint32        consumer                         Current consumers on queue
consumersHigh          uint32        consumer                         Current consumers on queue (High)
consumersLow           uint32        consumer                         Current consumers on queue (Low)
bindings               uint32        binding                          Current bindings
bindingsHigh           uint32        binding                          Current bindings (High)
bindingsLow            uint32        binding                          Current bindings (Low)
unackedMessages        uint32        message                          Messages consumed but not yet acked
unackedMessagesHigh    uint32        message                          Messages consumed but not yet acked (High)
unackedMessagesLow     uint32        message                          Messages consumed but not yet acked (Low)
messageLatencySamples  delta-time    nanosecond                       Broker latency through this queue (Samples)
messageLatencyMin      delta-time    nanosecond                       Broker latency through this queue (Min)
messageLatencyMax      delta-time    nanosecond                       Broker latency through this queue (Max)
messageLatencyAverage  delta-time    nanosecond                       Broker latency through this queue (Average)
  6. To exit the tool and return to the shell, type quit at the prompt: 
    qpid: quit
Exiting...
Report a bug

12.1.4. Using qpid-queue-stats

Run the command qpid-queue-stats to launch the tool.
The tool will begin to report stats for the broker on the current machine, with the following format: 
Queue Name                                     Sec       Depth     Enq Rate     Deq Rate
========================================================================================
message_queue                                 10.00      11224         0.00        54.01
qmfc-v2-ui-radhe.26001.1                      10.00          0         0.10         0.10
topic-radhe.26001.1                           10.00          0         0.20         0.20
message_queue                                 10.01       9430         0.00       179.29
qmfc-v2-ui-radhe.26001.1                      10.01          0         0.10         0.10
topic-radhe.26001.1                           10.01          0         0.20         0.20
The queues on the broker are listed on the left. The Sec column is the sample rate. The tool is hard-coded to poll the broker in 10 second intervals. The Depth column reports the number of messages in the queue. Enq Rate is the number of messages added to the queue (enqueued) since the last sample. Deq Rate is the number of messages removed from the queue (dequeued) since the last sample.
To view the queues on another server, use the -a switch, and provide a remote server address, and optionally the remote port and authentication credentials.
For example, to examine the queues on a remote server with the address 192.168.1.145, issue the command: 
qpid-queue-stats -a 192.168.1.145
To examine the queues on the server broker1.mydomain.com: 
qpid-queue-stats -a broker1.mydomain.com
To examine the queues on the server broker1.mydomain.com, where the broker is running on port 8888: 
qpid-queue-stats -a broker1.mydomain.com:8888
To examine the queues on the server 192.168.1.145, which requires authentication: 
qpid-queue-stats -a username/password@192.168.1.145
Report a bug