Merge pull request #2129 from rabbitmq/amqp-event-exchange

Update Event Exchange Plugin docs

Author: michaelklishin

docs/event-exchange.md

@@ -22,116 +22,77 @@ 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:
 
 ```bash
 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
+```

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`