Merge pull request #5853 from rabbitmq/mergify/bp/v3.11.x/pr-5846

Add rabbitmq-streams manpage (backport #5846)

9 files changed, 321 insertions, 0 deletions

diff --git a/deps/rabbit/docs/rabbitmq-diagnostics.8 b/deps/rabbit/docs/rabbitmq-diagnostics.8
index eabbb7b48e..e19cf11520 100644
--- a/deps/rabbit/docs/rabbitmq-diagnostics.8
+++ b/deps/rabbit/docs/rabbitmq-diagnostics.8
@@ -715,6 +715,7 @@ in
 .Xr rabbitmqctl 8 ,
 .Xr rabbitmq-server 8 ,
 .Xr rabbitmq-queues 8 ,
+.Xr rabbitmq-streams 8 ,
 .Xr rabbitmq-upgrade 8 ,
 .Xr rabbitmq-service 8 ,
 .Xr rabbitmq-env.conf 5 ,
diff --git a/deps/rabbit/docs/rabbitmq-env.conf.5 b/deps/rabbit/docs/rabbitmq-env.conf.5
index f33380f3ad..5344b8597d 100644
--- a/deps/rabbit/docs/rabbitmq-env.conf.5
+++ b/deps/rabbit/docs/rabbitmq-env.conf.5
@@ -78,6 +78,7 @@ file RabbitMQ configuration file location is changed to "/data/services/rabbitmq
 .Xr rabbitmq-plugins 8 ,
 .Xr rabbitmq-server 8 ,
 .Xr rabbitmq-queues 8 ,
+.Xr rabbitmq-streams 8 ,
 .Xr rabbitmq-upgrade 8 ,
 .Xr rabbitmqctl 8
 .\" ------------------------------------------------------------------
diff --git a/deps/rabbit/docs/rabbitmq-plugins.8 b/deps/rabbit/docs/rabbitmq-plugins.8
index 95f410746a..e14389e261 100644
--- a/deps/rabbit/docs/rabbitmq-plugins.8
+++ b/deps/rabbit/docs/rabbitmq-plugins.8
@@ -244,6 +244,7 @@ plugin and its dependencies and disables everything else:
 .Xr rabbitmq-diagnostics 8 ,
 .Xr rabbitmq-server 8 ,
 .Xr rabbitmq-queues 8 ,
+.Xr rabbitmq-streams 8 ,
 .Xr rabbitmq-upgrade 8 ,
 .Xr rabbitmq-service 8 ,
 .Xr rabbitmq-env.conf 5 ,
diff --git a/deps/rabbit/docs/rabbitmq-queues.8 b/deps/rabbit/docs/rabbitmq-queues.8
index d6898ae608..022a5dcb56 100644
--- a/deps/rabbit/docs/rabbitmq-queues.8
+++ b/deps/rabbit/docs/rabbitmq-queues.8
@@ -192,6 +192,7 @@ Example:
 .Xr rabbitmqctl 8 ,
 .Xr rabbitmq-diagnostics 8 ,
 .Xr rabbitmq-server 8 ,
+.Xr rabbitmq-streams 8 ,
 .Xr rabbitmq-upgrade 8 ,
 .Xr rabbitmq-service 8 ,
 .Xr rabbitmq-env.conf 5 ,
diff --git a/deps/rabbit/docs/rabbitmq-server.8 b/deps/rabbit/docs/rabbitmq-server.8
index 113cdd725b..76c16bc436 100644
--- a/deps/rabbit/docs/rabbitmq-server.8
+++ b/deps/rabbit/docs/rabbitmq-server.8
@@ -88,6 +88,7 @@ For example, runs RabbitMQ AMQP server in the background:
 .Xr rabbitmq-diagnostics 8 ,
 .Xr rabbitmq-plugins 8 ,
 .Xr rabbitmq-queues 8 ,
+.Xr rabbitmq-streams 8 ,
 .Xr rabbitmq-upgrade 8 ,
 .Xr rabbitmq-service 8 ,
 .Xr rabbitmq-env.conf 5 ,
diff --git a/deps/rabbit/docs/rabbitmq-service.8 b/deps/rabbit/docs/rabbitmq-service.8
index 35ad279bd9..7bb27baac3 100644
--- a/deps/rabbit/docs/rabbitmq-service.8
+++ b/deps/rabbit/docs/rabbitmq-service.8
@@ -143,6 +143,7 @@ is to discard the server output.
 .Xr rabbitmq-plugins 8 ,
 .Xr rabbitmq-server 8 ,
 .Xr rabbitmq-queues 8 ,
+.Xr rabbitmq-streams 8 ,
 .Xr rabbitmq-upgrade 8 ,
 .Xr rabbitmq-env.conf 5 ,
 .Xr rabbitmq-echopid 8
diff --git a/deps/rabbit/docs/rabbitmq-streams.8 b/deps/rabbit/docs/rabbitmq-streams.8
new file mode 100644
index 0000000000..848811690e
--- /dev/null
+++ b/deps/rabbit/docs/rabbitmq-streams.8
@@ -0,0 +1,313 @@
+.\" 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) 2022 VMware, Inc. or its affiliates.  All rights reserved.
+.\"
+.Dd September 20, 2022
+.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
+.\" ------------------------------------
+.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 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, 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
+.El
+.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 info@rabbitmq.com
diff --git a/deps/rabbit/docs/rabbitmq-upgrade.8 b/deps/rabbit/docs/rabbitmq-upgrade.8
index dec436d2a4..c33280439a 100644
--- a/deps/rabbit/docs/rabbitmq-upgrade.8
+++ b/deps/rabbit/docs/rabbitmq-upgrade.8
@@ -120,6 +120,7 @@ To learn more, see the
 .Xr rabbitmq-diagnostics 8 ,
 .Xr rabbitmq-server 8 ,
 .Xr rabbitmq-queues 8 ,
+.Xr rabbitmq-streams 8 ,
 .Xr rabbitmq-service 8 ,
 .Xr rabbitmq-env.conf 5 ,
 .Xr rabbitmq-echopid 8
diff --git a/deps/rabbit/docs/rabbitmqctl.8 b/deps/rabbit/docs/rabbitmqctl.8
index 3d93c09bc1..0e41ec0f4f 100644
--- a/deps/rabbit/docs/rabbitmqctl.8
+++ b/deps/rabbit/docs/rabbitmqctl.8
@@ -2507,6 +2507,7 @@ Reset stats database for all nodes in the cluster.
 .Xr rabbitmq-plugins 8 ,
 .Xr rabbitmq-server 8 ,
 .Xr rabbitmq-queues 8 ,
+.Xr rabbitmq-streams 8 ,
 .Xr rabbitmq-upgrade 8 ,
 .Xr rabbitmq-service 8 ,
 .Xr rabbitmq-env.conf 5 ,