diff options
Diffstat (limited to 'deps/rabbit/docs/rabbitmq-diagnostics.8')
| -rw-r--r-- | deps/rabbit/docs/rabbitmq-diagnostics.8 | 725 |
1 files changed, 725 insertions, 0 deletions
diff --git a/deps/rabbit/docs/rabbitmq-diagnostics.8 b/deps/rabbit/docs/rabbitmq-diagnostics.8 new file mode 100644 index 0000000000..7a6d53d097 --- /dev/null +++ b/deps/rabbit/docs/rabbitmq-diagnostics.8 @@ -0,0 +1,725 @@ +.\" vim:ft=nroff: +.\" This Source Code Form is subject to the terms of the Mozilla Public +.\" License, v. 2.0. If a copy of the MPL was not distributed with this +.\" file, You can obtain one at https://mozilla.org/MPL/2.0/. +.\" +.\" Copyright (c) 2007-2020 VMware, Inc. or its affiliates. All rights reserved. +.\" +.Dd September 28, 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://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://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://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://rabbitmq.com/cli.html "RabbitMQ CLI Tools guide" +.El +.\" ------------------------------------------------------------------ +.Sh COMMANDS +.\" ------------------------------------ +.Pp +Most commands provided by +.Nm +inspect node and cluster state or perform health checks. +.Pp +Commands that list topology entities (e.g. queues) use tab as column delimiter. +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 / . +.El +.Ss Help +.Bl -tag -width Ds +.\" ------------------------------------ +.Bl -tag -width Ds +.It Cm help Oo Fl l Oc Op Ar command_name +.Pp +Prints usage for all available commands. +.Bl -tag -width Ds +.It Fl l , Fl -list-commands +List command usages only, without parameter explanation. +.It Ar command_name +Prints usage for the specified command. +.El +.\" ------------------------------------ +.It Cm version +.Pp +Displays CLI tools version +.El +.Ss Nodes +.Bl -tag -width Ds +.\" ------------------------------------ +.It Cm wait +.Pp +See +.Cm wait +in +.Xr rabbitmqctl 8 +.El +.Ss Cluster +.Bl -tag -width Ds +.\" ------------------------------------ +.It Cm cluster_status +.Pp +See +.Cm cluster_status +in +.Xr rabbitmqctl 8 +.El +.Ss Users +.Bl -tag -width Ds +.\" ------------------------------------ +.It Cm list_users +.Pp +See +.Cm list_users +in +.Xr rabbitmqctl 8 +.El +.Ss Access Control +.Bl -tag -width Ds +.\" ------------------------------------ +.It Cm list_permissions Op Fl p Ar vhost +.Pp +See +.Cm list_permissions +in +.Xr rabbitmqctl 8 +.\" ------------------------------------ +.It Cm list_topic_permissions Op Fl p Ar vhost +.Pp +See +.Cm list_topic_permissions +in +.Xr rabbitmqctl 8 +.\" ------------------------------------ +.It Cm list_user_permissions Ar username +.Pp +See +.Cm list_user_permissions +in +.Xr rabbitmqctl 8 +.\" ------------------------------------ +.It Cm list_user_topic_permissions Ar username +.Pp +See +.Cm list_user_topic_permissions +in +.Xr rabbitmqctl 8 +.\" ------------------------------------ +.It Cm list_vhosts Op Ar vhostinfoitem ... +.Pp +See +.Cm list_vhosts +in +.Xr rabbitmqctl 8 +.El +.Ss Monitoring, observability and health checks +.Bl -tag -width Ds +.\" ------------------------------------ +.It Cm alarms +.Pp +Lists resource alarms, if any, in the cluster. +.Pp +See +.Lk https://rabbitmq.com/alarms.html "RabbitMQ Resource Alarms guide" +to learn more. +.Pp +Example: +.Sp +.Dl rabbitmq-diagnostics alarms +.\" ------------------------------------ +.It Cm certificates +.Pp +Displays the node certificates for every listener on target node that is configured to use TLS. +.Pp +Example: +.sp +.Dl rabbitmq-diagnostics certificates +.\" ------------------------------------ +.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://rabbitmq.com/alarms.html "RabbitMQ Resource Alarms guide" +to learn more. +.Pp +Example: +.Sp +.Dl rabbitmq-diagnostics check_alarms +.\" ------------------------------------ +.It Cm check_certificate_expiration Oo Fl -unit Ar time_unit Oc Op Fl -within Ar seconds +.Pp +Checks the expiration date on the certificates for every listener on target node that is configured to use TLS. +Supported time units are: +.Bl -bullet +.It +days +.It +weeks +.It +months +.It +years +.El +.Pp +Example: +.Sp +.Dl rabbitmq-diagnostics check_certificate_expiration --unit weeks --within 6 +.\" ------------------------------------ +.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://rabbitmq.com/alarms.html "RabbitMQ Resource Alarms guide" +to learn more. +.Pp +Example: +.Sp +.Dl rabbitmq-diagnostics check_local_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 +.Pp +The check only validates if a new TCP connection is accepted. It does not +perform messaging protocol handshake or authenticate. +.Pp +See +.Lk https://rabbitmq.com/networking.html "RabbitMQ Networking guide" +to learn more. +.Pp +Example: +.Sp +.Dl rabbitmq-diagnostics check_port_connectivity +.\" ------------------------------------ +.It Cm check_port_listener Ar port +.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://rabbitmq.com/networking.html "RabbitMQ Networking guide" +to learn more. +.Pp +Example: +.Sp +.Dl rabbitmq-diagnostics check_port_listener 5672 +.\" ------------------------------------ +.It Cm check_protocol_listener Ar protocol +.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://rabbitmq.com/networking.html "RabbitMQ Networking guide" +to learn more. +.Pp +Example: +.Sp +.Dl rabbitmq-diagnostics check_protocol_listener mqtt +.\" ------------------------------------ +.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 rabbitmq-diagnostics check_running +.\" ------------------------------------ +.It Cm check_virtual_hosts +.Pp +Health check that checks if all vhosts are running in the target node +.Pp +Example: +.Sp +.Dl rabbitmq-diagnostics check_virtual_hosts --timeout 60 +.\" ------------------------------------ +.It Cm cipher_suites +.Pp +Lists cipher suites enabled by default. To list all available cipher suites, add the --all argument. +.Pp +Example: +.Sp +.Dl rabbitmq-diagnostics cipher_suites --format openssl --all +.\" ------------------------------------ +.It Cm command_line_arguments +.Pp +Displays target node's command-line arguments and flags as reported by the runtime. +.Pp +Example: +.Sp +.Dl rabbitmq-diagnostics command_line_arguments -n rabbit@hostname +.\" ------------------------------------ +.It Cm consume_event_stream Oo Fl -duration Ar seconds | Fl d Ar seconds Oc Oo Fl -pattern Ar pattern Oc Op Fl -timeout Ar milliseconds +.Pp +Streams internal events from a running node. Output is jq-compatible. +.Pp +Example: +.Sp +.Dl rabbitmq-diagnostics consume_event_stream -n rabbit@hostname --duration 20 --pattern "queue_.*" +.\" ------------------------------------ +.It Cm discover_peers +.Pp +Runs a peer discovery on the target node and prints the discovered nodes, if any. +.Pp +See +.Lk https://rabbitmq.com/cluster-formation.html "RabbitMQ Cluster Formation guide" +to learn more. +.Pp +Example: +.Sp +.Dl rabbitmq-diagnostics discover_peers --timeout 60 +.\" ------------------------------------ +.It Cm environment +See +.Cm environment +in +.Xr rabbitmqctl 8 +.\" ------------------------------------ +.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://rabbitmq.com/clustering.html#erlang-cookie "RabbitMQ Clustering guide" +to learn more. +.Pp +Example: +.Sp +.Dl rabbitmq-diagnostics erlang_cookie_hash -q +.\" ------------------------------------ +.It Cm erlang_version +.Pp +Reports target node's Erlang/OTP version. +.Pp +Example: +.Sp +.Dl rabbitmq-diagnostics erlang_version -q +.\" ------------------------------------ +.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 rabbitmq-diagnostics is_booting +.\" ------------------------------------ +.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 rabbitmq-diagnostics is_running +.\" ------------------------------------ +.It Cm list_bindings Oo Fl p Ar vhost Oc Op Ar bindinginfoitem ... +.Pp +See +.Cm list_bindings +in +.Xr rabbitmqctl 8 +.\" ------------------------------------ +.It Cm list_channels Op Ar channelinfoitem ... +.Pp +See +.Cm list_channels +in +.Xr rabbitmqctl 8 +.\" ------------------------------------ +.It Cm list_ciphers +.Pp +See +.Cm list_ciphers +in +.Xr rabbitmqctl 8 +.\" ------------------------------------ +.It Cm list_connections Op Ar connectioninfoitem ... +.Pp +See +.Cm list_connections +in +.Xr rabbitmqctl 8 +.\" ------------------------------------ +.It Cm list_consumers Op Fl p Ar vhost +.Pp +See +.Cm list_consumers +in +.Xr rabbitmqctl 8 +.\" ------------------------------------ +.It Cm list_exchanges Oo Fl p Ar vhost Oc Op Ar exchangeinfoitem ... +.Pp +See +.Cm list_exchanges +in +.Xr rabbitmqctl 8 +.\" ------------------------------------ +.It Cm list_hashes +.Pp +See +.Cm list_hashes +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 ... +.Pp +See +.Cm list_queues +in +.Xr rabbitmqctl 8 +.\" ------------------------------------ +.It Cm list_unresponsive_queues Oc Oo Fl -local Oc Oo Fl -queue-timeout Ar milliseconds Oc Oo Ar column ... Oc Op Fl -no-table-headers +.Pp +See +.Cm list_unresponsive_queues +in +.Xr rabbitmqctl 8 +.\" ------------------------------------ +.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://rabbitmq.com/networking.html "RabbitMQ Networking guide" +to learn more. +.Pp +Example: +.Sp +.Dl rabbitmq-diagnostics listeners +.\" ------------------------------------ +.It Cm log_tail Fl -number Ar number | Fl N Ar number Op Fl -timeout Ar milliseconds +.Pp +Prints the last N lines of the log on the node +.Pp +Example: +.Sp +.Dl rabbitmq-diagnostics log_tail -number 100 +.\" ------------------------------------ +.It Cm log_tail_stream Oo Fl -duration Ar seconds | Fl d Ar seconds Oc Op Fl -timeout Ar milliseconds +.Pp +Streams logs from a running node for a period of time +.Pp +Example: +.Sp +.Dl rabbitmq-diagnostics log_tail_stream --duration 60 +.\" ------------------------------------ +.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 rabbitmq-diagnostics maybe_stuck -q +.\" ------------------------------------ +.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://rabbitmq.com/memory-use.html "RabbitMQ Memory Use guide" +to learn more. +.Pp +Example: +.sp +.Dl rabbitmq-diagnostics memory_breakdown --unit gigabytes +.\" ------------------------------------ +.It Cm observer Op Fl -interval Ar seconds +.Pp +Starts a CLI observer interface on the target node +.Pp +Example: +.Sp +.Dl rabbitmq-diagnostics observer --interval 10 +.\" ------------------------------------ +.It Cm ping +.Pp +Most basic health check. Succeeds if target node (runtime) is running +and +.Nm +can authenticate with it successfully. +.\" ------------------------------------ +.It Cm report +.Pp +See +.Cm report +in +.Xr rabbitmqctl 8 +.\" ------------------------------------ +.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 rabbitmq-diagnostics runtime_thread_stats --sample-interval 15 +.\" ------------------------------------ +.It Cm schema_info Oo Fl -no_table_headers Oc Oo Ar column ... Oc Op Fl -timeout Ar milliseconds +.Pp +See +.Cm schema_info +in +.Xr rabbitmqctl 8 +.\" ------------------------------------ +.It Cm server_version +.Pp +Reports target node's version. +.Pp +Example: +.Sp +.Dl rabbitmq-diagnostics server_version -q +.\" ------------------------------------ +.It Cm status +.Pp +See +.Cm status +in +.Xr rabbitmqctl 8 +.\" ------------------------------------ +.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://rabbitmq.com/ssl.html "RabbitMQ TLS guide" +to learn more. +.Pp +Example: +.Sp +.Dl rabbitmq-diagnostics tls_versions -q +.El +.Ss Parameters +.Bl -tag -width Ds +.\" ------------------------------------ +.It Cm list_global_parameters +.Pp +See +.Cm list_global_parameters +in +.Xr rabbitmqctl 8 +.\" ------------------------------------ +.It Cm list_parameters Op Fl p Ar vhost +.Pp +See +.Cm list_parameters +in +.Xr rabbitmqctl 8 +.El +.Ss Policies +.Bl -tag -width Ds +.\" ------------------------------------ +.It Cm list_operator_policies Op Fl p Ar vhost +.Pp +See +.Cm list_operator_policies +in +.Xr rabbitmqctl 8 +.\" ------------------------------------ +.It Cm list_policies Op Fl p Ar vhost +.Pp +See +.Cm list_policies +in +.Xr rabbitmqctl 8 +.\" ------------------------------------ +.El +.Ss Virtual hosts +.Bl -tag -width Ds +.\" ------------------------------------ +.It Cm list_vhost_limits Oo Fl -vhost Ar vhost Oc Oo Fl -global Oc Op Fl -no-table-headers +.Pp +See +.Cm list_vhost_limits +in +.Xr rabbitmqctl 8 +.El +.Ss Node configuration +.Bl -tag -width Ds +.\" ------------------------------------ +.It Cm log_location Oo Fl -all | Fl a Oc Op Fl -timeout Ar milliseconds +.Pp +Shows log file location(s) on target node +.Pp +Example: +.Sp +.Dl rabbitmq-diagnostics log_location -a +.El +.Ss Feature flags +.Bl -tag -width Ds +.\" ------------------------------------ +.It Cm list_feature_flags Oo Ar column ... Oc Op Fl -timeout Ar milliseconds +.Pp +See +.Cm list_feature_flags +in +.Xr rabbitmqctl 8 +.El +.Ss Queues +.Bl -tag -width Ds +.\" ------------------------------------ +.It Cm quorum_status Ar queue Op Fl -vhost Ar vhost +.Pp +See +.Cm quorum_status +in +.Xr rabbitmq-queues 8 +.It Cm check_if_node_is_mirror_sync_critical +.Pp +See +.Cm check_if_node_is_mirror_sync_critical +in +.Xr rabbitmq-queues 8 +.It Cm check_if_node_is_quorum_critical +.Pp +See +.Cm check_if_node_is_quorum_critical +in +.Xr rabbitmq-queues 8 +.\" ------------------------------------------------------------------ +.Sh SEE ALSO +.\" ------------------------------------------------------------------ +.Xr rabbitmqctl 8 , +.Xr rabbitmq-server 8 , +.Xr rabbitmq-queues 8 , +.Xr rabbitmq-upgrade 8 , +.Xr rabbitmq-service 8 , +.Xr rabbitmq-env.conf 5 , +.Xr rabbitmq-echopid 8 +.\" ------------------------------------------------------------------ +.Sh AUTHOR +.\" ------------------------------------------------------------------ +.An The RabbitMQ Team Aq Mt info@rabbitmq.com |