diff --git a/docs/event-exchange.md b/docs/event-exchange.md index 30218b1d17..3fce9efcf6 100644 --- a/docs/event-exchange.md +++ b/docs/event-exchange.md @@ -22,35 +22,13 @@ limitations under the License. ## Overview -Client connection, channels, queues, consumers, and other parts of the -system [naturally generate events](./logging#internal-events). For example, when a connection is -accepted, authenticated and access to the target virtual host is -authorised, it will emit an event of type `connection_created`. When a -connection is closed or fails for any reason, a `connection_closed` -event is emitted. - -[Monitoring](./monitoring) and auditing services can be interested in observing those -events. RabbitMQ has a minimalistic mechanism for event notifications -that can be exposed to RabbitMQ clients with a plugin. - - -## Consuming Internal Events with rabbitmq-event-exchange Plugin - -[rabbitmq-event-exchange](https://github.com/rabbitmq/rabbitmq-event-exchange) -is a plugin that consumes internal events and re-publishes them to a -topic exchange, thus exposing the events to clients (applications). - -To consume the events, an application needs to declare a queue, bind -it to a special system exchange and consume messages. +Client connections, queues, consumers, and other parts of the system generate [events](./logging#internal-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. -It declares a topic exchange called `amq.rabbitmq.event` in the default -virtual host. All events are published to this exchange with routing -keys like 'exchange.created', 'binding.deleted' etc, so you can -subscribe to only the events you're interested in. - -The exchange behaves similarly to `amq.rabbitmq.log`: everything gets -published there; if you don't trust a user with the information that -gets published, don't allow them access. +[Monitoring](./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: @@ -58,80 +36,63 @@ The plugin requires no configuration, just activate it: rabbitmq-plugins enable rabbitmq_event_exchange ``` -Each event has various properties associated with it. These are -translated into AMQP 0-9-1 data encoding and inserted in the message headers. The -**message body is always blank**. - - -## Events +## Consuming Internal Events -RabbitMQ and related plugins produce events with the following routing keys: +[rabbitmq_event_exchange](https://github.com/rabbitmq/rabbitmq-server/tree/main/deps/rabbitmq_event_exchange) +is a plugin that consumes RabbitMQ internal events and re-publishes them to a +[topic exchange](/tutorials/amqp-concepts#exchange-topic) 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. -### RabbitMQ Broker +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.#`. -Queue, Exchange and Binding events: +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](./access-control) them `read` access to the `amq.rabbitmq.event` exchange. -- `queue.created` -- `queue.deleted` -- `exchange.created` -- `exchange.deleted` -- `binding.created` -- `binding.deleted` +::: important -Connection and Channel events: +All messages published by the internal event mechanism will always have a blank body. +Relevant event attributes are passed in message metadata. -- `connection.created` -- `connection.closed` -- `channel.created` -- `channel.closed` +::: -Consumer events: +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](https://docs.oasis-open.org/amqp/core/v1.0/os/amqp-core-messaging-v1.0-os.html#type-message-annotations) +by setting the following in [rabbitmq.conf](configure#config-file): -- `consumer.created` -- `consumer.deleted` - -Policy and Parameter events: - -- `policy.set` -- `policy.cleared` -- `parameter.set` -- `parameter.cleared` - -Virtual host events: - -- `vhost.created` -- `vhost.deleted` - -User related events: +``` +event_exchange.protocol = amqp_1_0 +``` -- `user.authentication.success` -- `user.authentication.failure` -- `user.created` -- `user.deleted` -- `user.password.changed` -- `user.password.cleared` -- `user.tags.set` +All messages published by the internal event mechanism will always have a blank body. +Relevant event attributes are passed in message metadata. -Permission events: +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](/tutorials/amqp-concepts#exchange-headers), and the headers exchange to the `amq.rabbitmq.event` topic exchange. -- `permission.created` -- `permission.deleted` +### Events -### Shovel Plugin +Events including their routing keys (topics) that this plugin publishes are documented [here](./logging#internal-events). -Worker events: +### Example -- `shovel.worker.status` -- `shovel.worker.removed` +There's an [example internal event consumer in Java](https://github.com/rabbitmq/rabbitmq-server/tree/main/deps/rabbitmq_event_exchange/examples/java). -### Federation Plugin -Link events: +## Plugin Configuration -- `federation.link.status` -- `federation.link.removed` +By default, the `rabbitmq_event_exchange` plugin uses the following configuration: +``` ini +event_exchange.vhost = / +event_exchange.protocol = amqp_0_9_1 +``` -## Example +To switch the plugin to publish events in the AMQP 1.0 format, use -There is a usage example using the Java client [in the rabbitmq-event-exchange repository](https://github.com/rabbitmq/rabbitmq-event-exchange/tree/master/examples/java). +``` ini +event_exchange.vhost = / +event_exchange.protocol = amqp_1_0 +``` diff --git a/docs/logging.md b/docs/logging.md index 3ec36e21fe..e5d79ceaad 100644 --- a/docs/logging.md +++ b/docs/logging.md @@ -937,7 +937,7 @@ The events can also be exposed to applications for [consumption](./consumers) with [a plugin](./event-exchange). Events are published as messages with blank bodies. All event metadata is stored in -message metadata (properties, headers). +message annotations (properties, headers). Below is a list of published events. @@ -952,7 +952,7 @@ Below is a list of published events. * `binding.created` * `binding.deleted` -[Connection](./connections) and [Channel](./channels) events: +[Connection](./connections) and AMQP 0.9.1 [Channel](./channels) events: * `connection.created` * `connection.closed` @@ -968,6 +968,8 @@ Below is a list of published events. * `policy.set` * `policy.cleared` + * `queue.policy.updated` + * `queue.policy.cleared` * `parameter.set` * `parameter.cleared` @@ -980,10 +982,10 @@ Below is a list of published events. User management events: - * `user.authentication.success` - * `user.authentication.failure` * `user.created` * `user.deleted` + * `user.authentication.success` + * `user.authentication.failure` * `user.password.changed` * `user.password.cleared` * `user.tags.set`