.\" 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/docs/streams "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/docs/clustering "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/docs/cli "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 contact-tanzu-data.pdl@broadcom.com