RabbitMQ - Management Plugin

The rabbitmq-management plugin provides an HTTP-based API for management and monitoring of your RabbitMQ server, along with a browser-based UI and a command line tool, rabbitmqadmin. Features include:

Declare, list and delete exchanges, queues, bindings, users, virtual hosts and permissions.
Monitor queue length, message rates globally and per channel, data rates per connection, etc.
Send and receive messages.
Monitor Erlang processes, file descriptors, memory use.
Export / import object definitions to JSON.
Force close connections, purge queues.

Screenshots

Overview	Import / Export

Channel List	Queue Details

Installation

The management plugin is included in the RabbitMQ distribution. To enable it, use rabbitmq-plugins:

rabbitmq-plugins enable rabbitmq_management

If you wish to build the plugin from source, it can be built like any other. See the plugin development page for more information, but be aware that it seems to be problematic to build rabbitmq-mochiweb on Windows.

Requirements

rabbitmq-management uses the Mochiweb web server which requires a newer Erlang version. At least R13B01 is required, but later versions are recommended.

Getting started

The web UI is located at: http://server-name:15672/
The HTTP API and its documentation are both located at: http://server-name:15672/api/ (or view our latest HTTP API documentation here).
Download rabbitmqadmin at: http://server-name:15672/cli/

NB: The port for RabbitMQ versions prior to 3.0 is 55672.

To use the web UI you will need to authenticate as a RabbitMQ user (on a fresh installation the user "guest" is created with password "guest"). From here you can manage exchanges, queues, bindings, virtual hosts, users and permissions. Hopefully the UI is fairly self-explanatory.

The management UI is implemented as a single static HTML page which makes background queries to the HTTP API. As such it makes heavy use of Javascript. It has been tested with recent versions of Firefox, Chromium and Safari, and with versions of Microsoft Internet Explorer back to 6.0.

Permissions

The management plugin extends the existing permissions model somewhat. Users can be given arbitrary tags within RabbitMQ. The management plugin makes use of tags called "management", "monitoring" and "administrator". The following table shows what the different types of user can do:

Tag	Capabilities
(None)	No access to the management plugin
management	Anything the user could do via AMQP plus: List virtual hosts to which they can log in via AMQP View all queues, exchanges and bindings in "their" virtual hosts View and close their own channels and connections View "global" statistics covering all their virtual hosts, including activity by other users within them
monitoring	Everything "management" can plus: List all virtual hosts, including ones they could not log in to via AMQP View other users's connections and channels View node-level data such as memory use and clustering View truly global statistics for all virtual hosts
administrator	Everything "monitoring" can plus: Create and delete virtual hosts View, create and delete users View, create and delete permissions Close other users's connections

Note that since "administrator" does everything "monitoring" does, and "monitoring" does everything "management" does, you only need to give each user a maximum of one tag.

Normal RabbitMQ permissions still apply to monitors and administrators; just because a user is a monitor or administrator does not give them full access to exchanges, queues and bindings through either AMQP or the management plugin.

All users can only list objects within a particular virtual host if they have any permissions for that virtual host.

If you get locked out due to only having non-administrator users, or no users at all, you can use rabbitmqctl add_user to create a non-administrator user and rabbitmqctl set_user_tags to promote a user to administrator.

Configuration

There are several configuration options which affect the management plugin. These are managed through the main RabbitMQ configuration file.

Load definitions at startup

The management plugin lets you export a JSON file containing definitions of all broker objects (queues, exchanges, bindings, users, virtual hosts, permissions and parameters). In some scenarios it may be useful to ensure the existence of these objects at every startup.

To do this, set the load_definitions variable to the path of a previously exported JSON file containing the definitions you want.

Note that the definitions in the file will overwrite anything already in the broker; using this option will not delete anything that is already there. However, if you start from a completely reset broker, use of this option will prevent the usual default user / virtual host / permissions from being created.

Fine-grained statistics

The message rates shown by the management plugin require fine-grained statistics to be enabled in the server. This will have a performance impact on a CPU-bound server; typically message throughput can be reduced by 5-10%. For ease of use, the management plugin will automatically enable fine-grained statistics when it is installed.

However, if you'd rather get the throughput than the statistics, you can prevent this from happening. Set the value of the force_fine_statistics variable to false in your configuration file for the rabbitmq_management_agent application and restart RabbitMQ.

Statistics interval

By default the server will emit statistics events every 5000ms. The message rate values shown in the management plugin are calculated over this period. You may therefore want to increase this value in order to sample rates over a longer period, or to reduce the statistics load on a server with a very large number of queues or channels.

In order to do so, set the value of the collect_statistics_interval variable for the rabbit application to the desired interval in milliseconds and restart RabbitMQ.

HTTP request logging

To create simple access logs of requests to the HTTP API, set the value of the http_log_dir variable in the rabbitmq_management application to the name of a directory in which logs can be created and restart RabbitMQ. Note that only requests to the API at /api are logged, not requests to the static files which make up the browser-based GUI.

Example

An example configuration file for RabbitMQ that switches on request logging, increases the statistics interval to 10000ms and explicitly sets some other relevant parameters to their default values, would look like this:

[
  {rabbit,                    [ {tcp_listeners,               [5672]},
                                {collect_statistics_interval, 10000} ] },
  {rabbitmq_management,       [ {http_log_dir,          "/tmp/rabbit-mgmt"} ] },
  {rabbitmq_management_agent, [ {force_fine_statistics, true} ] }
].

HTTP interfaces

It is possible to configure rabbitmq-mochiweb to serve the management plugin on a different port or network interface, with SSL, etc. To do so, you should configure the listener configuration item:

[
  ...
  {rabbitmq_management, [{listener, [{port, 12345}]}]},
  ...
].

See the rabbitmq-mochiweb guide for more details.

Sample retention policies

The management plugin will retain samples of some data such as message rates and queue lengths. You can configure how long such data is retained.

[
  ...
  {rabbitmq_management, [{sample_retention_policies,
                          [{global,   [{60, 5}, {3600, 60}, {86400, 1200}]},
                           {basic,    [{60, 5}, {3600, 60}]},
                           {detailed, [{10, 5}]}]}
                        ]},
  ...
].

There are three policies:

global - how long to retain data for the overview and virtual host pages
basic - how long to retain data for individual connections, channels, exchanges and queues
detailed - how long to retain data for message rates between pairs of connections, channels, exchanges and queues (as shown under "Message rates breakdown")

This configuration (which is the default) retains global data at a 5 second resolution for 1 minute, then at a 1 minute resolution for 1 hour, then at a 20 minute resolution for 1 day. It retains basic data at a 5 second resolution for 1 minute, then at a 1 minute resolution for 1 hour, and detailed data only for 10 seconds.

Note on clustering

The management plugin is aware of clusters. You can enable it on one or more nodes in a cluster, and see information pertaining to the entire cluster no matter which node you connect to.

If you want to deploy cluster nodes which do not have the full management plugin enabled, you will still need to enable the rabbitmq-management-agent plugin on each node.

HTTP API

By default the management plugin will create an HTTP-based API at http://server-name:15672/api/. Browse to that location for more information on the API. For convenience you can read the latest HTTP API documentation on our Mercurial server.

Proxy setup

It is possible to make the web UI available via any proxy that conforms with RFC 1738. The following sample Apache configuration illustrates the minimum necessary directives to coax Apache into conformance. It assumes a management web UI on the default port of 15672:

AllowEncodedSlashes On
ProxyPass        /api http://localhost:15672/api nocanon
ProxyPass        /    http://localhost:15672/
ProxyPassReverse /    http://localhost:15672/

Management Plugin