451 lines
14 KiB
Groff
451 lines
14 KiB
Groff
.\" 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-2023 Broadcom. All Rights Reserved. The term “Broadcom” refers to Broadcom Inc. and/or its subsidiaries. All rights reserved.
|
|
.\"
|
|
.Dd June 22, 2023
|
|
.Dt RABBITMQ-STREAMS 8
|
|
.Os "RabbitMQ Server"
|
|
.Sh NAME
|
|
.Nm rabbitmq-streams
|
|
.Nd RabbitMQ stream management 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 to manage streams,
|
|
for example, add or delete stream replicas.
|
|
See the
|
|
.Lk https://www.rabbitmq.com/streams.html "RabbitMQ streams overview".
|
|
.\" ------------------------------------------------------------------
|
|
.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
|
|
.\" ------------------------------------
|
|
.Bl -tag -width Ds
|
|
.\" ------------------------------------
|
|
.It Cm help
|
|
.Pp
|
|
Displays general help and commands supported by
|
|
.Nm .
|
|
.El
|
|
.Ss Replication
|
|
.Bl -tag -width Ds
|
|
.\" ------------------------------------
|
|
.It Cm add_replica Ar queue Ar node Fl -vhost Ar virtual-host
|
|
.Pp
|
|
Adds a stream replica on the given node.
|
|
.Pp
|
|
Example:
|
|
.Sp
|
|
.Dl rabbitmq-streams add_replica --vhost Qo a-vhost Qc Qo a-queue Qc Qo rabbit@new-node Qc
|
|
.\" ------------------------------------
|
|
.It Cm delete_replica Ar queue Ar node Fl -vhost Ar virtual-host
|
|
.Pp
|
|
Removes a stream replica on the given node.
|
|
.Pp
|
|
Example:
|
|
.Sp
|
|
.Dl rabbitmq-streams delete_replica --vhost Qo a-vhost Qc Qo a-queue Qc Qo rabbit@decomissioned-node Qc
|
|
.\" ------------------------------------
|
|
.El
|
|
.Ss Monitoring, observability and health checks
|
|
.Bl -tag -width Ds
|
|
.\" ------------------------------------
|
|
.It Cm stream_status Ar stream Fl -vhost Ar virtual-host
|
|
.Pp
|
|
Displays the status of a stream.
|
|
.Pp
|
|
Example:
|
|
.Sp
|
|
.Dl rabbitmq-streams stream_status --vhost Qo a-vhost Qc Qo a-stream Qc
|
|
.\" ------------------------------------
|
|
.It Cm restart_stream Ar stream Fl -vhost Ar virtual-host Fl --preferred-leader-node Ar node
|
|
.Pp
|
|
Restarts a stream including all of it's replicas. The optional preferred
|
|
node flag instructs the command to try to place the leader on a specific node during the restart.
|
|
.Pp
|
|
Example:
|
|
.Sp
|
|
.Dl rabbitmq-streams restart_stream --vhost Qo a-vhost Qc Qo a-stream Qc --preferred-leader-node Qo node
|
|
.\" ------------------------------------
|
|
.El
|
|
.Ss Policies
|
|
.Bl -tag -width Ds
|
|
.\" ------------------------------------
|
|
.It Cm set_stream_retention_policy Ar stream Ar policy Fl -vhost Ar virtual-host
|
|
.Pp
|
|
Set the retention policy of a stream.
|
|
.Pp
|
|
Example:
|
|
.Sp
|
|
.Dl rabbitmq-streams set_stream_retention_policy --vhost Qo a-vhost Qc Qo a-stream Qc Qo a-policy Qc
|
|
.\" ------------------------------------
|
|
.El
|
|
.Ss Stream plugin
|
|
.Bl -tag -width Ds
|
|
.\" ------------------------------------------------------------------
|
|
.It Cm list_stream_connections Op Ar connectioninfoitem ...
|
|
.Pp
|
|
Returns stream protocol connection statistics.
|
|
.Pp
|
|
The
|
|
.Ar connectioninfoitem
|
|
parameter is used to indicate which connection information items to
|
|
include in the results.
|
|
The column order in the results will match the order of the parameters.
|
|
.Ar connectioninfoitem
|
|
can take any value from the list that follows:
|
|
.Bl -tag -width Ds
|
|
.It Cm auth_mechanism
|
|
SASL authentication mechanism used, such as
|
|
.Qq PLAIN .
|
|
.It Cm client_properties
|
|
Informational properties transmitted by the client during connection
|
|
establishment.
|
|
.It Cm conn_name
|
|
Readable name for the connection.
|
|
.It Cm connected_at
|
|
Date and time this connection was established, as timestamp.
|
|
.It Cm connection_state
|
|
Connection state; one of:
|
|
.Bl -bullet -compact
|
|
.It
|
|
running
|
|
.It
|
|
blocked
|
|
.El
|
|
.It Cm frame_max
|
|
Maximum frame size (bytes).
|
|
.It Cm heartbeat
|
|
Negotiated heartbeat interval, in seconds.
|
|
.It Cm host
|
|
Server hostname obtained via reverse DNS, or its IP address if reverse
|
|
DNS failed or was disabled.
|
|
.It Cm peer_cert_issuer
|
|
The issuer of the peer's SSL certificate, in RFC4514 form.
|
|
.It Cm peer_cert_subject
|
|
The subject of the peer's SSL certificate, in RFC4514 form.
|
|
.It Cm peer_cert_validity
|
|
The period for which the peer's SSL certificate is valid.
|
|
.It Cm peer_host
|
|
Peer hostname obtained via reverse DNS, or its IP address if reverse DNS
|
|
failed or was not enabled.
|
|
.It Cm peer_port
|
|
Peer port.
|
|
.It Cm port
|
|
Server port.
|
|
.It Cm ssl
|
|
Boolean indicating whether the connection is secured with SSL.
|
|
.It Cm ssl_cipher
|
|
SSL cipher algorithm (e.g.\&
|
|
.Qq aes_256_cbc ) .
|
|
.It Cm ssl_hash
|
|
SSL hash function (e.g.\&
|
|
.Qq sha ) .
|
|
.It Cm ssl_key_exchange
|
|
SSL key exchange algorithm (e.g.\&
|
|
.Qq rsa ) .
|
|
.It Cm ssl_protocol
|
|
SSL protocol (e.g.\&
|
|
.Qq tlsv1 ) .
|
|
.It Cm subscriptions
|
|
Number of subscriptions (consumers) on the connection.
|
|
.It Cm user
|
|
Username associated with the connection.
|
|
.It Cm vhost
|
|
Virtual host name with non-ASCII characters escaped as in C.
|
|
.El
|
|
.Pp
|
|
If no
|
|
.Ar connectioninfoitem
|
|
are specified then only conn_name is displayed.
|
|
.Pp
|
|
For example, this command displays the connection name and user
|
|
for each connection:
|
|
.sp
|
|
.Dl rabbitmq-streams list_stream_connections conn_name user
|
|
.\" ------------------------------------------------------------------
|
|
.It Cm list_stream_consumers Oo Fl p Ar vhost Oc Op Ar consumerinfoitem ...
|
|
.Pp
|
|
Returns consumers attached to a stream.
|
|
.Pp
|
|
The
|
|
.Ar consumerinfoitem
|
|
parameter is used to indicate which consumer information items to
|
|
include in the results.
|
|
The column order in the results will match the order of the parameters.
|
|
.Ar consumerinfoitem
|
|
can take any value from the list that follows:
|
|
.Bl -tag -width Ds
|
|
.It Ar active
|
|
Boolean indicating whether the consumer is active or not.
|
|
.It Ar activity_status
|
|
Consumer activity status; one of:
|
|
.Bl -bullet -compact
|
|
.It
|
|
up
|
|
.It
|
|
single_active
|
|
.It
|
|
waiting
|
|
.El
|
|
.It Ar connection_pid
|
|
Id of the Erlang process associated with the consumer connection.
|
|
.It Ar credits
|
|
Available credits for the consumer.
|
|
.It Ar messages_consumed
|
|
Number of messages the consumer consumed.
|
|
.It Ar offset
|
|
The offset (location in the stream) the consumer is at.
|
|
.It Ar offset_lag
|
|
The difference between the last stored offset and the last
|
|
dispatched offset for the consumer.
|
|
.It Ar properties
|
|
The properties of the consumer subscription.
|
|
.It Ar stream
|
|
The stream the consumer is attached to.
|
|
.It Ar subscription_id
|
|
The connection-scoped ID of the consumer.
|
|
.El
|
|
.Pp
|
|
If no
|
|
.Ar consumerinfoitem
|
|
are specified then connection_pid, subscription_id, stream,
|
|
messages_consumed, offset, offset_lag, credits, active, activity_status, and properties are displayed.
|
|
.Pp
|
|
For example, this command displays the connection PID, subscription ID and stream
|
|
for each consumer:
|
|
.sp
|
|
.Dl rabbitmq-streams list_stream_consumers connection_pid subscription_id stream
|
|
\" ------------------------------------------------------------------
|
|
.It Cm list_stream_publishers Oo Fl p Ar vhost Oc Op Ar publisherinfoitem ...
|
|
.Pp
|
|
Returns registered publishers.
|
|
.Pp
|
|
The
|
|
.Ar publisherinfoitem
|
|
parameter is used to indicate which publisher information items to
|
|
include in the results.
|
|
The column order in the results will match the order of the parameters.
|
|
.Ar publisherinfoitem
|
|
can take any value from the list that follows:
|
|
.Bl -tag -width Ds
|
|
.It Ar connection_pid
|
|
Id of the Erlang process associated with the consumer connection.
|
|
.It Ar messages_confirmed
|
|
The number of confirmed messages for the publisher.
|
|
.It Ar messages_errored
|
|
The number of errored messages for the publisher.
|
|
.It Ar messages_published
|
|
The overall number of messages the publisher published.
|
|
.It Ar publisher_id
|
|
The connection-scoped ID of the publisher.
|
|
.It Ar reference
|
|
The deduplication reference of the publisher.
|
|
.It Ar stream
|
|
The stream the publisher publishes to.
|
|
.El
|
|
.Pp
|
|
If no
|
|
.Ar publisherinfoitem
|
|
are specified then connection_pid, publisher_id, stream, reference,
|
|
messages_published, messages_confirmed, and messages_errored are displayed.
|
|
.Pp
|
|
For example, this command displays the connection PID, publisher ID and stream
|
|
for each producer:
|
|
.sp
|
|
.Dl rabbitmq-streams list_stream_publishers connection_pid publisher_id stream
|
|
.\" ------------------------------------------------------------------
|
|
.It Cm add_super_stream Ar super-stream Oo Fl -vhost Ar vhost Oc Oo Fl -partitions Ar partitions Oc Oo Fl -binding-keys Ar binding-keys Oc Oo Fl -max-length-bytes Ar max-length-bytes Oc Oo Fl -max-age Ar max-age Oc Oo Fl -stream-max-segment-size-bytes Ar stream-max-segment-size-bytes Oc Oo Fl -leader-locator Ar leader-locator Oc Oo Fl -initial-cluster-size Ar initial-cluster-size Oc
|
|
.Bl -tag -width Ds
|
|
.It Ar super-stream
|
|
The name of the super stream to create.
|
|
.It Ar vhost
|
|
The name of the virtual host to create the super stream into.
|
|
.It Ar partitions
|
|
The number of partitions the super stream will have.
|
|
.It Ar binding-keys
|
|
Comma-separated list of binding keys.
|
|
.It Ar max-length-bytes
|
|
The maximum size of partition streams, example values: 20gb, 500mb.
|
|
.It Ar max-age
|
|
The maximum age of partition stream segments, using the ISO 8601 duration format, e.g. PT10M30S for 10 minutes 30 seconds, P5DT8H for 5 days 8 hours.
|
|
.It Ar stream-max-segment-size-bytes
|
|
The maximum size of partition stream segments, example values: 500mb, 1gb.
|
|
.It Ar leader-locator
|
|
Leader locator strategy for partition streams.
|
|
Possible values are:
|
|
.Bl -bullet -compact
|
|
.It
|
|
client-local
|
|
.It
|
|
balanced
|
|
.El
|
|
The default is
|
|
.Cm balanced
|
|
.It Ar initial-cluster-size
|
|
The initial cluster size of partition streams.
|
|
.El
|
|
.Pp
|
|
Create a super stream.
|
|
.\" ------------------------------------------------------------------
|
|
.It Cm delete_super_stream Ar super-stream Oo Fl -vhost Ar vhost Oc
|
|
.Bl -tag -width Ds
|
|
.It Ar super-stream
|
|
The name of the super stream to delete.
|
|
.It Ar vhost
|
|
The virtual host of the super stream.
|
|
.Pp
|
|
Delete a super stream.
|
|
.El
|
|
\" ------------------------------------------------------------------
|
|
.It Cm list_stream_consumer_groups Oo Fl p Ar vhost Oc Op Ar groupinfoitem ...
|
|
.Pp
|
|
Lists groups of stream single active consumers for a vhost.
|
|
.Pp
|
|
The
|
|
.Ar groupinfoitem
|
|
parameter is used to indicate which group information items to
|
|
include in the results.
|
|
The column order in the results will match the order of the parameters.
|
|
.Ar groupinfoitem
|
|
can take any value from the list that follows:
|
|
.Bl -tag -width Ds
|
|
.It Ar consumers
|
|
Number of consumers in the group.
|
|
.It Ar partition_index
|
|
The stream partition index if the stream is part of a super stream,
|
|
-1 if it is not.
|
|
.It Ar reference
|
|
The group reference (name).
|
|
.It Ar stream
|
|
The stream the consumers are attached to.
|
|
.El
|
|
.Pp
|
|
If no
|
|
.Ar groupinfoitem
|
|
are specified then stream, reference, partition_index, and consumers are displayed.
|
|
.Pp
|
|
For example, this command displays the stream, reference, and number of consumers
|
|
for each group:
|
|
.sp
|
|
.Dl rabbitmq-streams list_stream_consumer_groups stream reference consumers
|
|
\" ------------------------------------------------------------------
|
|
.It Cm list_stream_group_consumers Fl -stream Ar stream Fl -reference Ar reference Oo Fl -vhost Ar vhost Oc Op Ar consumerinfoitem ...
|
|
.Pp
|
|
Lists consumers of a stream consumer group in a vhost.
|
|
.It Ar stream
|
|
The stream the consumers are attached to.
|
|
.It Ar reference
|
|
The group reference (name).
|
|
.It Ar vhost
|
|
The virtual host of the stream.
|
|
.El
|
|
.Pp
|
|
The
|
|
.Ar consumerinfoitem
|
|
parameter is used to indicate which consumer information items to
|
|
include in the results.
|
|
The column order in the results will match the order of the parameters.
|
|
.Ar consumerinfoitem
|
|
can take any value from the list that follows:
|
|
.Bl -tag -width Ds
|
|
.It Ar connection_name
|
|
Readable name of the consumer connection.
|
|
.It Ar state
|
|
Consumer state; one of:
|
|
.Bl -bullet -compact
|
|
.It
|
|
active
|
|
.It
|
|
inactive
|
|
.El
|
|
.It Ar subscription_id
|
|
The connection-scoped ID of the consumer.
|
|
.El
|
|
.Pp
|
|
If no
|
|
.Ar consumerinfoitem
|
|
are specified then subscription_id, connection_name, and state are displayed.
|
|
.Pp
|
|
For example, this command displays the connection name and state
|
|
for each consumer attached to the stream-1 stream and belonging to the stream-1 group:
|
|
.sp
|
|
.Dl rabbitmq-streams list_stream_group_consumers --stream stream-1 --reference stream-1 connection_name state
|
|
.El
|
|
.\" ------------------------------------------------------------------
|
|
.Sh SEE ALSO
|
|
.\" ------------------------------------------------------------------
|
|
.Xr rabbitmqctl 8 ,
|
|
.Xr rabbitmq-diagnostics 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 rabbitmq-core@groups.vmware.com
|