| <?xml version="1.0" encoding="utf-8"?> |
| <!-- |
| |
| Licensed to the Apache Software Foundation (ASF) under one |
| or more contributor license agreements. See the NOTICE file |
| distributed with this work for additional information |
| regarding copyright ownership. The ASF licenses this file |
| to you under the Apache License, Version 2.0 (the |
| "License"); you may not use this file except in compliance |
| with the License. You may obtain a copy of the License at |
| |
| http://www.apache.org/licenses/LICENSE-2.0 |
| |
| Unless required by applicable law or agreed to in writing, |
| software distributed under the License is distributed on an |
| "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY |
| KIND, either express or implied. See the License for the |
| specific language governing permissions and limitations |
| under the License. |
| |
| --> |
| |
| <section id="section-Managing-CPP-Broker"> |
| <title> Managing the C++ Broker </title> |
| <para> |
| There are quite a few ways to interact with the C++ broker. The |
| command line tools |
| include: |
| </para><itemizedlist> |
| <listitem><para>qpid-route - used to configure federation (a set of federated |
| brokers) |
| </para></listitem> |
| <listitem><para>qpid-config - used to configure queues, exchanges, bindings |
| and list them etc |
| </para></listitem> |
| <listitem><para>qpid-tool - used to view management information/statistics |
| and call any management actions on the broker |
| </para></listitem> |
| <listitem><para>qpid-printevents - used to receive and print QMF events |
| </para></listitem> |
| <listitem><para>qpid-ha - used to interact with the High Availability module |
| </para></listitem> |
| </itemizedlist> |
| |
| <section role="h3" id="MgmtC-2B-2B-Usingqpidconfig"><title> |
| Using qpid-config |
| </title> |
| <para> |
| This utility can be used to create queues exchanges and bindings, |
| both durable and transient. Always check for latest options by |
| running --help command. |
| </para> |
| <programlisting> |
| $ 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> |
| qpid-config [OPTIONS] add queue <name> [AddQueueOptions] |
| qpid-config [OPTIONS] del queue <name> |
| qpid-config [OPTIONS] bind <exchange-name> <queue-name> [binding-key] |
| qpid-config [OPTIONS] unbind <exchange-name> <queue-name> [binding-key] |
| |
| Options: |
| -b [ --bindings ] Show bindings in queue or exchange list |
| -a [ --broker-addr ] Address (localhost) Address of qpidd broker |
| 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 |
| |
| Add Queue Options: |
| --durable Queue is durable |
| --cluster-durable Queue becomes durable if there is only one functioning cluster node |
| --file-count N (8) Number of files in queue's persistence journal |
| --file-size N (24) File size in pages (64Kib/page) |
| --max-queue-size N Maximum in-memory queue size as bytes |
| --max-queue-count N Maximum in-memory queue size as a number of messages |
| --limit-policy [none | reject | flow-to-disk | ring | ring-strict] |
| Action taken when queue limit is reached: |
| none (default) - Use broker's default policy |
| reject - Reject enqueued messages |
| flow-to-disk - Page messages to disk |
| ring - Replace oldest unacquired message with new |
| ring-strict - Replace oldest message, reject if oldest is acquired |
| --order [fifo | lvq | lvq-no-browse] |
| Set queue ordering policy: |
| fifo (default) - First in, first out |
| lvq - Last Value Queue ordering, allows queue browsing |
| lvq-no-browse - Last Value Queue ordering, browsing clients may lose data |
| --generate-queue-events N |
| If set to 1, every enqueue will generate an event that can be processed by |
| registered listeners (e.g. for replication). If set to 2, events will be |
| generated for enqueues and dequeues |
| |
| Add Exchange Options: |
| --durable Exchange is durable |
| --sequence Exchange will insert a 'qpid.msg_sequence' field in the message header |
| with a value that increments for each message forwarded. |
| --ive Exchange will behave as an 'initial-value-exchange', keeping a reference |
| to the last message forwarded and enqueuing that message to newly bound |
| queues. |
| </programlisting> |
| <para> |
| Get the summary page |
| </para> |
| <programlisting> |
| $ qpid-config |
| Total Exchanges: 6 |
| topic: 2 |
| headers: 1 |
| fanout: 1 |
| direct: 2 |
| Total Queues: 7 |
| durable: 0 |
| non-durable: 7 |
| </programlisting> |
| <para> |
| List the queues |
| </para> |
| <programlisting> |
| $ qpid-config queues |
| Queue Name Attributes |
| ================================================================= |
| pub_start |
| pub_done |
| sub_ready |
| sub_done |
| perftest0 --durable |
| reply-dhcp-100-18-254.bos.redhat.com.20713 auto-del excl |
| topic-dhcp-100-18-254.bos.redhat.com.20713 auto-del excl |
| |
| </programlisting> |
| <para> |
| List the exchanges with bindings |
| </para> |
| <programlisting> |
| $ ./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 |
| </programlisting> |
| <!--h3--></section> |
| |
| <section role="h3" id="MgmtC-2B-2B-Usingqpidroute"><title> |
| Using qpid-route |
| </title> |
| <para> |
| This utility is to create federated networks of brokers, This |
| allows you for forward messages between brokers in a network. |
| Messages can be routed statically (using "qpid-route route add") |
| where the bindings that control message forwarding are supplied |
| in the route. Message routing can also be dynamic (using |
| "qpid-route dynamic add") where the messages are automatically |
| forwarded to clients based on their bindings to the local broker. |
| </para> |
| <programlisting> |
| $ qpid-route |
| Usage: qpid-route [OPTIONS] dynamic add <dest-broker> <src-broker> <exchange> [tag] [exclude-list] |
| qpid-route [OPTIONS] dynamic del <dest-broker> <src-broker> <exchange> |
| |
| qpid-route [OPTIONS] route add <dest-broker> <src-broker> <exchange> <routing-key> [tag] [exclude-list] |
| qpid-route [OPTIONS] route del <dest-broker> <src-broker> <exchange> <routing-key> |
| qpid-route [OPTIONS] queue add <dest-broker> <src-broker> <exchange> <queue> |
| qpid-route [OPTIONS] queue del <dest-broker> <src-broker> <exchange> <queue> |
| qpid-route [OPTIONS] route list [<dest-broker>] |
| qpid-route [OPTIONS] route flush [<dest-broker>] |
| qpid-route [OPTIONS] route map [<broker>] |
| |
| qpid-route [OPTIONS] link add <dest-broker> <src-broker> |
| qpid-route [OPTIONS] link del <dest-broker> <src-broker> |
| qpid-route [OPTIONS] link list [<dest-broker>] |
| |
| Options: |
| -v [ --verbose ] Verbose output |
| -q [ --quiet ] Quiet output, don't print duplicate warnings |
| -d [ --durable ] Added configuration shall be durable |
| -e [ --del-empty-link ] Delete link after deleting last route on the link |
| -s [ --src-local ] Make connection to source broker (push route) |
| -t <transport> [ --transport <transport>] |
| Specify transport to use for links, defaults to tcp |
| |
| dest-broker and src-broker are in the form: [username/password@] hostname | ip-address [:<port>] |
| ex: localhost, 10.1.1.7:10000, broker-host:10000, guest/guest@localhost |
| </programlisting> |
| <para> |
| A few examples: |
| </para> |
| <programlisting> |
| qpid-route dynamic add host1 host2 fed.topic |
| qpid-route dynamic add host2 host1 fed.topic |
| |
| qpid-route -v route add host1 host2 hub1.topic hub2.topic.stock.buy |
| qpid-route -v route add host1 host2 hub1.topic hub2.topic.stock.sell |
| qpid-route -v route add host1 host2 hub1.topic 'hub2.topic.stock.#' |
| qpid-route -v route add host1 host2 hub1.topic 'hub2.#' |
| qpid-route -v route add host1 host2 hub1.topic 'hub2.topic.#' |
| qpid-route -v route add host1 host2 hub1.topic 'hub2.global.#' |
| </programlisting> |
| <para> |
| The link map feature can be used to display the entire federated |
| network configuration by supplying a single broker as an entry |
| point: |
| </para> |
| <programlisting> |
| $ qpid-route route map localhost:10001 |
| |
| Finding Linked Brokers: |
| localhost:10001... Ok |
| localhost:10002... Ok |
| localhost:10003... Ok |
| localhost:10004... Ok |
| localhost:10005... Ok |
| localhost:10006... Ok |
| localhost:10007... Ok |
| localhost:10008... Ok |
| |
| Dynamic Routes: |
| |
| Exchange fed.topic: |
| localhost:10002 <=> localhost:10001 |
| localhost:10003 <=> localhost:10002 |
| localhost:10004 <=> localhost:10002 |
| localhost:10005 <=> localhost:10002 |
| localhost:10006 <=> localhost:10005 |
| localhost:10007 <=> localhost:10006 |
| localhost:10008 <=> localhost:10006 |
| |
| Exchange fed.direct: |
| localhost:10002 => localhost:10001 |
| localhost:10004 => localhost:10003 |
| localhost:10003 => localhost:10002 |
| localhost:10001 => localhost:10004 |
| |
| Static Routes: |
| |
| localhost:10003(ex=amq.direct) <= localhost:10005(ex=amq.direct) key=rkey |
| localhost:10003(ex=amq.direct) <= localhost:10005(ex=amq.direct) key=rkey2 |
| </programlisting> |
| <!--h3--></section> |
| |
| <section role="h3" id="MgmtC-2B-2B-Usingqpidtool"><title> |
| Using qpid-tool |
| </title> |
| <para> |
| This utility provided a telnet style interface to be able to |
| view, list all stats and action |
| all the methods. Simple capture below. Best to just play with it |
| and mail the list if you have |
| questions or want features added. |
| </para> |
| <programlisting> |
| qpid: |
| 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 |
| list <className> active - Print contents of all non-deleted objects of specified class |
| list <list-of-IDs> - Print contents of one or more objects (infer className) |
| list <className> <list-of-IDs> - Print contents of one or more objects |
| list is space-separated, ranges may be specified (i.e. 1004-1010) |
| call <ID> <methodName> <args> - Invoke a method on an object |
| schema - Print summary of object classes seen on the target |
| schema <className> - Print details of an object class |
| set time-format short - Select short timestamp format (default) |
| set time-format long - Select long timestamp format |
| quit or ^D - Exit the program |
| qpid: list |
| Management Object Types: |
| ObjectType Active Deleted |
| ================================ |
| qpid.binding 21 0 |
| qpid.broker 1 0 |
| qpid.client 1 0 |
| qpid.exchange 6 0 |
| qpid.queue 13 0 |
| qpid.session 4 0 |
| qpid.system 1 0 |
| qpid.vhost 1 0 |
| qpid: list qpid.system |
| Objects of type qpid.system |
| ID Created Destroyed Index |
| ================================== |
| 1000 21:00:02 - host |
| qpid: list 1000 |
| Object of type qpid.system: (last sample time: 21:26:02) |
| Type Element 1000 |
| ======================================================= |
| config sysId host |
| config osName Linux |
| config nodeName localhost.localdomain |
| config release 2.6.24.4-64.fc8 |
| config version #1 SMP Sat Mar 29 09:15:49 EDT 2008 |
| config machine x86_64 |
| 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) |
| Method 'purge' Discard all messages on queue |
| qpid: list queue |
| Objects of type qpid.queue |
| ID Created Destroyed Index |
| =========================================================================== |
| 1012 21:08:13 - 1002.pub_start |
| 1014 21:08:13 - 1002.pub_done |
| 1016 21:08:13 - 1002.sub_ready |
| 1018 21:08:13 - 1002.sub_done |
| 1020 21:08:13 - 1002.perftest0 |
| 1038 21:09:08 - 1002.mgmt-3206ff16-fb29-4a30-82ea-e76f50dd7d15 |
| 1040 21:09:08 - 1002.repl-3206ff16-fb29-4a30-82ea-e76f50dd7d15 |
| 1046 21:09:32 - 1002.mgmt-df06c7a6-4ce7-426a-9f66-da91a2a6a837 |
| 1048 21:09:32 - 1002.repl-df06c7a6-4ce7-426a-9f66-da91a2a6a837 |
| 1054 21:10:01 - 1002.mgmt-c55915c2-2fda-43ee-9410-b1c1cbb3e4ae |
| 1056 21:10:01 - 1002.repl-c55915c2-2fda-43ee-9410-b1c1cbb3e4ae |
| 1063 21:26:00 - 1002.mgmt-8d621997-6356-48c3-acab-76a37081d0f3 |
| 1065 21:26:00 - 1002.repl-8d621997-6356-48c3-acab-76a37081d0f3 |
| qpid: list 1020 |
| Object of type qpid.queue: (last sample time: 21:26:02) |
| Type Element 1020 |
| ========================================================================== |
| config vhostRef 1002 |
| config name perftest0 |
| config durable False |
| config autoDelete False |
| config exclusive False |
| config arguments {'qpid.max_size': 0, 'qpid.max_count': 0} |
| config storeRef NULL |
| inst msgTotalEnqueues 500000 messages |
| inst msgTotalDequeues 500000 |
| inst msgTxnEnqueues 0 |
| inst msgTxnDequeues 0 |
| inst msgPersistEnqueues 0 |
| inst msgPersistDequeues 0 |
| inst msgDepth 0 |
| inst msgDepthHigh 0 |
| inst msgDepthLow 0 |
| inst byteTotalEnqueues 512000000 octets |
| inst byteTotalDequeues 512000000 |
| inst byteTxnEnqueues 0 |
| inst byteTxnDequeues 0 |
| inst bytePersistEnqueues 0 |
| inst bytePersistDequeues 0 |
| inst byteDepth 0 |
| inst byteDepthHigh 0 |
| inst byteDepthLow 0 |
| inst enqueueTxnStarts 0 transactions |
| inst enqueueTxnCommits 0 |
| inst enqueueTxnRejects 0 |
| inst enqueueTxnCount 0 |
| inst enqueueTxnCountHigh 0 |
| inst enqueueTxnCountLow 0 |
| inst dequeueTxnStarts 0 |
| inst dequeueTxnCommits 0 |
| inst dequeueTxnRejects 0 |
| inst dequeueTxnCount 0 |
| inst dequeueTxnCountHigh 0 |
| inst dequeueTxnCountLow 0 |
| inst consumers 0 consumers |
| inst consumersHigh 0 |
| inst consumersLow 0 |
| inst bindings 1 binding |
| inst bindingsHigh 1 |
| inst bindingsLow 1 |
| inst unackedMessages 0 messages |
| inst unackedMessagesHigh 0 |
| inst unackedMessagesLow 0 |
| inst messageLatencySamples 0 |
| inst messageLatencyMin 0 |
| inst messageLatencyMax 0 |
| inst messageLatencyAverage 0 |
| qpid: |
| </programlisting> |
| <!--h3--></section> |
| |
| <section role="h3" id="MgmtC-2B-2B-Usingqpidprintevents"><title> |
| Using |
| qpid-printevents |
| </title> |
| <para> |
| This utility connects to one or more brokers and collects events, |
| printing out a line per event. |
| </para> |
| <programlisting> |
| $ qpid-printevents --help |
| Usage: qpid-printevents [options] [broker-addr]... |
| |
| Collect and print events from one or more Qpid message brokers. If no broker- |
| addr is supplied, qpid-printevents will connect to 'localhost:5672'. broker- |
| addr is of the form: [username/password@] hostname | ip-address [:<port>] ex: |
| localhost, 10.1.1.7:10000, broker-host:10000, guest/guest@localhost |
| |
| Options: |
| -h, --help show this help message and exit |
| </programlisting> |
| <para> |
| You get the idea... have fun! |
| </para> |
| <!--h3--></section> |
| <section> |
| <title>Using qpid-ha</title> |
| <para>This utility lets you monitor and control the activity of the clustering behavior provided by the HA module. |
| </para> |
| <programlisting> |
| <![CDATA[ |
| qpid-ha --help |
| usage: qpid-ha <command> [<arguments>] |
| |
| Commands are: |
| |
| ready Test if a backup broker is ready. |
| query Print HA configuration settings. |
| set Set HA configuration settings. |
| promote Promote broker from backup to primary. |
| replicate Set up replication from <queue> on <remote-broker> to <queue> on the current broker. |
| |
| For help with a command type: qpid-ha <command> --help |
| ]]> |
| </programlisting> |
| </section> |
| </section> |
