Queries the consumption status of a specified message.

Note

  • You can call this operation to check whether a specified message is consumed. If the message is not consumed, you can troubleshoot the issue based on the returned information.
  • This operation queries information based on the default offset mechanism of Message Queue for Apache RocketMQ. In most cases, the results are correct. If you have reset the consumer offset or cleared queued messages, the results may be incorrect.

Request limit

Each Alibaba Cloud account can call this operation up to 10 times per second. If the number of requests that you send to call this operation within one second reaches the request limit, new requests fail. This may interrupt your business. For information about the request limit of each operation, see API request limits.

Authorization

By default, Alibaba Cloud accounts can call this operation. A Resource Access Management (RAM) user can call this operation only after the RAM user is granted the required permissions. The following table describes the permissions that must be granted to a RAM user to call this operation. For information about how to grant permissions, see Policies.

API

Action

Resource in an instance that uses a namespace

Resource in an instance that does not use a namespace

OnsMessageTrace

mq:QueryInstanceBaseInfo

mq:QueryMessageTrace

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

acs:mq:*:*:{topic}

Request parameters

Parameter Type Required Example Description
Action String Yes OnsMessageTrace

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

Topic String Yes test-mq_topic

The topic in which the message you want to query is stored.

MsgId String Yes 1E05791C117818B4AAC23B1BB0CE****

The ID of the message that you want to query.

InstanceId String Yes MQ_INST_111111111111_DOxxxxxx

The ID of the Message Queue for Apache RocketMQ instance which contains the message you want to query.

Response parameters

Parameter Type Example Description
RequestId String EAE5BE23-37A1-4354-94D6-E44AE17E****

The ID of the request. The system generates a unique ID for each request. You can troubleshoot issues based on the request ID.

Data Array of MessageTrack

The data that is returned.

MessageTrack
TrackType String CONSUMED

The status of the message. Valid values:

  • CONSUMED: The message is consumed.
  • CONSUMED_BUT_FILTERED: No consumer groups subscribe to the message. The message is filtered out and not consumed.
  • NOT_CONSUME_YET: The message is not consumed.
  • NOT_ONLINE: The consumer group is offline.
  • UNKNOWN: The message is not consumed due to unknown reasons.
ConsumerGroup String GID_test_group_id

The ID of the consumer group that subscribes to the topic.

InstanceId String MQ_INST_111111111111_DOxxxxxx

The ID of the Message Queue for Apache RocketMQ instance which contains the message.

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 

HTTP/1.1 200 OK
Content-Type:application/xml

<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 

HTTP/1.1 200 OK
Content-Type:application/json

{
  "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.

Query the consumption status of a message in the console

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