Merge branch 'rabbitmq-diagnostics-man-page'

5 files changed, 599 insertions, 46 deletions

diff --git a/docs/rabbitmq-diagnostics.8 b/docs/rabbitmq-diagnostics.8
new file mode 100644
index 0000000000..f025a9f299
--- /dev/null
+++ b/docs/rabbitmq-diagnostics.8
@@ -0,0 +1,551 @@
+.\" vim:ft=nroff:
+.\" The contents of this file are subject to the Mozilla Public License
+.\" Version 1.1 (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.mozilla.org/MPL/
+.\"
+.\" Software distributed under the License is distributed on an "AS IS"
+.\" basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
+.\" the License for the specific language governing rights and
+.\" limitations under the License.
+.\"
+.\" The Original Code is RabbitMQ.
+.\"
+.\" The Initial Developer of the Original Code is Pivotal Software, Inc.
+.\" Copyright (c) 2007-2019 Pivotal Software, Inc.  All rights reserved.
+.\"
+.Dd January 29, 2019
+.Dt RABBITMQ-DIAGNOSTICS 8
+.Os "RabbitMQ Server"
+.Sh NAME
+.Nm rabbitmq-diagnostics
+.Nd RabbitMQ diagnostics, monitoring and health checks tools
+.\" ------------------------------------------------------------------
+.Sh SYNOPSIS
+.\" ------------------------------------------------------------------
+.Nm
+.Op Fl q
+.Op Fl s
+.Op Fl l
+.Op Fl n Ar node
+.Op Fl t Ar timeout
+.Ar command
+.Op Ar command_options
+.\" ------------------------------------------------------------------
+.Sh DESCRIPTION
+.\" ------------------------------------------------------------------
+.Nm
+is a command line tool that provides commands used for diagnostics, monitoring
+and health checks of RabbitMQ nodes.
+See the
+.Lk https://www.rabbitmq.com/documentation.html "RabbitMQ documentation guides"
+to learn more about RabbitMQ diagnostics, monitoring and health checks.
+
+.Nm
+allows the operator to inspect node and cluster state. A number of
+health checks are available to be used interactively and by monitoring tools.
+
+.Pp
+By default if it is not possible to connect to and authenticate with the target node
+(for example if it is stopped), the operation will fail.
+To learn more, see the
+.Lk https://www.rabbitmq.com/monitoring.html "RabbitMQ Monitoring guide"
+.
+.\" ------------------------------------------------------------------
+.Sh OPTIONS
+.\" ------------------------------------------------------------------
+.Bl -tag -width Ds
+.It Fl n Ar node
+Default node is
+.Qq Pf rabbit@ Ar target-hostname ,
+where
+.Ar target-hostname
+is the local host.
+On a host named
+.Qq myserver.example.com ,
+the node name will usually be
+.Qq rabbit@myserver
+(unless
+.Ev RABBITMQ_NODENAME
+has been overridden).
+The output of
+.Qq hostname -s
+is usually the correct suffix to use after the
+.Qq @
+sign.
+See
+.Xr rabbitmq-server 8
+for details of configuring a RabbitMQ node.
+.It Fl q , -quiet
+Quiet output mode is selected.
+Informational messages are reduced when quiet mode is in effect.
+.It Fl s , -silent
+Silent output mode is selected.
+Informational messages are reduced and table headers are suppressed when silent mode is in effect.
+.It Fl t Ar timeout , Fl -timeout Ar timeout
+Operation timeout in seconds.
+Not all commands support timeouts.
+Default is
+.Cm infinity .
+.It Fl l , Fl -longnames
+Must be specified when the cluster is configured to use long (FQDN) node names.
+To learn more, see the
+.Lk https://www.rabbitmq.com/clustering.html "RabbitMQ Clustering guide"
+.It Fl -erlang-cookie Ar cookie
+Shared secret to use to authenticate to the target node.
+Prefer using a local file or the
+.Ev RABBITMQ_ERLANG_COOKIE
+environment variable instead of specifying this option on the command line.
+To learn more, see the
+.Lk https://www.rabbitmq.com/cli.html "RabbitMQ CLI Tools guide"
+.El
+.\" ------------------------------------------------------------------
+.Sh COMMANDS
+.\" ------------------------------------
+.Ss Topology Introspection
+.Pp
+The topology introspection commands list topology entities (e.g. queues) with tab-delimited columns.
+.
+These commands and their arguments are delegated to rabbitmqctl(8).
+.Pp
+Some commands (
+.Cm list_queues ,
+.Cm list_exchanges ,
+.Cm list_bindings
+and
+.Cm list_consumers )
+accept an optional
+.Ar vhost
+parameter.
+.Pp
+The
+.Cm list_queues ,
+.Cm list_exchanges
+and
+.Cm list_bindings
+commands accept an optional virtual host parameter for which to display
+results.
+The default value is
+.Qq / .
+.Bl -tag -width Ds
+.\" ------------------------------------
+.It Cm help
+.Pp
+Displays general help and commands supported by
+.Nm .
+.\" ------------------------------------
+.It Cm ping
+.Pp
+Most basic health check. Succeeds if target node (runtime) is running
+and
+.Nm
+can authenticate with it successfully.
+.\" ------------------------------------
+.It Cm memory_breakdown Op Fl -unit Ar memory_unit
+.Pp
+Displays node's memory usage by category.
+Supported memory units are:
+.Bl -bullet
+.It
+bytes
+.It
+megabytes
+.It
+gigabytes
+.It
+terabytes
+.El
+.Pp
+See
+.Lk https://www.rabbitmq.com/memory-use.html "RabbitMQ Memory Use guide"
+to learn more.
+.Pp
+Example:
+.Sp
+.Dl
+.Nm
+memory_breakdown --unit gigabytes
+.\" ------------------------------------
+.It Cm server_version
+.Pp
+Reports target node's version.
+.Pp
+Example:
+.Sp
+.Dl
+.Nm
+server_version -q
+.\" ------------------------------------
+.It Cm erlang_version
+.Pp
+Reports target node's Erlang/OTP version.
+.Pp
+Example:
+.Sp
+.Dl
+.Nm
+erlang_version -q
+.\" ------------------------------------
+.It Cm maybe_stuck
+.Pp
+Periodically samples stack traces of all Erlang processes
+("lightweight threads") on the node. Reports the processes for which
+stack trace samples are identical.
+.Pp
+Identical samples may indicate that the process is not making any progress
+but is not necessarily an indication of a problem.
+.Pp
+Example:
+.Sp
+.Dl
+.Nm
+maybe_stuck -q
+.\" ------------------------------------
+.It Cm runtime_thread_stats Op Fl -sample-interval Ar interval
+.Pp
+Performs sampling of runtime (kernel) threads' activity for
+.Ar interval
+seconds and reports it.
+.Pp
+For this command to work, Erlang/OTP on the target node must be compiled with
+microstate accounting support and have the runtime_tools package available.
+.Pp
+Example:
+.Sp
+.Dl
+.Nm
+runtime_thread_stats --sample-interval 15
+.\" ------------------------------------
+.It Cm tls_versions
+.Pp
+Lists all TLS versions supported by the runtime on the target node.
+Note that RabbitMQ can be configured to only accept a subset of those
+versions, for example, SSLv3 is disabled by default.
+.Pp
+See
+.Lk https://www.rabbitmq.com/ssl.html "RabbitMQ TLS guide"
+to learn more.
+.Pp
+Example:
+.Sp
+.Dl
+.Nm
+tls_versions -q
+.\" ------------------------------------
+.It Cm erlang_cookie_hash
+.Pp
+Outputs a hashed value of the shared secret used by the target node
+to authenticate CLI tools and peers. The value can be compared with the hash
+found in error messages of CLI tools.
+.Pp
+See
+.Lk https://www.rabbitmq.com/clustering.html#erlang-cookie "RabbitMQ Clustering guide"
+to learn more.
+.Pp
+Example:
+.Sp
+.Dl
+.Nm
+erlang_cookie_hash -q
+.\" ------------------------------------
+.It Cm discover_peers
+.Pp
+Runs a peer discovery on the target node and prints the discovered nodes, if any.
+.Pp
+See
+.Lk https://www.rabbitmq.com/cluster-formation.html "RabbitMQ Cluster Formation guide"
+to learn more.
+.Pp
+Example:
+.Sp
+.Dl
+.Nm
+discover_peers --timeout 60
+.\" ------------------------------------
+.It Cm list_channels Op Ar channelinfoitem ...
+See
+.Cm list_channels
+in
+.Xr rabbitmqctl 8
+.\" ------------------------------------
+.It Cm list_queues Oo Fl p Ar vhost Oc Oo Fl -offline | Fl -online | Fl -local Oc Op Ar queueinfoitem ...
+See
+.Cm list_queues
+in
+.Xr rabbitmqctl 8
+.\" ------------------------------------
+.It Cm list_exchanges Oo Fl p Ar vhost Oc Op Ar exchangeinfoitem ...
+See
+.Cm list_exchanges
+in
+.Xr rabbitmqctl 8
+.\" ------------------------------------
+.It Cm list_bindings Oo Fl p Ar vhost Oc Op Ar bindinginfoitem ...
+See
+.Cm list_bindings
+in
+.Xr rabbitmqctl 8
+.\" ------------------------------------
+.It Cm list_connections Op Ar connectioninfoitem ...
+See
+.Cm list_connections
+in
+.Xr rabbitmqctl 8
+.\" ------------------------------------
+.It Cm list_channels Op Ar channelinfoitem ...
+See
+.Cm list_channels
+in
+.Xr rabbitmqctl 8
+.\" ------------------------------------
+.It Cm list_consumers Op Fl p Ar vhost
+See
+.Cm list_consumers
+in
+.Xr rabbitmqctl 8
+.\" ------------------------------------
+.It Cm alarms
+.Pp
+Lists resource alarms, if any, in the cluster.
+.Pp
+See
+.Lk https://www.rabbitmq.com/alarms.html "RabbitMQ Resource Alarms guide"
+to learn more.
+.Pp
+Example:
+.Sp
+.Dl
+.Nm
+alarms
+.\" ------------------------------------
+.It Cm listeners
+.Pp
+Lists listeners (bound sockets) on this node. Use this to inspect
+what protocols and ports the node is listening on for client, CLI tool
+and peer connections.
+.Pp
+See
+.Lk https://www.rabbitmq.com/networking.html "RabbitMQ Networking guide"
+to learn more.
+.Pp
+Example:
+.Sp
+.Dl
+.Nm
+listeners
+.\" ------------------------------------
+.It Cm is_running
+.Pp
+Reports if RabbitMQ application is fully booted and running (that is, not stopped) on
+the target node.
+.Pp
+Example:
+.Sp
+.Dl
+.Nm
+is_running
+.\" ------------------------------------
+.It Cm is_booting
+.Pp
+Reports if RabbitMQ application is currently booting (not booted/running or stopped) on
+the target node.
+.Pp
+Example:
+.Sp
+.Dl
+.Nm
+is_booting
+.\" ------------------------------------
+
+check_port_connectivity [-t <timeout>]
+.\" ------------------------------------
+.It Cm check_running
+.Pp
+Health check that fails (returns with a non-zero code) if the RabbitMQ
+application is not running on the target node.
+.Pp
+If
+.Cm rabbitmqctl(8)
+was used to stop the application, this check will fail.
+.Pp
+Example:
+.Sp
+.Dl
+.Nm
+check_running
+.\" ------------------------------------
+.It Cm check_local_alarms
+.Pp
+Health check that fails (returns with a non-zero code) if there are alarms
+in effect on the target node.
+.Pp
+See
+.Lk https://www.rabbitmq.com/alarms.html "RabbitMQ Resource Alarms guide"
+to learn more.
+.Pp
+Example:
+.Sp
+.Dl
+.Nm
+check_local_alarms
+.\" ------------------------------------
+.It Cm check_alarms
+.Pp
+Health check that fails (returns with a non-zero code) if there are alarms
+in effect on any of the cluster nodes.
+.Pp
+See
+.Lk https://www.rabbitmq.com/alarms.html "RabbitMQ Resource Alarms guide"
+to learn more.
+.Pp
+Example:
+.Sp
+.Dl
+.Nm
+check_alarms
+.\" ------------------------------------
+.It Cm check_port_connectivity
+.Pp
+Health check that fails (returns with a non-zero code) if any listener ports
+on the target node cannot accept a new TCP connection opened by
+.Nm.
+The check only validates if a new TCP connection is accepted. It does not
+perform messaging protocol handshake or authenticate.
+.Pp
+See
+.Lk https://www.rabbitmq.com/networking.html "RabbitMQ Networking guide"
+to learn more.
+.Pp
+Example:
+.Sp
+.Dl
+.Nm
+check_port_connectivity
+.\" ------------------------------------
+.It Cm check_protocol_listener
+.Pp
+Health check that fails (returns with a non-zero code) if the target node
+does not have a listener for the specified protocol.
+.Pp
+See
+.Lk https://www.rabbitmq.com/networking.html "RabbitMQ Networking guide"
+to learn more.
+.Pp
+Example:
+.Sp
+.Dl
+.Nm
+check_protocol_listener mqtt
+.\" ------------------------------------
+.It Cm check_port_listener
+.Pp
+Health check that fails (returns with a non-zero code) if the target node
+is not listening on the specified port (there is no listener that
+uses that port).
+.Pp
+See
+.Lk https://www.rabbitmq.com/networking.html "RabbitMQ Networking guide"
+to learn more.
+.Pp
+Example:
+.Sp
+.Dl
+.Nm
+check_port_listener 5672
+.\" ------------------------------------
+.It Cm status
+See
+.Cm status
+in
+.Xr rabbitmqctl 8
+.\" ------------------------------------
+.It Cm cluster_status
+See
+.Cm cluster_status
+in
+.Xr rabbitmqctl 8
+.\" ------------------------------------
+.It Cm environment
+See
+.Cm environment
+in
+.Xr rabbitmqctl 8
+.\" ------------------------------------
+.It Cm report
+See
+.Cm report
+in
+.Xr rabbitmqctl 8
+.\" ------------------------------------
+.It Cm list_global_parameters
+See
+.Cm list_global_parameters
+in
+.Xr rabbitmqctl 8
+.\" ------------------------------------
+.It Cm list_operator_policies Op Fl p Ar vhost
+See
+.Cm list_operator_policies
+in
+.Xr rabbitmqctl 8
+.\" ------------------------------------
+.It Cm list_parameters Op Fl p Ar vhost
+See
+.Cm list_parameters
+in
+.Xr rabbitmqctl 8
+.\" ------------------------------------------------------------------
+.It Cm list_permissions Op Fl p Ar vhost
+See
+.Cm list_permissions
+in
+.Xr rabbitmqctl 8
+.\" ------------------------------------
+.It Cm list_policies Op Fl p Ar vhost
+See
+.Cm list_policies
+in
+.Xr rabbitmqctl 8
+.\" ------------------------------------
+.It Cm list_topic_permissions Op Fl p Ar vhost
+See
+.Cm list_topic_permissions
+in
+.Xr rabbitmqctl 8
+.\" ------------------------------------
+.It Cm list_user_permissions Ar username
+See
+.Cm list_user_permissions
+in
+.Xr rabbitmqctl 8
+.\" ------------------------------------
+.It Cm list_user_topic_permissions Ar username
+See
+.Cm list_user_topic_permissions
+in
+.Xr rabbitmqctl 8
+.\" ------------------------------------
+.It Cm list_users
+See
+.Cm list_users
+in
+.Xr rabbitmqctl 8
+.\" ------------------------------------
+.It Cm list_vhosts Op Ar vhostinfoitem ...
+See
+.Cm list_vhosts
+in
+.Xr rabbitmqctl 8
+.\" ------------------------------------
+.It Cm node_health_check
+Performs several health checks of the target node.
+.Pp
+Verifies the rabbit application is running and alarms are not set,
+then checks that every queue and channel on the node can emit basic stats.
+.Pp
+Example:
+.Sp
+.Dl
+.Nm
+node_health_check -n rabbit@hostname
+.\" ------------------------------------
diff --git a/docs/rabbitmq-plugins.8 b/docs/rabbitmq-plugins.8
index d68bdc8044..4d0d86150e 100644
--- a/docs/rabbitmq-plugins.8
+++ b/docs/rabbitmq-plugins.8
@@ -19,7 +19,7 @@
 .Os "RabbitMQ Server"
 .Sh NAME
 .Nm rabbitmq-plugins
-.Nd command line for managing RabbitMQ plugins
+.Nd command line tool for managing RabbitMQ plugins
 .\" ------------------------------------------------------------------
 .Sh SYNOPSIS
 .\" ------------------------------------------------------------------
@@ -63,8 +63,8 @@ and
 .Cm set
 commands will update the plugins file and then attempt to connect to the
 broker and ensure it is running all enabled plugins.
-By default if it is not possible to connect to the running broker (for
-example if it is stopped) the operation will fail.
+By default if it is not possible to connect to and authenticate with the target node
+(for example if it is stopped), the operation will fail.
 If
 .Nm
 is used on the same host as the target node,
@@ -249,11 +249,12 @@ plugin and its dependencies and disables everything else:
 .\" ------------------------------------------------------------------
 .Sh SEE ALSO
 .\" ------------------------------------------------------------------
-.Xr rabbitmq-env.conf 5 ,
-.Xr rabbitmq-echopid 8 ,
+.Xr rabbitmqctl 8 ,
+.Xr rabbitmq-diagnostics 8 ,
 .Xr rabbitmq-server 8 ,
 .Xr rabbitmq-service 8 ,
-.Xr rabbitmqctl 8
+.Xr rabbitmq-env.conf 5 ,
+.Xr rabbitmq-echopid 8
 .\" ------------------------------------------------------------------
 .Sh AUTHOR
 .\" ------------------------------------------------------------------
diff --git a/docs/rabbitmq-server.8 b/docs/rabbitmq-server.8
index 8882ce62c7..87c6e7c531 100644
--- a/docs/rabbitmq-server.8
+++ b/docs/rabbitmq-server.8
@@ -41,7 +41,7 @@ To shut down the server, use service management tools or
 .\" ------------------------------------------------------------------
 .Bl -tag -width Ds
 .It Ev RABBITMQ_CONFIG_FILE
-Defaults to 
+Defaults to
 .Pa /etc/rabbitmq/rabbitmq.conf .
 Node configuration file path.
 To learn more, see the
@@ -93,11 +93,12 @@ For example, runs RabbitMQ AMQP server in the background:
 .\" ------------------------------------------------------------------
 .Sh SEE ALSO
 .\" ------------------------------------------------------------------
-.Xr rabbitmq-env.conf 5 ,
-.Xr rabbitmq-echopid 8 ,
+.Xr rabbitmqctl 8 ,
+.Xr rabbitmq-diagnostics 8 ,
 .Xr rabbitmq-plugins 8 ,
 .Xr rabbitmq-service 8 ,
-.Xr rabbitmqctl 8
+.Xr rabbitmq-env.conf 5 ,
+.Xr rabbitmq-echopid 8
 .\" ------------------------------------------------------------------
 .Sh AUTHOR
 .\" ------------------------------------------------------------------
diff --git a/docs/rabbitmq-service.8 b/docs/rabbitmq-service.8
index fd01bbb814..f9c5588435 100644
--- a/docs/rabbitmq-service.8
+++ b/docs/rabbitmq-service.8
@@ -147,10 +147,12 @@ is to discard the server output.
 .\" ------------------------------------------------------------------
 .Sh SEE ALSO
 .\" ------------------------------------------------------------------
-.Xr rabbitmq-echopid 8 ,
+.Xr rabbitmqctl 8 ,
+.Xr rabbitmq-diagnostics 8 ,
 .Xr rabbitmq-plugins 8 ,
 .Xr rabbitmq-server 8 ,
-.Xr rabbitmqctl 8
+.Xr rabbitmq-env.conf 5 ,
+.Xr rabbitmq-echopid 8
 .\" ------------------------------------------------------------------
 .Sh AUTHOR
 .\" ------------------------------------------------------------------
diff --git a/docs/rabbitmqctl.8 b/docs/rabbitmqctl.8
index e556a7f979..6c08655acd 100644
--- a/docs/rabbitmqctl.8
+++ b/docs/rabbitmqctl.8
@@ -204,7 +204,7 @@ will be completed when this command returns.
 Shuts down the node, both RabbitMQ and its runtime.
 The command is blocking and will return after the runtime process exits.
 If RabbitMQ fails to stop, it will return a non-zero exit code.
-This command infers the process pid of the target node and
+This command infers the OS PID of the target node and
 therefore can only be used to shut down nodes running on the same
 host (or broadly speaking, in the same operating system,
 e.g. in the same VM or container)
@@ -812,12 +812,12 @@ For example, this command instructs the RabbitMQ broker to grant the
 user named
 .Qq janeway
 access to the virtual host called
-.Qq /myvhost ,
+.Qq my-vhost ,
 with configure permissions on all resources whose names starts with
 .Qq janeway- ,
 and write and read permissions on all resources:
 .sp
-.Dl rabbitmqctl set_permissions -p /myvhost janeway Qo ^janeway-.* Qc Qo .* Qc Qq .*
+.Dl rabbitmqctl set_permissions -p my-vhost janeway Qo ^janeway-.* Qc Qo .* Qc Qq .*
 .\" ------------------------------------
 .It Cm clear_permissions Oo Fl p Ar vhost Oc Ar username
 .Bl -tag -width Ds
@@ -835,9 +835,9 @@ For example, this command instructs the RabbitMQ broker to deny the user
 named
 .Qq janeway
 access to the virtual host called
-.Qq /myvhost :
+.Qq my-vhost :
 .sp
-.Dl rabbitmqctl clear_permissions -p /myvhost janeway
+.Dl rabbitmqctl clear_permissions -p my-vhost janeway
 .\" ------------------------------------
 .It Cm list_permissions Op Fl p Ar vhost
 .Bl -tag -width Ds
@@ -852,12 +852,12 @@ Lists permissions in a virtual host.
 .Pp
 For example, this command instructs the RabbitMQ broker to list all the
 users which have been granted access to the virtual host called
-.Qq /myvhost ,
+.Qq my-vhost ,
 and the permissions they have for operations on resources in that
 virtual host.
 Note that an empty string means no permissions granted:
 .sp
-.Dl rabbitmqctl list_permissions -p /myvhost
+.Dl rabbitmqctl list_permissions -p my-vhost
 .\" ------------------------------------
 .It Cm list_user_permissions Ar username
 .Bl -tag -width Ds
@@ -899,18 +899,18 @@ user named
 publish and consume messages going through the
 .Qq amp.topic
 exchange of the
-.Qq /myvhost
+.Qq my-vhost
 virtual host with a routing key starting with
 .Qq janeway- :
 .sp
-.Dl rabbitmqctl set_topic_permissions -p /myvhost janeway amq.topic Qo ^janeway-.* Qc Qo ^janeway-.* Qc
+.Dl rabbitmqctl set_topic_permissions -p my-vhost janeway amq.topic Qo ^janeway-.* Qc Qo ^janeway-.* Qc
 .Pp
 Topic permissions support variable expansion for the following variables:
 username, vhost, and client_id. Note that client_id is expanded only when using MQTT.
 The previous example could be made more generic by using
 .Qq ^{username}-.* :
 .sp
-.Dl rabbitmqctl set_topic_permissions -p /myvhost janeway amq.topic Qo ^{username}-.* Qc Qo ^{username}-.* Qc
+.Dl rabbitmqctl set_topic_permissions -p my-vhost janeway amq.topic Qo ^{username}-.* Qc Qo ^{username}-.* Qc
 .\" ------------------------------------
 .It Cm clear_topic_permissions Oo Fl p Ar vhost Oc Ar username Oo Ar exchange Oc
 .Bl -tag -width Ds
@@ -933,9 +933,9 @@ named
 for the topic exchange
 .Qq amq.topic
 in the virtual host called
-.Qq /myvhost :
+.Qq my-vhost :
 .sp
-.Dl rabbitmqctl clear_topic_permissions -p /myvhost janeway amq.topic
+.Dl rabbitmqctl clear_topic_permissions -p my-vhost janeway amq.topic
 .\" ------------------------------------
 .It Cm list_topic_permissions Op Fl p Ar vhost
 .Bl -tag -width Ds
@@ -949,9 +949,9 @@ Lists topic permissions in a virtual host.
 .Pp
 For example, this command instructs the RabbitMQ broker to list all the
 users which have been granted topic permissions in the virtual host called
-.Qq /myvhost:
+.Qq my-vhost:
 .sp
-.Dl rabbitmqctl list_topic_permissions -p /myvhost
+.Dl rabbitmqctl list_topic_permissions -p my-vhost
 .\" ------------------------------------
 .It Cm list_user_topic_permissions Ar username
 .Bl -tag -width Ds
@@ -1230,10 +1230,9 @@ Suppresses the
 parameter.
 .El
 .El
-.Ss Server Status
-The server status queries interrogate the server and return a list of
-results with tab-delimited columns.
-Some queries (
+.Ss Topology Introspection
+The topology introspection commands list topology entities (e.g. queues) with tab-delimited columns.
+Some commands (
 .Cm list_queues ,
 .Cm list_exchanges ,
 .Cm list_bindings
@@ -1242,8 +1241,6 @@ and
 accept an optional
 .Ar vhost
 parameter.
-This parameter, if present, must be specified immediately after the
-query.
 .Pp
 The
 .Cm list_queues ,
@@ -1399,9 +1396,9 @@ are specified then queue name and depth are displayed.
 .Pp
 For example, this command displays the depth and number of consumers for
 each queue of the virtual host named
-.Qq /myvhost
+.Qq my-vhost
 .sp
-.Dl rabbitmqctl list_queues -p /myvhost messages consumers
+.Dl rabbitmqctl list_queues -p my-vhost messages consumers
 .\" ------------------------------------
 .It Cm list_exchanges Oo Fl p Ar vhost Oc Op Ar exchangeinfoitem ...
 Returns exchange details.
@@ -1455,9 +1452,9 @@ are specified then exchange name and type are displayed.
 .Pp
 For example, this command displays the name and type for each exchange
 of the virtual host named
-.Qq /myvhost :
+.Qq my-vhost :
 .sp
-.Dl rabbitmqctl list_exchanges -p /myvhost name type
+.Dl rabbitmqctl list_exchanges -p my-vhost name type
 .\" ------------------------------------
 .It Cm list_bindings Oo Fl p Ar vhost Oc Op Ar bindinginfoitem ...
 Returns binding details.
@@ -1503,9 +1500,9 @@ are specified then all above items are displayed.
 .Pp
 For example, this command displays the exchange name and queue name of
 the bindings in the virtual host named
-.Qq /myvhost
+.Qq my-vhost
 .sp
-.Dl rabbitmqctl list_bindings -p /myvhost exchange_name queue_name
+.Dl rabbitmqctl list_bindings -p my-vhost exchange_name queue_name
 .\" ------------------------------------
 .It Cm list_connections Op Ar connectioninfoitem ...
 Returns TCP/IP connection statistics.
@@ -1711,13 +1708,13 @@ broker:
 .Dl rabbitmqctl status
 .\" ------------------------------------
 .It Cm node_health_check
-Health check of the RabbitMQ node.
-Verifies the rabbit application is running, list_queues and
-list_channels return, and alarms are not set.
+Performs several health checks of the target node.
 .Pp
-For example, this command performs a health check on the RabbitMQ node:
+Verifies the rabbit application is running and alarms are not set,
+then checks that every queue and channel on the node can emit basic stats.
 .sp
-.Dl rabbitmqctl node_health_check -n rabbit@stringer
+Example:
+.Dl rabbitmqctl node_health_check -n rabbit@hostname
 .\" ------------------------------------
 .It Cm environment
 Displays the name and value of each variable in the application
@@ -2227,11 +2224,12 @@ Reset stats database for all nodes in the cluster.
 .\" ------------------------------------------------------------------
 .Sh SEE ALSO
 .\" ------------------------------------------------------------------
-.Xr rabbitmq-env.conf 5 ,
-.Xr rabbitmq-echopid 8 ,
+.Xr rabbitmq-diagnostics 8 ,
 .Xr rabbitmq-plugins 8 ,
 .Xr rabbitmq-server 8 ,
-.Xr rabbitmq-service 8
+.Xr rabbitmq-service 8 ,
+.Xr rabbitmq-env.conf 5 ,
+.Xr rabbitmq-echopid 8
 .\" ------------------------------------------------------------------
 .Sh AUTHOR
 .\" ------------------------------------------------------------------