ApsaraMQ for RocketMQ：Query message traces

Message trace data

In ApsaraMQ for RocketMQ, the complete trace of a message involves the producer, broker, and consumer. When each role processes the message, the related information is added to the trace. You can use the aggregated information to obtain the status of the message.

Usage notes

After a message is sent, you can query the trace of the message based on the attributes of the message in the ApsaraMQ for RocketMQ console. This feature takes effect on all types of messages. Before you use the message trace feature, take note of the following points.

Time range for message trace queries

By default, messages are stored in ApsaraMQ for RocketMQ brokers for 3 days. You can query only the traces of messages that are produced within 3 days before the current point in time. For example, if the current point in time is 15:09:48 on November 30, 2023, you can query the traces of messages that are produced from 15:09:48 on November 27, 2023 to 15:09:48 on November 30, 2023.

Impacts of consumption status on query results

Versions of SDKs that support the message trace feature

Prerequisites for using the enhanced message trace feature

Compared with the basic message trace feature, the enhanced message trace feature allows you to view more trace data in the ApsaraMQ for RocketMQ console. You can query the trace data that is generated during message consumption and the trace data of scheduled messages, delayed messages, and transactional messages. For information about the parameters that are returned in trace query results, see Parameters.

• TCP client SDK for Java:

  • The TCP client SDK for Java is upgraded to V2.x.x.Final.

  • The instance must be deployed in one of the following regions: China (Hangzhou), China (Qingdao), China (Beijing), China (Zhangjiakou), China (Hohhot), China (Shenzhen), China (Chengdu), Germany (Frankfurt), and Indonesia (Jakarta).

• TCP client SDK for C++:

  • The TCP client SDK for C++ is upgraded to V3.x.x.

  • The instance can be deployed in any region.

Common scenarios

If a message is not sent or consumed as expected in a production environment, you can use the message trace feature to troubleshoot the issue. You can query the trace of a message by message ID, message key, or topic within a specific time range to check whether the message is sent or consumed as expected.

Example

If you did not receive a message as expected and want to identify the cause based on the relevant logs, perform the following steps to troubleshoot the issue by using the message trace:

1. Collect the information about the message, including the message ID, message key, topic, and approximate point in time when the message was sent.

2. Log on to the ApsaraMQ for RocketMQ console and create a query task based on the collected information to query the message trace.

3. Check the query result and analyze the cause.

   • If Not Consumed is displayed in the trace, you can go to the Groups page to check the consumption status and determine whether the issue is caused by message accumulation. For more information, see View consumer details.

   • If the message is consumed, check the consumption information to find the corresponding consumer client and the time when the message was consumed. Then, log on to the consumer client to view the relevant logs.

Procedure

1. Log on to the ApsaraMQ for RocketMQ console. In the left-side navigation pane, click Instances.

2. In the top navigation bar, select a region, such as China (Hangzhou). On the Instances page, click the name of the instance that you want to manage.

3. In the left-side navigation pane, click Message Trace. In the upper-left corner of the page that appears, click Create Query Task.

4. In the Create Message Trace Query Task panel, configure query conditions based on your business requirements. Then, click OK.

   Important

   Set the time range as accurately as possible to narrow down the query scope and speed up the query.

   The following query methods are supported by the message trace feature:

   • Query by Message ID: This method is recommended for its exact matching and fast speed.

   • Query by Message Key: This method uses fuzzy search. If you use this method, you can query the traces of up to 1,000 messages. This method is suitable only for scenarios in which you did not record the ID of a message but specified the key that uniquely identifies the message.

   • Query by Topic: This method uses range query. This method is suitable for small-message-volume scenarios in which you did not record the message ID or specify the message key. We recommend that you do not use this query method. In most cases, a large number of messages are produced in a topic within a specific time range. If you use this method, you can hardly identify a specific message among the queried messages.

   After you create a query task, you can view the query task on the Message Trace page. If Querying is displayed in the Status column, the message trace cannot be viewed. You can click the button in the upper-right corner of the task list to refresh the task status until the status of the task changes to Query Completed.

Parameters

On the Message Trace page, find your query task and click Query Results in the Actions column. On the page that appears, you can view the sending status and consumption status of the queried messages in the Sending Status and Consumption Status columns. You can also view the sending status and consumption status of each message in the Producer and Consumer sections on the message trace details page. The following table describes the possible sending and consumption status.

FAQ

Why am I unable to query the trace of a message?

• Check whether the SDK version is valid. For information about the versions of SDKs that support the message trace feature, see Versions of SDKs that support the message trace feature.

• Check whether the time range that you specified is valid.

  By default, messages are stored in ApsaraMQ for RocketMQ brokers for 3 days. You can query only the traces of messages that are produced within 3 days before the current point in time. For example, if the current point in time is 15:09:48 on November 30, 2023, you can query the traces of messages that are produced from 15:09:48 on November 27, 2023 to 15:09:48 on November 30, 2023.

  Important

  Message traces may not be retained in ApsaraMQ for RocketMQ brokers for three days due to insufficient storage space. If you want to retain message traces for three days, we recommend that you use ApsaraMQ for RocketMQ Enterprise Platinum Edition instances. These instances allow you to specify a custom storage duration for message traces.

• The trace data of a message may be incomplete because the message trace feature is implemented in asynchronous links. The system may return no result for a query even if the query conditions that you specified are valid. In this case, you can query logs on your client to obtain consumption details. For more information, see Logging settings.

References

You can also query message traces by calling the following API operations provided by ApsaraMQ for RocketMQ:

• OnsTraceQueryByMsgId

• OnsTraceQueryByMsgKey

• OnsTraceGetResult