Chapter 13. Management Tools and Consoles

13.1. Command-line utilities

13.1.1. Command-line Management utilities

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

Table 13.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-cluster 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
qpid-cluster-store Used in recovering persistent data after a non-clean cluster shutdown

13.1.2. Changes in qpid-config and qpid-stat for MRG 2.3

In MRG 2.3 the qpid-config tool has been updated to align it with the latest developments in open source development. The following changes have been made:

Changes to qpid-config in MRG 2.3

  • The -a --broker-addr command line option was changed to -b --broker. This option specifies the broker address.
  • The -b --bindings command line option was changed to -r --recursive. This option shows the queue/exchange bindings.
  • The -a command for the broker address, as well as the --broker-addr and --bindings form of the commands are still supported but are intentionally not in the usage help

Changes to qpid-stat in MRG 2.3

  • Command line options are now presented in three groups: general options, command options and display options.
  • The new way to specify the broker address is the -b --broker option. It is now under the -g options

13.1.3. Using qpid-config

Changes
  • Updated February 2013.
  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. Version 2.2 and below
    List information on all existing exchanges with the exchanges command. Add the -b option to also see binding information:
    $ qpid-config -b 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
    
    Version 2.3 and above
    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

13.1.4. Using qpid-cluster

qpid-cluster is a command-line utility that allows you to view information on a cluster and its brokers, disconnect a client connection, shut down a broker in a cluster, or shut down the entire cluster. You can see the options using the --help option:
$ qpid-cluster --help
Usage:  qpid-cluster [OPTIONS] [broker-addr]

             broker-addr is in the form:   [username/password@] hostname | ip-address [:<port>]
             ex:  localhost, 10.1.1.7:10000, broker-host:10000, guest/guest@localhost

Options:
          -C [--all-connections]  View client connections to all cluster members
          -c [--connections] ID   View client connections to specified member
          -d [--del-connection] HOST:PORT
                                  Disconnect a client connection
          -s [--stop] ID          Stop one member of the cluster by its ID
          -k [--all-stop]         Shut down the whole cluster
          -f [--force]            Suppress the 'are-you-sure?' prompt
          -n [--numeric]          Don't resolve names
Connect to a cluster and display basic information about the cluster and its brokers. When you connect to the cluster using qpid-cluster, you can use the host and port for any broker in the cluster. For instance, if a broker in the cluster is running on localhost on port 6664, you can start qpid-cluster like this:
$ qpid-cluster localhost:6664
Here is the output:
  Cluster Name: local_test_cluster
Cluster Status: ACTIVE
  Cluster Size: 3
       Members: ID=127.0.0.1:13143 URL=amqp:tcp:192.168.1.101:6664,tcp:192.168.122.1:6664,tcp:10.16.10.62:6664
              : ID=127.0.0.1:13167 URL=amqp:tcp:192.168.1.101:6665,tcp:192.168.122.1:6665,tcp:10.16.10.62:6665
              : ID=127.0.0.1:13192 URL=amqp:tcp:192.168.1.101:6666,tcp:192.168.122.1:6666,tcp:10.16.10.62:6666
The ID for each broker in cluster is given on the left. For instance, the ID for the first broker in the cluster is 127.0.0.1:13143. The URL in the output is the broker's advertised address. Use the ID to shut down the broker using the --stop command:
$ qpid-cluster localhost:6664 --stop 127.0.0.1:13143

13.1.5. 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
        com.redhat.rhm.store    store         1       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...
    

13.1.6. 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