# Log Trace

Use Log Trace to collect debug-level logs for specific MQTT clients, topics, source IP addresses, or rule IDs in an EMQX Cloud deployment. Log Trace is useful for troubleshooting client connection failures, unexpected disconnections, subscription failures, message publishing problems, message loss, or rule execution errors without enabling verbose logging for the entire deployment.

## Availability and Limits

Log Trace is available only for Dedicated and Dedicated Flex deployments running EMQX v6.1.3 or later. If your deployment does not meet these requirements, the EMQX Cloud Console does not show the **Trace** menu under **Diagnostics**.

Log Trace has the following limits:

- Each deployment can have up to 10 traces.
- Each trace can run for up to 24 hours.
- The trace name must start with a letter and can contain letters, numbers, underscores (`_`), and hyphens (`-`). The maximum length is 256 characters.
- You can set the payload limit up to 1 MB. The default value is 1024 B.

## When to Use Log Trace

Use Log Trace when you need to inspect the detailed broker-side process for a specific troubleshooting target. Typical scenarios include:

- A client cannot connect, disconnects unexpectedly, or fails authentication.
- A client cannot publish or subscribe to a topic.
- Messages are published but not received as expected.
- A rule does not process messages as expected.
- You need to compare logs from different broker nodes in a multi-node deployment.

For general deployment errors and warnings, use **Diagnostics** -> **Logs**. Use Log Trace when you need a focused trace for a specific client, topic, IP address, or rule.

## Create a Trace

1. In the EMQX Cloud Console, go to your deployment.

2. From the deployment menu, select **Diagnostics** -> **Trace**.

3. On the **Trace** page, click **New**.

4. In the **New Trace** dialog, configure the following fields:

   | Field | Description |
   | --- | --- |
   | **Name** | Enter a name for the trace. Use a descriptive name to identify the troubleshooting target. |
   | **Type** | Select the trace condition type. Supported types are **Client ID**, **Topic**, **IP Address**, and **Rule ID**. |
   | **Client ID** / **Topic** / **IP Address** / **Rule ID** | Enter the value to trace. The field label changes based on the selected **Type**. |
   | **Time Range** | Select the start and end time for the trace. The maximum time range is 24 hours. |
   | **Payload Encode** | Select how EMQX Cloud writes message payloads in the trace log. |
   | **Payload Limit** | Set the maximum number of payload bytes printed in the trace log. If the payload exceeds this value, EMQX Cloud truncates it. |

5. Click **Confirm**.

EMQX Cloud starts the trace at the configured start time and stops it automatically at the end time. You can also stop a running trace manually from the trace list.

::: tip

Set the start time before reproducing the issue and keep the time range as short as possible. This reduces log size and makes the trace easier to review.

:::

## Trace Types

You can create traces based on the following condition types:

- **Client ID**: Captures broker interactions for a specific MQTT client.
- **Topic**: Captures publish, subscribe, and unsubscribe events for a specific topic. Topic wildcards are supported.
- **IP Address**: Captures broker interactions from clients that connect from a specific source IP address.
- **Rule ID**: Captures rule execution logs for a specific rule, including SQL execution and action execution details.

## Payload Encode Options

Use **Payload Encode** to control how message payloads are written in trace logs:

- **Text**: Writes payloads as text. This option is recommended for plain text or JSON-encoded payloads.
- **HEX**: Writes payloads as hexadecimal values. This option is recommended for custom binary protocols.
- **Hidden**: Masks payloads as `******`. Use this option when payloads contain sensitive information.

**Payload Limit** applies only when **Payload Encode** is set to **Text** or **HEX**. If a payload exceeds the configured limit, EMQX Cloud writes only the allowed number of bytes to the trace log.

## View and Manage Traces

The **Trace** page lists all traces created for the deployment. The list includes the following information:

- **Name**: The trace name. Click the name to open the trace details.
- **Type**: The trace condition type.
- **Condition**: The value being traced, such as a client ID, topic, IP address, or rule ID.
- **Time Range**: The start and end time of the trace.
- **Status**: The trace status, such as **Running** or **Stopped**.
- **Payload Encode**: The selected payload encoding method.
- **Payload Limit**: The configured payload size limit.
- **Log Size**: The size of the collected trace logs.
- **Actions**: Available operations, such as downloading, stopping, or deleting a trace.

Use the actions in the trace list to manage trace logs:

- Click the trace name to open the trace details.
- Click the download icon to download the collected trace logs.
- Click the stop icon to stop a running trace before its end time.
- Click the delete icon to delete a stopped trace that is no longer needed.

You can stop or download running traces. You can download or delete stopped traces.

![Trace list](./_assets/log_trace_list.png)

## View Trace Details

Click a trace name to open the trace details page.

The trace details page displays the collected trace logs in a log viewer. Each log line includes information such as the timestamp, protocol or module tag, client identifier, source address, packet type, topic, authentication result, authorization result, or rule execution details, depending on the traced activity.

If your deployment has multiple broker nodes, the trace details page provides a node selector. By default, the page selects the node that most recently generated trace logs. You can manually select another node to view logs from that node.

You can also use the actions on the trace details page to:

- Refresh the displayed trace logs.
- Download trace logs from the selected node.
- Switch to another node when the deployment has multiple broker nodes.

## Demo: Trace a Test MQTT Client

This demo shows how to create a trace for a test client, generate MQTT traffic with the built-in MQTT client, and verify the generated trace logs.

### Step 1: Create a Client ID Trace

1. Go to **Diagnostics** -> **Trace**.

2. Click **New**.

3. Configure the trace with the following values:

   | Field | Value |
   | --- | --- |
   | **Name** | `client_trace_test` |
   | **Type** | `Client ID` |
   | **Client ID** | `trace_client_001` |
   | **Time Range** | Select a time range of about 30 minutes. |
   | **Payload Encode** | `Text` |
   | **Payload Limit** | `1024 B` or `1 KB` |

4. Click **Confirm**.

The trace appears in the trace list. Its status is **Running** during the selected time range.

### Step 2: Generate Test Traffic and Trigger Trace Logs

Use the built-in MQTT client from **Diagnostics** -> **MQTT Client** together with Log Trace to reproduce issues and generate trace logs without using an external MQTT client.

1. Go to **Diagnostics** -> **MQTT Client**.

2. Connect to the deployment using one of the following methods:

   - **Connect with Auto-Generated Authentication**: Use this option for quick testing if it is available for your deployment.
   - **Connect with Added Authentication**: Use an existing username and password configured in **Access Control** -> **Authentication**.

3. Make sure the MQTT client uses the following client ID:

   ```text
   trace_client_001
   ```

   The MQTT client must connect with the same client ID as the trace condition.

4. In the **Messages** area, publish a test message with the following values:

   | Field | Value |
   | --- | --- |
   | **Topic** | `trace/test` |
   | **QoS** | `QoS 0` |
   | **Payload Format** | `JSON` |
   | **Payload** | `{ "message": "hello" }` |

5. Click **Publish**. You can publish the message more than once to generate additional trace logs.

   The MQTT client page shows the connection status, publish topic, payload, and sent messages.

   ![MQTT Client generating test traffic for Log Trace](./_assets/log_trace_mqtt_client_demo.png)

### Step 3: Verify the Trace Logs

1. Return to **Diagnostics** -> **Trace**.

2. In the trace list, check the `client_trace_test` trace:

   - Verify that **Status** is **Running** if the trace is still within the selected time range.
   - Verify that **Log Size** increases after the matching client generates traffic.

   ![Trace list with MQTT Client panel](./_assets/log_trace_demo_trace_list.png)

   Keep the MQTT Client panel open while you verify the trace logs. You can click **Disconnect** to stop the test client, or click **Edit** to update the connection settings if you need to reconnect with a different client ID.

3. Click `client_trace_test` to open the trace details.

4. Check the trace logs. For this demo, the logs may include entries for:

   - MQTT connection packets, such as `CONNECT` and `CONNACK`.
   - Published messages, such as `PUBLISH` packets to `trace/test`.
   - Authentication and authorization results.
   - Keepalive packets, such as `PINGREQ` and `PINGRESP`.

5. If the deployment has multiple broker nodes, use the node selector to switch between nodes and view logs from a specific node.

6. Click the refresh icon to reload the displayed logs, or click the download icon to download the trace logs.

After you finish the test, return to the trace list and stop the trace if it is still running. You can delete the stopped trace after downloading any logs you need.

## Best Practices

- Use the narrowest trace condition possible to reduce log volume.
- Use a short time range when reproducing an issue.
- Use **Hidden** for **Payload Encode** if payloads may contain sensitive information.
- Increase **Payload Limit** only when you need to inspect larger payloads.
- Stop or delete traces that are no longer needed.