Event Exchange Plugin

Overview

Client connections, queues, consumers, and other parts of the system generate events. For example, when a connection is created, a connection.created event is emitted. When a connection is closed or fails, a connection.closed event is emitted.

Monitoring and auditing services can be interested in observing these events. RabbitMQ has a minimalistic mechanism for event notifications that can be exposed to RabbitMQ clients with the rabbitmq_event_exchange plugin.

The plugin requires no configuration, just activate it:

rabbitmq-plugins enable rabbitmq_event_exchange

Consuming Internal Events

rabbitmq_event_exchange is a plugin that consumes RabbitMQ internal events and re-publishes them to a topic exchange called amq.rabbitmq.event, thus exposing these events to clients applications. To consume the events, an application needs to declare a queue and bind it to the amq.rabbitmq.event exchange.

By default, the plugin declares the topic exchange amq.rabbitmq.event in the default virtual host (/). All events are published to this exchange with routing keys (topics) such as exchange.created, binding.deleted, etc. Applications can therefore consume only the relevant events. For example, to subscribe to all user events (such as user.created, user.authentication.failure, etc.) create a binding with routing (binding) key user.#.

The exchange behaves similarly to amq.rabbitmq.log: everything gets published there. If application's user cannot be trusted with the events that get published, don't allow them read access to the amq.rabbitmq.event exchange.

::: important

All messages published by the internal event mechanism will always have a blank body. Relevant event attributes are passed in message metadata.

:::

Each event has various event properties associated with it. By default, the plugin internally publishes AMQP 0.9.1 messages with event properties translated to AMQP 0.9.1 message headers. The plugin can optionally be configured to internally publish AMQP 1.0 messages with event properties translated to AMQP 1.0 message-annotations by setting the following in rabbitmq.conf:

event_exchange.protocol = amqp_1_0

All messages published by the internal event mechanism will always have a blank body. Relevant event attributes are passed in message metadata.

Because the plugin sets event properties as AMQP 0.9.1 headers or AMQP 1.0 message-annotations, client applications can optionally subscribe to only specific event properties (for example all events emitted for a specific user). This can be achieved by binding a queue to a headers exchange, and the headers exchange to the amq.rabbitmq.event topic exchange.

Events

Events including their routing keys (topics) that this plugin publishes are documented here.

Example

There's an example internal event consumer in Java.

Plugin Configuration

By default, the rabbitmq_event_exchange plugin uses the following configuration:

event_exchange.vhost = /
event_exchange.protocol = amqp_0_9_1

To switch the plugin to publish events in the AMQP 1.0 format, use

event_exchange.vhost = /
event_exchange.protocol = amqp_1_0