- Notifications
You must be signed in to change notification settings - Fork1
A command line tool for RabbitMQ that uses the HTTP API
License
Apache-2.0, MIT licenses found
Licenses found
rabbitmq/rabbitmqadmin-ng
Folders and files
| Name | Name | Last commit message | Last commit date | |
|---|---|---|---|---|
Repository files navigation
rabbitmqadmin v2 is a major revision ofrabbitmqadmin, one of theRabbitMQ CLI toolsthat target theHTTP API.
If you are migrating from the originalrabbitqadmin, please seeBreaking or Potentially Breaking Changesto learn about the breaking changes in the command line interface.
The general "shape and feel" of the interface is still very similar torabbitmqadmin v1.
rabbitmqadmin v2 targets
- Open source RabbitMQ
4.x - Open source RabbitMQ
3.13.x(specifically for the command groups and commands related to upgrades) - Tanzu RabbitMQ
4.x - Tanzu RabbitMQ
3.13.x
To download a binary build, seeReleases.
On platforms not covered by the binary builds,rabbitmqadmin v2 can be installed withCargo:
cargo install rabbitmqadmin
For usage documentation, see thededicated RabbitMQ doc guide and/orUsage below.
Please use GitHub Discussions in this repository andRabbitMQ community Discord server.
This version ofrabbitmqadmin should be considered reasonably mature to be used.
Before migrating, please seeBreaking or Potentially Breaking Changes to learn about a few breaking change in the interface.
To explore what command groups are available, use
rabbitmqadminhelpwhich will output a list of command groups:
Usage: rabbitmqadmin [OPTIONS] <COMMAND>Commands: show Overview, memory footprint breakdown, and more list Lists objects declare Creates or declares objects delete Deletes objects purge Purges queues policies Operations on policies health_check Runs health checks close Closes connections rebalance Rebalancing of leader replicas definitions Operations on definitions (everything except for messages: virtual hosts, queues, streams, exchanges, bindings, users, etc) export See 'definitions export' import See 'definitions import' feature_flags Operations on feature flags deprecated_features Operations on deprecated features publish Publishes (inefficiently) message(s) to a queue or a stream. Only suitable for development and test environments. get Fetches message(s) from a queue or stream via polling. Only suitable for development and test environments. shovels Operations on shovels federation Operations on federation upstreams and links tanzu Tanzu RabbitMQ-specific commands help Print this message or the help of the given subcommand(s)To explore commands in a specific group, use
rabbitmqadmin {group name}helpTo learn about what command groups and specific commands are available, run
rabbitmqadminhelpThis flag can be appended to a command or subcommand to get command-specific documentation:
rabbitmqadmindeclare queue --help# => creates or declares things# =># => Usage: rabbitmqadmin declare [object]# => ...
Alternatively, thehelp subcommand can be given a command name. It's the equivalentof tagging on--help at the end of command name:
rabbitmqadmindeclarehelp queue# => declares a queue or a stream# =># => Usage: rabbitmqadmin declare queue [OPTIONS] --name <name>
More specific examples are covered in the Examples section below.
Like the original version,rabbitmqadmin v2 is first and foremost built for interactive useby humans. Many commands will output formatted tables, for example:
rabbitmqadmin show overview
will output a table that looks like this:
┌───────────────────────────────────────────────────────────────────┬─────────────────────────────────────────────────────────────────────────────────────────────────┐│ Overview │├───────────────────────────────────────────────────────────────────┼─────────────────────────────────────────────────────────────────────────────────────────────────┤│ key │ value │├───────────────────────────────────────────────────────────────────┼─────────────────────────────────────────────────────────────────────────────────────────────────┤│ Product name │ RabbitMQ │├───────────────────────────────────────────────────────────────────┼─────────────────────────────────────────────────────────────────────────────────────────────────┤│ Product version │ 4.0.5 │├───────────────────────────────────────────────────────────────────┼─────────────────────────────────────────────────────────────────────────────────────────────────┤│ RabbitMQ version │ 4.0.5 │├───────────────────────────────────────────────────────────────────┼─────────────────────────────────────────────────────────────────────────────────────────────────┤│ Erlang version │ 27.2.1 │├───────────────────────────────────────────────────────────────────┼─────────────────────────────────────────────────────────────────────────────────────────────────┤│ Erlang details │ Erlang/OTP 27 [erts-15.2.1] [source] [64-bit] [smp:10:10] [ds:10:10:10] [async-threads:1] [jit] │├───────────────────────────────────────────────────────────────────┼─────────────────────────────────────────────────────────────────────────────────────────────────┤│ Connections (total) │ 4 │├───────────────────────────────────────────────────────────────────┼─────────────────────────────────────────────────────────────────────────────────────────────────┤│ AMQP 0-9-1 channels (total) │ 4 │├───────────────────────────────────────────────────────────────────┼─────────────────────────────────────────────────────────────────────────────────────────────────┤│ Queues and streams (total) │ 4 │├───────────────────────────────────────────────────────────────────┼─────────────────────────────────────────────────────────────────────────────────────────────────┤│ Consumers (total) │ 4 │├───────────────────────────────────────────────────────────────────┼─────────────────────────────────────────────────────────────────────────────────────────────────┤│ Messages (total) │ 222 │├───────────────────────────────────────────────────────────────────┼─────────────────────────────────────────────────────────────────────────────────────────────────┤│ Messages ready for delivery (total) │ 2 │├───────────────────────────────────────────────────────────────────┼─────────────────────────────────────────────────────────────────────────────────────────────────┤│ Messages delivered but unacknowledged by consumers (total) │ 220 │├───────────────────────────────────────────────────────────────────┼─────────────────────────────────────────────────────────────────────────────────────────────────┤│ Publishing (ingress) rate (global) │ │├───────────────────────────────────────────────────────────────────┼─────────────────────────────────────────────────────────────────────────────────────────────────┤│ Publishing confirm rate (global) │ │├───────────────────────────────────────────────────────────────────┼─────────────────────────────────────────────────────────────────────────────────────────────────┤│ Consumer delivery (egress) rate (global) │ │├───────────────────────────────────────────────────────────────────┼─────────────────────────────────────────────────────────────────────────────────────────────────┤│ Consumer delivery in automatic acknowledgement mode rate (global) │ │├───────────────────────────────────────────────────────────────────┼─────────────────────────────────────────────────────────────────────────────────────────────────┤│ Consumer acknowledgement rate (global) │ │├───────────────────────────────────────────────────────────────────┼─────────────────────────────────────────────────────────────────────────────────────────────────┤│ Unroutable messages: returned-to-publisher rate (global) │ │├───────────────────────────────────────────────────────────────────┼─────────────────────────────────────────────────────────────────────────────────────────────────┤│ Unroutable messages: dropped rate (global) │ │├───────────────────────────────────────────────────────────────────┼─────────────────────────────────────────────────────────────────────────────────────────────────┤│ Cluster tags │ "az": "us-east-3" ││ │ "environment": "production" ││ │ "region": "us-east" ││ │ │├───────────────────────────────────────────────────────────────────┼─────────────────────────────────────────────────────────────────────────────────────────────────┤│ Node tags │ "environment": "production" ││ │ "instance": "xlarge.m3" ││ │ │└───────────────────────────────────────────────────────────────────┴─────────────────────────────────────────────────────────────────────────────────────────────────┘As it is easy to observe, parsing such output in a script will be challenging.
For this reason,rabbitmqadmin v2 can render results in a way that would be much more friendlyfor scripting if the--non-interactive flag is passed. It is a global flag so it must bepassed before the command and subcommand name:
rabbitmqadmin --non-interactive show overview
The output of the above command will not include any table borders and will is much easier to parseas a result:
key Product name RabbitMQ Product version 4.0.7 RabbitMQ version 4.0.7 Erlang version 26.2.5.10 Erlang details Erlang/OTP 26 [erts-14.2.5.9] [source] [64-bit] [smp:10:10] [ds:10:10:10] [async-threads:1] [jit]rabbitmqadmin show overview
will display essential node information in tabular form.
Helps assess connection, queue/stream, channelchurn metrics in the cluster.
rabbitmqadmin show churn
rabbitmqadmin list nodes
rabbitmqadmin list vhosts
rabbitmqadmin list users
rabbitmqadmin list queues
rabbitmqadmin --vhost"monitoring" list queuesrabbitmqadmin list exchanges
rabbitmqadmin --vhost"events" list exchangesrabbitmqadmin list bindings
rabbitmqadmin --vhost"events" list bindingsrabbitmqadmindeclare vhost --name"vh-789" --default-queue-type"quorum" --description"Used to reproduce issue #789"
rabbitmqadmin delete vhost --name"vh-789"# --idempotently means that 404 Not Found responses will not be considered errorsrabbitmqadmin delete vhost --name"vh-789" --idempotently
rabbitmqadmin --vhost"events"declare queue --name"target.quorum.queue.name" --type"quorum" --durabletrue
rabbitmqadmin --vhost"events"declare queue --name"target.stream.name" --type"stream" --durabletrue
rabbitmqadmin --vhost"events"declare queue --name"target.classic.queue.name" --type"classic" --durabletrue --auto-deletefalse
rabbitmqadmin --vhost "events" purge queue --name "target.queue.name"rabbitmqadmin --vhost"events" delete queue --name"target.queue.name"
# --idempotently means that 404 Not Found responses will not be considered errorsrabbitmqadmin --vhost"events" delete queue --name"target.queue.name" --idempotently
rabbitmqadmin --vhost"events"declare exchange --name"events.all_types.topic" --type"topic" --durabletrue
rabbitmqadmin --vhost"events"declare exchange --name"events.all_type.uncategorized" --type"fanout" --durabletrue --auto-deletefalse
rabbitmqadmin --vhost"events"declare exchange --name"local.random.c60bda92" --type"x-local-random" --durabletrue
rabbitmqadmin --vhost"events" delete exchange --name"target.exchange.name"
# --idempotently means that 404 Not Found responses will not be considered errorsrabbitmqadmin --vhost"events" delete exchange --name"target.exchange.name" --idempotently
There are two commands for reasoning about targetnode's memory footprint:
# displays a breakdown in bytesrabbitmqadmin show memory_breakdown_in_bytes --node'rabbit@hostname'
# displays a breakdown in percentrabbitmqadmin show memory_breakdown_in_percent --node'rabbit@hostname'
Example output ofshow memory_breakdown_in_percent:
┌────────────────────────────────────────┬────────────┐│ key │ percentage │├────────────────────────────────────────┼────────────┤│ total │ 100% │├────────────────────────────────────────┼────────────┤│ Binary heap │ 45.10% │├────────────────────────────────────────┼────────────┤│ Allocated but unused │ 23.45% │├────────────────────────────────────────┼────────────┤│ Quorum queue ETS tables │ 23.05% │├────────────────────────────────────────┼────────────┤│ Other processes │ 5.32% │├────────────────────────────────────────┼────────────┤│ Other (used by the runtime) │ 4.98% │├────────────────────────────────────────┼────────────┤│ Code │ 4.54% │├────────────────────────────────────────┼────────────┤│ Client connections: others processes │ 3.64% │├────────────────────────────────────────┼────────────┤│ Management stats database │ 3.48% │├────────────────────────────────────────┼────────────┤│ Client connections: reader processes │ 3.22% │├────────────────────────────────────────┼────────────┤│ Plugins and their data │ 3.12% │├────────────────────────────────────────┼────────────┤│ Other (ETS tables) │ 1.55% │├────────────────────────────────────────┼────────────┤│ Metrics data │ 0.66% │├────────────────────────────────────────┼────────────┤│ AMQP 0-9-1 channels │ 0.40% │├────────────────────────────────────────┼────────────┤│ Message store indices │ 0.27% │├────────────────────────────────────────┼────────────┤│ Atom table │ 0.24% │├────────────────────────────────────────┼────────────┤│ Client connections: writer processes │ 0.19% │├────────────────────────────────────────┼────────────┤│ Quorum queue replica processes │ 0.10% │├────────────────────────────────────────┼────────────┤│ Stream replica processes │ 0.07% │├────────────────────────────────────────┼────────────┤│ Mnesia │ 0.02% │├────────────────────────────────────────┼────────────┤│ Metadata store │ 0.02% │├────────────────────────────────────────┼────────────┤│ Stream coordinator processes │ 0.02% │├────────────────────────────────────────┼────────────┤│ Classic queue processes │ 0.00% │├────────────────────────────────────────┼────────────┤│ Metadata store ETS tables │ 0.00% │├────────────────────────────────────────┼────────────┤│ Stream replica reader processes │ 0.00% │├────────────────────────────────────────┼────────────┤│ Reserved by the kernel but unallocated │ 0.00% │└────────────────────────────────────────┴────────────┘Note that there aretwo different supported strategiesfor computing memory footprint of a node.rabbitmqadmin will use the greater valuefor 100% when computing the relative share in percent for each category.
Other factors that can affect the precision of percentage values reportedareruntime allocatorbehavior nuances and thekernel page cache.
rabbitmqadmin feature_flags list
# same command as aboverabbitmqadmin list feature_flagsrabbitmqadmin feature_flagsenable rabbitmq_4.0.0rabbitmqadmin feature_flags enable_all
rabbitmqadmin deprecated_features list_used
rabbitmqadmin deprecated_features list
# same command as aboverabbitmqadmin list deprecated_featuresThis feature is available only in themain branchat the moment.
If theRABBITMQADMIN_NON_INTERACTIVE_MODE is not set totrue, this toolnow can infer subcommand and --long-option names.
This means that a subcommand can be referenced with its unique prefix,that is,
- 'del queue' will be inferred as 'delete queue'
- 'del q --nam "a.queue"' will be inferred as 'delete queue --name "a.queue"'
To enable each feature, set the following environment variables to'true':
RABBITMQADMIN_INFER_SUBCOMMANDSRABBITMQADMIN_INFER_LONG_OPTIONS
This feature is only mean to be used interactively. For non-interactiveuse, it can be potentially too dangerous to allow.
rabbitmqadmin v2 supportsTOML-based configuration filesstores groups of HTTP API connection settings under aliases ("node names" in originalrabbitmqadmin speak).
Here is an examplerabbitmqadmin v2 configuration file:
[local]hostname ="localhost"port =15672username ="lolz"password ="lolz"vhost ='/'[staging]hostname ="192.168.20.31"port =15672username ="staging-2387a72329"password ="staging-1d20cfbd9d"[production]hostname ="(redacted)"port =15671username ="user-2ca6bae15ff6b79e92"password ="user-92ee4c479ae604cc72"
Instead of specifying--hostname or--username on the command line to connect toa cluster (or specific node) calledstaging, a--node alias can be specified instead:
# will use the settings from the section called [staging]rabbitmqadmin --node staging show churnDefault configuration file path is at$HOME/.rabbitmqadmin.conf, as it was inthe original version ofrabbitmqadmin. It can be overridden on the command line:
# will use the settings from the section called [staging]rabbitmqadmin --config$HOME/.configuration/rabbitmqadmin.conf --node staging show churn
Environment variables have a number of serious downsides compared to arabbitmqadmin.confand the regular--long-options on the command line:
- Non-existent support for value types and validation ("everything is a string")
- Subprocess inheritance restrictions that can be very time-consuming to debug
- Different syntax for setting them between the classic POSIX-era shells (such as
bash,zsh) and modern ones (such asnushell)
For these reasons and others,rabbitmqadmin v2 intentionally uses the configuration file and theCLI options over the environment variables.
rabbitmqadmin v2 does, however, supports a number of environment variables for a fewglobal settings that cannot be configured any other way (besides a CLI option),or truly represent an environment characteristic, e.g. either the non-interactive modeshould be enabled.
These environment variables are as follows:
| Environment variable | Type | When used | Description |
|---|---|---|---|
RABBITMQADMIN_CONFIG_FILE_PATH | Local filesystem path | Pre-flight (before command execution) | Same meaning as the global--confg-file argument |
RABBITMQADMIN_NON_INTERACTIVE_MODE | Boolean | Command execution | Enables the non-interactive mode. Same meaning as the global --non-interactive argument |
RABBITMQADMIN_QUIET_MODE | Boolean | Command execution | Instructs the tool to produce less output. Same meaning as the global --quiet argument |
RABBITMQADMIN_NODE_ALIAS | String | Command execution | Same meaning as the global--node argument |
RABBITMQADMIN_TARGET_HOST | String | Command execution | Same meaning as the global--host argument |
RABBITMQADMIN_TARGET_PORT | Positive integer | Command execution | Same meaning as the global--port argument |
RABBITMQADMIN_API_PATH_PREFIX | String | Command execution | Same meaning as the global--path-prefix argument |
RABBITMQADMIN_TARGET_VHOST | String | Command execution | Same meaning as the global--vhost argument |
RABBITMQADMIN_BASE_URI | String | Command execution | Same meaning as the global--base-uri argument |
RABBITMQADMIN_USE_TLS | Boolean | Command execution | Same meaning as the global--tls argument |
RABBITMQADMIN_USERNAME | String | Command execution | Same meaning as the global--username argument |
RABBITMQADMIN_PASSWORD | String | Command execution | Same meaning as the global--password argument |
RABBITMQADMIN_TABLE_STYLE | Enum, see--table-style inrabbitmqadmin help | Command execution | Same meaning as the global--table-style argument |
This version ofrabbitmqadmin has a few ideas in mind:
- This is a major version bump. Therefore, reasonable breaking changes are OK.
rabbitmqadminhasn't seen a revision in fifteen years - Some features in
rabbitmqadminv1 arguably should never have been built-ins,external tools for data processing andmodern shells can manipulate tabular databetter thanrabbitmqadminever would rabbitmqadminshould be standalone binary. There are very few reasons not to build and distribute it that way- Standalone project, not an obscure feature:
rabbitmqadminshould be a standalone tool, not a relatively unknown "feature" ofthe RabbitMQ management plugin, and should be developed as such, not tied completely to the developmentenvironment, practices and release schedule of RabbitMQ itself - v2 should be a distributed via GitHub releases and not a special
rabbitmq_managementendpoint - There is a lot of room to improve validation of flags and arguments, since breaking changes are OK for v2
- This tool should strive to be as free as practically possible from CVEs in other projects that show up on security scans.CVEs from older Python versions should not plague OCI images that choose to include
rabbitmqadminv2
rabbitmqadmin v2 does not support
- Sorting of results. Instead, use
--non-interactiveand parse the spaces-separatedoutput. Many modern tools for working with data parse it into a table, sort the data set,filter the results, and son. In fact, these features for data processing are ready availablein some shells - Column selection. This feature may be reintroduced
- JSON output for arbitrary commands (with the exception of
definitionscommands).Use the HTTP API directly if you need to work with JSON - CSV output for arbitrary commands. This format may be reintroduced
rabbitmqadmin v1 usedlower_case for named command arguments, for example:
# Note: auto_deleterabbitmqadmin-v1 --vhost"vh-2"declare queue name="qq.1" type="quorum" durable=true auto_delete=false
rabbitmqadmin v2 uses a more typical--snake-case format for the same arguments:
# Note: --auto-deleterabbitmqadmin --vhost"vh-2"declare queue --name"qq.1" --type"quorum" --durabletrue --auto-deletefalse
Global flags inrabbitmqadmin v2 must precede the command category (e.g.list) and the command itself,namely various HTTP API endpoint options and--vhost:
rabbitmqadmin --vhost"events"declare queue --name"target.quorum.queue.name" --type"quorum" --durabletrue
Inrabbitmqadmin v1,--path-prefix appended to the defaultAPI path prefix.In this version, the value passed to--path-prefix will be used as given, in other words,it replaces the default prefix,/api.
rabbitmqadmin v1 supported ini configuration files that allowedthe user to group a number of command line values under a name, e.g. a cluster or node nickname.
Due to the "no dependencies other than Python" design goal ofrabbitmqadmin v1, this feature was not really tested,and the specific syntax (that of ini files, supported by Python'sConfigParser) linting, parsing or generation tools were not really available.
rabbitmqadmin v2 replaces this format withTOML, a popular configuration standardwithverification and linting tools, as well as very mature parserthat is not at all specific torabbitmqadmin v2.
Here is an examplerabbitmqadmin v2 configuration file:
[local]hostname ="localhost"port =15672username ="lolz"password ="lolz"vhost ='/'[staging]hostname ="192.168.20.31"port =15672username ="staging-2387a72329"password ="staging-1d20cfbd9d"[production]hostname ="(redacted)"port =15671username ="user-efe1f4d763f6"password ="(redacted)"
This tool,rabbitmqadmin (v2 and later versions), is dual-licensed underthe Apache Software License 2.0 and the MIT license.
About
A command line tool for RabbitMQ that uses the HTTP API