| //// |
| 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}. |
| |
| == 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 [__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 [__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 [__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 [__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 [__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 [__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 autlink 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 [__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 [__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 |
| ... |
| ---- |
| -- |
