| //// |
| 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 |
| //// |
| |
| [id='monitoring-using-qdstat'] |
| = Monitoring {RouterName} Using `qdstat` |
| |
| You can use `qdstat` to view the status of routers on your router network. For example, you can view information about the attached links and configured addresses, available connections, and nodes in the router network. |
| |
| == Syntax for Using `qdstat` |
| |
| You can use `qdstat` with the following syntax: |
| |
| [options="nowrap",subs="+quotes"] |
| ---- |
| $ qdstat __OPTION__ [__CONNECTION_OPTIONS__] [__SECURE_CONNECTION_OPTIONS__] |
| ---- |
| |
| This specifies: |
| |
| * An `option` for the type of information to view. |
| * One or more optional `connection_options` to specify a router for which to view the information. |
| + |
| If you do not specify a connection option, `qdstat` connects to the router listening on localhost and the default AMQP port (5672). |
| * The `secure_connection_options` if the router for which you want to view information only accepts secure connections. |
| |
| For more information about `qdstat`, see the {qdstatManPageLink}. |
| |
| == Creating a State Dump of the Router Network |
| |
| A state dump shows the current operational state of the router network. You can display the following statistics for a single router, or for all routers in the router network: |
| |
| * Links |
| * Addresses |
| * Connections |
| * Autolinks |
| * Link routes |
| * General statistics |
| * Memory usage |
| |
| .Procedure |
| |
| * Do one of the following: |
| + |
| -- |
| [cols="30,70"] |
| |=== |
| | To... | Use this command: |
| |
| | Create a state dump containing all statistics for all routers |
| a| |
| [options="nowrap"] |
| ---- |
| $ qdstat --all-routers --all-entities |
| ---- |
| |
| If you run this command on an interior router, it displays the statistics for all interior routers. If you run the command on an edge router, it displays the statistics for only that edge router. |
| |
| | Create a state dump containing a single statistic for all routers |
| a| |
| [options="nowrap",subs="+quotes"] |
| ---- |
| $ qdstat -l\|-a\|-c\|--autolinks\|--linkroutes\|-g\|-m --all-routers |
| ---- |
| |
| If you run this command on an interior router, it displays the statistic for all interior routers. If you run the command on an edge router, it displays the statistic for only that edge router. |
| |
| | Create a state dump containing all statistics for a single router |
| a| |
| [options="nowrap"] |
| ---- |
| $ qdstat --all-entities |
| ---- |
| |
| This command shows the statistics for the local router only. |
| |=== |
| -- |
| |
| == Viewing General Statistics for a Router |
| |
| You can view information about a router in the router network, such as its working mode and ID. |
| |
| .Procedure |
| |
| * Use the following command: |
| + |
| -- |
| [options="nowrap",subs="+quotes"] |
| ---- |
| $ qdstat -g [all-routers|__CONNECTION_OPTIONS__] |
| ---- |
| |
| This example shows general statistics for the local router: |
| |
| [options="nowrap"] |
| ---- |
| $ qdstat -g |
| Router Statistics |
| attr value |
| ============================================= |
| Version 1.2.0 |
| Mode standalone |
| Router Id Router.A |
| Link Routes 0 |
| Auto Links 0 |
| Links 2 |
| Nodes 0 |
| Addresses 4 |
| Connections 1 |
| Presettled Count 0 |
| Dropped Presettled Count 0 |
| Accepted Count 2 |
| Rejected Count 0 |
| Released Count 0 |
| Modified Count 0 |
| Ingress Count 2 |
| Egress Count 1 |
| Transit Count 0 |
| Deliveries from Route Container 0 |
| Deliveries to Route Container 0 |
| ---- |
| -- |
| |
| == Viewing a List of Connections to a Router |
| |
| You can view: |
| |
| * Connections from clients (sender/receiver) |
| * Connections from and to other routers in the network |
| * Connections to other containers (such as brokers) |
| * Connections from the tool itself |
| |
| .Procedure |
| |
| * Use this command: |
| + |
| -- |
| [options="nowrap",subs="+quotes"] |
| ---- |
| $ qdstat -c [all-routers|__CONNECTION_OPTIONS__] |
| ---- |
| |
| For more information about the fields displayed by this command, see link:{qdstatManPageUrl}#_qdstat_c[the qdstat -c output columns^]. |
| |
| In this example, two clients are connected to `Router.A`. `Router.A` is connected to `Router.B` and a broker. |
| |
| Viewing the connections on Router.A displays the following: |
| |
| [options="nowrap"] |
| ---- |
| $ qdstat -c -r Router.A |
| Connections |
| id host container role dir security authentication tenant |
| ================================================================================================================================== |
| 2 127.0.0.1:5672 route-container out no-security anonymous-user // <1> |
| 10 127.0.0.1:5001 Router.B inter-router out no-security anonymous-user // <2> |
| 12 localhost.localdomain:42972 161211fe-ba9e-4726-9996-52d6962d1276 normal in no-security anonymous-user // <3> |
| 14 localhost.localdomain:42980 a35fcc78-63d9-4bed-b57c-053969c38fda normal in no-security anonymous-user // <3> |
| 15 localhost.localdomain:42982 0a03aa5b-7c45-4500-8b38-db81d01ce651 normal in no-security anonymous-user // <4> |
| ---- |
| <1> This connection shows that `Router.A` is connected to a broker, because the `role` is `route-container`, and the `dir` is `out`. |
| <2> `Router.A` is also connected to another router on the network (the `role` is `inter-router`), establishing an output connection (the `dir` is `out`). |
| <3> These connections show that two clients are connected to `Router.A`, because the `role` is `normal`, and the `dir` is `in`. |
| <4> The connection from `qdstat` to `Router.A`. This is the connection that `qdstat` uses to query `Router.A` and display the command output. |
| |
| `Router.A` is connected to `Router.B`. Viewing the connections on `Router.B` displays the following: |
| |
| [options="nowrap"] |
| ---- |
| $ qdstat -c -r Router.B |
| Connections |
| id host container role dir security authentication tenant |
| ==================================================================================================== |
| 1 localhost.localdomain:51848 Router.A inter-router in no-security anonymous-user // <1> |
| ---- |
| <1> This connection shows that `Router.B` is connected to `Router.A` through an incoming connection (the `role` is `inter-router` and the `dir` is `in`). There is not a connection from `qdstat` to `Router.B`, because the command was run from `Router.A` and forwarded to `Router.B`. |
| -- |
| |
| == Viewing AMQP Links Attached to a Router |
| |
| You can view a list of AMQP links attached to the router from clients (sender/receiver), from or to other routers into the network, to other containers (for example, brokers), and from the tool itself. |
| |
| .Procedure |
| * Use this command: |
| + |
| -- |
| [options="nowrap",subs="+quotes"] |
| ---- |
| $ qdstat -l [all-routers|__CONNECTION_OPTIONS__] |
| ---- |
| |
| For more information about the fields displayed by this command, see link:{qdstatManPageUrl}#_qdstat_l[the qdstat -l output columns^]. |
| |
| In this example, `Router.A` is connected to both `Router.B` and a broker. A link route is configured for the `my_queue` queue and waypoint (with autolinks), and for the `my_queue_wp` queue on the broker. In addition, there is a receiver connected to `my_address` (message routing based), another to `my_queue`, and the a third one to `my_queue_wp`. |
| |
| In this configuration, the router uses only one connection to the broker for both the waypoints (related to `my_queue_wp`) and the link route (related to `my_queue`). |
| |
| Viewing the links displays the following: |
| |
| [options="nowrap"] |
| ---- |
| $ qdstat -l |
| Router Links |
| type dir conn id id peer class addr phs cap undel unsett del presett psdrop acc rej rel mod admin oper |
| ====================================================================================================================================================== |
| router-control in 2 7 250 0 0 2876 0 0 0 0 0 0 enabled up // <1> |
| router-control out 2 8 local qdhello 250 0 0 2716 0 0 0 0 0 0 enabled up |
| inter-router in 2 9 250 0 0 1 0 0 0 0 0 0 enabled up |
| inter-router out 2 10 250 0 0 1 0 0 0 0 0 0 enabled up |
| endpoint in 1 11 mobile my_queue_wp 1 250 0 0 3 0 0 0 0 0 0 enabled up // <2> |
| endpoint out 1 12 mobile my_queue_wp 0 250 0 0 3 0 0 0 0 0 0 enabled up |
| endpoint out 4 15 mobile my_address 0 250 0 0 0 0 0 0 0 0 0 enabled up // <3> |
| endpoint out 6 18 19 250 0 0 1 0 0 0 0 0 0 enabled up // <4> |
| endpoint in 1 19 18 0 0 0 1 0 0 0 0 0 0 enabled up // <5> |
| endpoint out 19 40 mobile my_queue_wp 1 250 0 0 1 0 0 0 0 0 0 enabled up // <6> |
| endpoint in 24 48 mobile $management 0 250 0 0 1 0 0 0 0 0 0 enabled up |
| endpoint out 24 49 local temp.mx5HxzUe2Eddw_s 250 0 0 0 0 0 0 0 0 0 enabled up |
| ---- |
| <1> The `conn id` 2 connection has four links (in both directions) for inter-router communications with `Router.B`, such as control messages and normal message-routed deliveries. |
| <2> There are two autolinks (`conn id 1`) for the waypoint for `my_queue_wp`. There is an incoming (`id 11`) and outgoing (`id 12`) link to the broker, and another `out` link (`id 40`) to the receiver. |
| <3> A `mobile` link for `my_address`. The `dir` is `out` related to the receiver attached to it. |
| <4> The `out` link from the router to the receiver for `my_queue`. This enables the router to deliver messages to the receiver. |
| <5> The `in` link to the router for `my_queue`. This enables the router to get messages from `my_queue` so that they can be sent to the receiver on the `out` link. |
| <6> The remaining links are related to the `$management` address and are used by `qdstat` to receive the information that is displayed by this command. |
| -- |
| |
| == Viewing Known Routers on a Network |
| |
| To see the topology of the router network, you can view known routers on the network. |
| |
| .Procedure |
| |
| * Use this command: |
| + |
| -- |
| [options="nowrap",subs="+quotes"] |
| ---- |
| $ qdstat -n [all-routers|__CONNECTION_OPTIONS__] |
| ---- |
| |
| For more information about the fields displayed by this command, see link:{qdstatManPageUrl}#_qdstat_n[the qdstat -n output columns^]. |
| |
| In this example, `Router.A` is connected to `Router.B`, which is connected to `Router.C`. Viewing the router topology on `Router.A` shows the following: |
| |
| [options="nowrap"] |
| ---- |
| $ qdstat -n -r Router.A |
| Routers in the Network |
| router-id next-hop link cost neighbors valid-origins |
| ========================================================================== |
| Router.A (self) - ['Router.B'] [] // <1> |
| Router.B - 0 1 ['Router.A', 'Router.C'] [] // <2> |
| Router.C Router.B - 2 ['Router.B'] [] // <3> |
| ---- |
| <1> `Router.A` has one neighbor: `Router.B`. |
| <2> `Router.B` is connected to `Router.A` and `Router.C` over `link` 0. The `cost` for `Router.A` to reach `Router.B` is 1, because the two routers are connected directly. |
| <3> `Router.C` is connected to `Router.B`, but not to `Router.A`. The `cost` for `Router.A` to reach `Router.C` is 2, because messages would have to pass through `Router.B` as the `next-hop`. |
| |
| `Router.B` shows a different view of the router topology: |
| |
| [options="nowrap"] |
| ---- |
| $ qdstat -n -v -r Router.B |
| Routers in the Network |
| router-id next-hop link cost neighbors valid-origins |
| ========================================================================== |
| Router.A - 0 1 ['Router.B'] ['Router.C'] |
| Router.B (self) - ['Router.A', 'Router.C'] [] |
| Router.C - 1 1 ['Router.B'] ['Router.A'] |
| ---- |
| |
| The `neighbors` list is the same when viewed on `Router.B`. However, from the perspective of `Router.B`, the destinations on `Router.A` and `Router.C` both have a `cost` of `1`. This is because `Router.B` is connected to `Router.A` and `Router.C` through links. |
| |
| The `valid-origins` column shows that starting from `Router.C`, `Router.B` has the best path to reach `Router.A`. Likewise, starting from `Router.A`, `Router.B` has the best path to reach `Router.C`. |
| |
| Finally, `Router.C` shows the following details about the router topology: |
| |
| [options="nowrap"] |
| ---- |
| $ qdstat -n -v -r Router.C |
| Routers in the Network |
| router-id next-hop link cost neighbors valid-origins |
| ========================================================================== |
| Router.A Router.B - 2 ['Router.B'] [] |
| Router.B - 0 1 ['Router.A', 'Router.C'] [] |
| Router.C (self) - ['Router.B'] [] |
| ---- |
| |
| Due to a symmetric topology, the `Router.C` perspective of the topology is very similar to the `Router.A` perspective. The primary difference is the `cost`: the cost to reach `Router.B` is `1`, because the two routers are connected. However, the cost to reach `Router.A` is `2`, because the messages would have to pass through `Router.B` as the `next-hop`. |
| -- |
| |
| == Viewing Addresses Known to a Router |
| |
| You can view message-routed and link-routed addresses known to a router. |
| |
| .Procedure |
| |
| * Use the following command: |
| + |
| -- |
| [options="nowrap",subs="+quotes"] |
| ---- |
| $ qdstat -a [all-routers|__CONNECTION_OPTIONS__] |
| ---- |
| |
| For more information about the fields displayed by this command, see link:{qdstatManPageUrl}#_qdstat_a[the qdstat -a output columns^]. |
| |
| In this example, `Router.A` is connected to both `Router.B` and a broker. The broker has two queues: |
| |
| * `my_queue` (with a link route on `Router.A`) |
| * `my_queue_wp` (with a waypoint and autolinks configured on `Router.A`) |
| |
| In addition, there are three receivers: one connected to `my_address` for message routing, another connected to `my_queue`, and the last one connected to `my_queue_wp`. |
| |
| Viewing the addresses displays the following information: |
| |
| [options="nowrap"] |
| ---- |
| $ qdstat -a |
| Router Addresses |
| class addr phs distrib in-proc local remote cntnr in out thru to-proc from-proc |
| ====================================================================================================================== |
| local $_management_internal closest 1 0 0 0 0 0 0 0 0 |
| local $displayname closest 1 0 0 0 0 0 0 0 0 |
| mobile $management 0 closest 1 0 0 0 8 0 0 8 0 |
| local $management closest 1 0 0 0 0 0 0 0 0 |
| router Router.B closest 0 0 1 0 0 0 5 0 5 // <1> |
| mobile my_address 0 closest 0 1 0 0 1 1 0 0 0 // <2> |
| link-in my_queue linkBalanced 0 0 0 1 0 0 0 0 0 // <3> |
| link-out my_queue linkBalanced 0 0 0 1 0 0 0 0 0 |
| mobile my_queue_wp 1 balanced 0 1 0 0 1 1 0 0 0 // <4> |
| mobile my_queue_wp 0 balanced 0 1 0 0 1 1 0 0 0 |
| local qdhello flood 1 1 0 0 0 0 0 741 706 // <5> |
| local qdrouter flood 1 0 0 0 0 0 0 4 0 |
| topo qdrouter flood 1 0 1 0 0 0 27 28 28 |
| local qdrouter.ma multicast 1 0 0 0 0 0 0 1 0 |
| topo qdrouter.ma multicast 1 0 1 0 0 0 2 0 3 |
| local temp.IJSoXoY_lX0TiDE closest 0 1 0 0 0 0 0 0 0 |
| ---- |
| <1> An address related to `Router.B` with a `remote` at 1. This is the consumer from `Router.B`. |
| <2> The `my_address` address has one local consumer, which is related to the single receiver attached on that address. The `in` and `out` fields are both 1, which means that one message has traveled through this address using the `closest` distribution method. |
| <3> The incoming link route for the `my_queue` address. This address has one locally-attached container (`cntnr`) as a destination (in this case, the broker). The following entry is the outgoing link for the same address. |
| <4> The incoming autolink for the `my_queue_wp` address and configured waypoint. There is one local consumer (`local`) for the attached receiver. The following entry is the outgoing autolink for the same address. A single message has traveled through the autolinks. |
| <5> The `qdhello`, `qdrouter`, and `qdrouter.ma` addresses are used to periodically update the network topology and deliver router control messages. These updates are made automatically through the inter-router protocol, and are based on all of the messages the routers have exchanged. In this case, the distribution method (`distrib`) for each address is either flood or multicast to ensure the control messages reach all of the routers in the network. |
| -- |
| |
| == Viewing a Router's Autolinks |
| |
| You can view a list of the autolinks that are associated with waypoint addresses for a node on another container (such as a broker). |
| |
| .Procedure |
| |
| * Use the following command: |
| + |
| -- |
| [options="nowrap",subs="+quotes"] |
| ---- |
| $ qdstat --autolinks [all-routers|__CONNECTION_OPTIONS__] |
| ---- |
| |
| For more information about the fields displayed by this command, see link:{qdstatManPageUrl}#_qdstat_autolinks[the qdstat --autolinks output columns^]. |
| |
| In this example, a router is connected to a broker. The broker has a queue called `my_queue_wp`, to which the router is configured with a waypoint and autolinks. Viewing the autolinks displays the following: |
| |
| [options="nowrap"] |
| ---- |
| $ qdstat --autolinks |
| AutoLinks |
| addr dir phs link status lastErr |
| ============================================== |
| my_queue_wp in 1 4 active // <1> |
| my_queue_wp out 0 5 active // <2> |
| ---- |
| <1> The incoming autolink from `my_queue_wp`. As indicated by the `status` field, the link is active, because the broker is running and the connection for the link is already established (as indicated by the `link` field). |
| <2> The outgoing autolink to `my_queue_wp`. Like the incoming link, it is active and has an established connection. |
| -- |
| |
| == Viewing the Status of a Router's Link Routes |
| |
| You can view the status of each incoming and outgoing link route. |
| |
| .Procedure |
| |
| * Use the following command: |
| + |
| -- |
| [options="nowrap",subs="+quotes"] |
| ---- |
| $ qdstat --linkroutes [all-routers|__CONNECTION_OPTIONS__] |
| ---- |
| |
| For more information about the fields displayed by this command, see link:{qdstatManPageUrl}#_qdstat_linkroutes[the qdstat --linkroutes output columns^]. |
| |
| In this example, a router is connected to a broker. The router is configured with a link route to the `my_queue` queue on the broker. Viewing the link routes displays the following: |
| |
| [options="nowrap"] |
| ---- |
| $ qdstat --linkroutes |
| Link Routes |
| prefix dir distrib status |
| ===================================== |
| my_queue in linkBalanced active // <1> |
| my_queue out linkBalanced active // <2> |
| ---- |
| <1> The incoming link route from `my_queue` to the router. This route is currently active, because the broker is running. |
| <2> The outgoing link from the router to `my_queue`. This route is also currently active. |
| -- |
| |
| == Viewing Memory Consumption Information |
| |
| If you need to perform debugging or tracing for a router, you can view information about its memory consumption. |
| |
| .Procedure |
| |
| * Use the following command: |
| + |
| -- |
| [options="nowrap",subs="+quotes"] |
| ---- |
| $ qdstat -m [all-routers|__CONNECTION_OPTIONS__] |
| ---- |
| |
| This command displays information about allocated objects, their size, and their usage by application threads: |
| |
| [options="nowrap"] |
| ---- |
| $ qdstat -m |
| Types |
| type size batch thread-max total in-threads rebal-in rebal-out |
| =========================================================================================== |
| qd_bitmask_t 24 64 128 64 64 0 0 |
| qd_buffer_t 536 16 32 80 80 0 0 |
| qd_composed_field_t 64 64 128 256 256 0 0 |
| qd_composite_t 112 64 128 320 320 0 0 |
| ... |
| ---- |
| -- |
