# Event History

Event History is a troubleshooting tool that records recent client connection, authentication, and subscription events from an EMQX deployment. Use it to investigate connection failures, unexpected disconnections, authentication failures, and subscriptions that do not take effect. For precise, multidimensional searches, use EMQX Tables.

Event History is available for Dedicated and Dedicated Flex deployments running EMQX v6.1.3 or later. It is not supported for Serverless or BYOC deployments.

## When to Use Event History

Event History helps you correlate the events that occur during a client's lifecycle. For example, you can:

- Check **Client Connack** and **Authentication Completed** events to investigate why a client failed to connect.
- Check the reason in a **Client Disconnected** event to investigate an unexpected disconnection.
- Check **Session Subscribed** and **Session Unsubscribed** events to verify the topic and QoS used by a client.
- Compare event timestamps to reconstruct the sequence of a client's connection, authentication, and subscription operations.

Event History consumes data integration TPS. Deployments with frequent client connections or reconnections generate more events and consume more TPS. Before enabling Event History, make sure that the deployment has sufficient data integration TPS capacity.

## Enable Event History

Before you enable Event History, make sure that:

- The deployment is running.
- The deployment is a Dedicated or Dedicated Flex deployment.
- The deployment runs EMQX v6.1.3 or later.
- The deployment has sufficient data integration TPS capacity.

To enable Event History:

1. In the EMQX Cloud console, open the deployment.
2. In the left navigation menu, click **Diagnostics** -> **Event History**.
3. Click **Enable Now**.
4. In the confirmation dialog, click **Confirm**.

The page displays the **Enabled** status, and EMQX starts recording supported client lifecycle events. No additional event configuration is required. Only events generated after Event History is enabled are recorded; events that occurred before it was enabled are not backfilled.

## Find and Inspect Events

The event limit defaults to 100 events. Use the filters when you need to narrow the results to a client or a specific type of activity. Each query reads the node-local event logs from all EMQX nodes in the deployment and aggregates the latest matching events.

### Filter Events

The following filters and result limits are available:

| Filter | Matching method | Limit |
| --- | --- | --- |
| **Client ID** | Contains, case-sensitive | 256 characters |
| **Username** | Contains, case-sensitive | 256 characters |
| **IP Address** | Exact match | 256 characters |
| **Topic** | Contains, without MQTT topic filter semantics | 256 characters |
| **Event Type** | Exact match | Select a supported event type from the list |
| Event limit | Maximum number of returned events | `100` (default), `500`, `1,000`, `5,000`, or `10,000` |

To query events:

1. Enter or select one or more filters. Leave all filters empty to query recent events of every supported type.
2. Select the maximum number of events to return.
3. Click the search icon.
4. Review the returned events. Click the expand icon beside an event to inspect its details.

To remove all filter values, click the clear icon. To retrieve the latest snapshot using the current filters, click the refresh icon.

![Filter and query events](./_assets/event-history-query.png)

### Interpret the Results

The event list displays the following information:

- **Time**: The event time, accurate to the second, together with the UTC offset.
- **Event Type**: The Console event name, such as **Client Connected**, **Authentication Completed**, or **Session Subscribed**.
- **Client ID**: The client identifier.
- **IP Address**: The client IP address and port when available. Otherwise, only the IP address is displayed.
- **Reason**: The result or reason when available. For example, an authentication event can show `success`, while a disconnection event can show a reason such as `internal_error`.

The expanded details vary by event type. They can include **Username**, **Topic**, **QoS**, **Connected At**, **Protocol Name**, and **Protocol Version**. Empty fields and fields already shown in the main list are omitted.

![Inspect event details](./_assets/event-history-event-details.png)

Query results use local pagination, with 10 events on each page. Changing pages does not query EMQX again. Starting a new search, clearing the filters, or refreshing the results sends a new query and returns to the first page.

## Supported Event Types

The **Event Type** list contains the following client lifecycle events:

| Console event type | Internal event type | Description |
| --- | --- | --- |
| **Client Connected** | `client.connected` | A client successfully connects to EMQX. |
| **Client Disconnected** | `client.disconnected` | A client disconnects from EMQX. Check **Reason** when troubleshooting an unexpected disconnection. |
| **Client Connack** | `client.connack` | EMQX sends a CONNACK packet to a client. |
| **Authentication Completed** | `client.check_authn_complete` | A client authentication attempt completes. Check **Reason** for the result. |
| **Session Subscribed** | `session.subscribed` | A client subscribes to a topic. Expand the event to check the topic and QoS. |
| **Session Unsubscribed** | `session.unsubscribed` | A client unsubscribes from a topic. Expand the event to check the topic and QoS. |

Event History does not record message events, such as `$events/message/delivery_dropped`.

## Disable Event History

To disable Event History:

1. Open the **Event History** page.
2. Click **Disable** in the upper-right corner.
3. Confirm the operation.

After Event History is disabled, EMQX stops recording new events. Recorded events are not deleted immediately and might still appear in query results until the disk logs are rotated or the EMQX node is replaced. You can enable Event History again at any time.

## Usage Notes and Limits

- **Query events promptly**: Event History uses local disk logs and does not guarantee a fixed retention period. The available time range depends on the event volume, available disk space, and log rotation.
- **Treat each query as a snapshot**: Event History does not support server-side pagination or time-range queries. Results from separate queries are independent snapshots and might not be continuous.
- **Use focused filters**: Event History is designed for troubleshooting recent client activity. Use EMQX Tables when you need precise, multidimensional searches.
- **Avoid excessive queries**: Each deployment supports up to 30 Event History queries within 60 seconds. Failed requests count toward this limit. Requests that exceed the limit return `429 Too Many Requests`.
- **Observe the result limit**: A query returns no more than 10,000 events.