All Products
Search
Document Center

ApsaraMQ for RocketMQ:Query message traces

Last Updated:Feb 07, 2024

The processing of a message in ApsaraMQ for RocketMQ involves the following key activities: message sending, message storage, and message consumption. ApsaraMQ for RocketMQ defines data related to the activities as trace parameters. A message trace includes the message sending result, the sending duration, the time when the message arrives at the broker, the message consumption result, the consumption duration, and the client information. ApsaraMQ for RocketMQ allows you to query message traces in a visualized manner. If a message is not sent or consumed as expected or you want to track a specific message, you can query the trace of the message to obtain the processing status of the message in each activity.

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. The message trace feature takes effect on all types of messages. Before you use this feature, take note of the following points.

Time range for message trace queries

By default, messages are stored on 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

Message type

Description

Normal messages

If the message is not consumed, Not Consumed is displayed. After the message is consumed, the sending information and consumption information are displayed.

Ordered messages

If the message is not consumed, Not Consumed is displayed. After the message is consumed, the sending information and consumption information are displayed.

Scheduled messages and delayed messages

If the current system time is earlier than the specified point in time for consumption, the trace of the message can be queried, but the message cannot be queried.

Transactional messages

Before the local transaction for a message is committed, the trace of the message can be queried, but the message cannot be queried.

Versions of SDKs that support the message trace feature

Protocol

Language

Version

Description

TCP

Java

V1.2.7.Final and later

Release notes for the SDK for Java

C/C++

V1.1.2 and later

Release notes for the SDK for C and C++

.NET

V1.1.2 and later

Release notes for the SDK for .NET

HTTP

Node.js

V1.0.2 and later

Usage notes for HTTP client SDKs

Others

V1.0.1 and later

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 consumer details 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 refresh 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

Note

The following parameters can be viewed in the console only if your instance and client SDK version meet the prerequisites of using the enhanced message tracing feature. For more information, see Prerequisites for using the enhanced message trace feature.

  • AccessKey in the Producer section

  • Arrive at Server At, Scheduled to Be Delivered At, Delivered At, and Committed/Rolled back At in the MQ Server section

  • Arrive at Consumer At and Wait Duration before Processing in the Consumer section

Table 1. Parameters

Section

Parameter

Description

Basic Information

Message ID

The globally unique identifier of the message. This identifier is automatically generated by the ApsaraMQ for RocketMQ system.

Topic

The topic to which the message belongs.

Message Key

The business identifier of the message. The message key is specified by the message producer and uniquely identifies a business logic.

Message Tag

The tag that is used to classify messages in a topic.

Producer

AccessKey

The AccessKey ID of your Alibaba Cloud account or Resource Access Management (RAM) user. AccessKey IDs are used to verify user identities. When you use SDKs or call API operations to access ApsaraMQ for RocketMQ resources, the AccessKey ID is required for identity verification.

Client IP Address

The client IP address of the message producer.

Message Produced At

The timestamp that indicates when the message was sent from the producer.

Sending RT

The amount of time that is consumed to send the message. Unit: milliseconds.

Sending Status

The status of the message sending task. For more information, see Sending Status in Message status.

MQ Server

Message Type

Note

Scheduled Message is displayed for the Message Type parameter, regardless of whether the message is a scheduled message or a delayed message.

Arrive at Server At

The time when the message arrived at the ApsaraMQ for RocketMQ broker.

Scheduled to Be Delivered At

The scheduled point in time when a scheduled message can be delivered to the consumer.

Delivered At

The time when the message can be delivered to the consumer.

Committed/Rolled back At

The time when a transaction is committed or rolled back.

Consumer

AccessKey

The AccessKey ID of your Alibaba Cloud account or RAM user. AccessKey IDs are used to verify user identities. When you use SDKs or call API operations to access ApsaraMQ for RocketMQ resources, the AccessKey ID is required for authentication.

Arrive at Consumer At

The time when the message arrived at the consumer client.

Wait Duration before Processing

The duration between the time when the message arrived at the consumer client and the time when the message started to be consumed.

Delivery Result

A message may need to be delivered multiple times before it is consumed. This parameter indicates the result of one specific delivery. For more information, see Consumption Status in Message status.

Client IP Address

The IP address of the consumer client.

Message Processing Started At

The timestamp that indicates when the message started to be consumed by the client.

Message Processing Complete At

The timestamp that indicates when the consumer completed message consumption.

Message Processing Duration

The amount of time that is used by the consumer to consume the message.

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.

Table 2. Message status

Type

State

Sending Status

Sent

Failed

Scheduling

Transactional Message Not Committed

Transactional Message Rolled Back

Consumption Status

All Successful

Partially Successful

All Failed

Not Consumed

No Consumption Result Returned

Consumed

Failed

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 on 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.

  • 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: