Queries the consumption status of a message by specifying the message ID.

Usage notes

  • You can call this operation to determine the message consumption status and identity possible causes of consumption exceptions.
  • This operation is implemented based on the internal offset mechanism of Message Queue for Apache RocketMQ. In most cases, the results are correct. However, if you have reset the offset or cleared messages, the results may not be correct.

QPS limit

The queries-per-second (QPS) limit on this operation is 10 per user. Throttling is triggered when the number of calls to this operation per second exceeds the QPS limit. Throttling may affect your business. Therefore, call this operation based on your needs. For more information, see QPS limits.

Authorization information

By default, only Alibaba Cloud accounts can call this operation. RAM users can call this operation only after they are authorized to use it. The following table lists the authorization information of this operation. For more information, see Policies and examples.

API

Action

Resource with a namespace

Resource without a namespace

OnsMessageTrace

mq:QueryMessageTrace

acs:mq:*:*:{instanceId}%{topic}

acs:mq:*:*:{topic}

Debugging

OpenAPI Explorer automatically calculates the signature value. For your convenience, we recommend that you call this operation in OpenAPI Explorer. OpenAPI Explorer dynamically generates the sample code of the operation for different SDKs.

Request parameters

Parameter Type Required Example Description
Action String Yes OnsMessageTrace

The operation that you want to perform. Set the value to OnsMessageTrace.

InstanceId String Yes MQ_INST_111111111111_DOxxxxxx

The ID of the Message Queue for Apache RocketMQ instance that corresponds to the message whose consumption status you want to query.

MsgId String Yes 1E05791C117818B4AAC23B1BB0CE****

The ID of the message whose consumption status you want to query.
Topic String Yes test-mq_topic

The topic of the message.

Response parameters

Parameter Type Example Description
Data Array of MessageTrack

The query results.
MessageTrack
ConsumerGroup String GID_test_group_id

The group ID of the consumer that subscribes to the topic.
InstanceId String MQ_INST_111111111111_DOxxxxxx

The ID of the Message Queue for Apache RocketMQ instance that corresponds to the message.
TrackType String CONSUMED

The current status of the message. Valid values:

  • CONSUMED: The message is consumed.
  • CONSUMED_BUT_FILTERED: The message is filtered out and not consumed.
  • NOT_CONSUME_YET: The message is not consumed.
  • NOT_ONLINE: The consumer is offline.
  • UNKNOWN: The message is in an unknown state.
RequestId String EAE5BE23-37A1-4354-94D6-E44AE17E****

The ID of the request, which is a common parameter. Each request has a unique ID to facilitate troubleshooting and fault locating.

Examples

Sample requests

http(s)://ons.cn-hangzhou.aliyuncs.com/? Action=OnsMessageTrace
&InstanceId=MQ_INST_111111111111_DOxxxxxx
&MsgId=1E05791C117818B4AAC23B1BB0CE****
&Topic=test-mq_topic
&<Common request parameters>

Sample success responses

XML format 

<OnsMessageTraceResponse>
  <Data>
        <MessageTrack>
              <InstanceId>MQ_INST_111111111111_DOxxxxxx</InstanceId>
              <ConsumerGroup>GID_test_group_id</ConsumerGroup>
              <TrackType>CONSUMED</TrackType>
        </MessageTrack>
  </Data>
  <RequestId>EAE5BE23-37A1-4354-94D6-E44AE17****</RequestId>
</OnsMessageTraceResponse>

JSON format 

{
    "Data": {
        "MessageTrack": [
            {
                "InstanceId": "MQ_INST_111111111111_DOxxxxxx",
                "ConsumerGroup": "GID_test_group_id",
                "TrackType": "CONSUMED"
            }
        ]
    },
    "RequestId": "EAE5BE23-37A1-4354-94D6-E44AE17E****"
}

Error codes

For a list of error codes, visit the API Error Center.

Operations in the console

In addition to calling the OnsMessageTrace operation, you can query the consumption status of a message in the Message Queue for Apache RocketMQ console. For more information, see Query a message trace.