GetTrace - ApsaraMQ for RocketMQ - Alibaba Cloud Documentation Center

Retrieves the trace of a specified message in a specified topic.

Try it now

Try this API in OpenAPI Explorer, no manual signing needed. Successful calls auto-generate SDK code matching your parameters. Download it with built-in credential security for local usage.

Test

RAM authorization

The table below describes the authorization required to call this API. You can define it in a Resource Access Management (RAM) policy. The table's columns are detailed below:

Action: The actions can be used in the Action element of RAM permission policy statements to grant permissions to perform the operation.
API: The API that you can call to perform the action.
Access level: The predefined level of access granted for each API. Valid values: create, list, get, update, and delete.
Resource type: The type of the resource that supports authorization to perform the action. It indicates if the action supports resource-level permission. The specified resource must be compatible with the action. Otherwise, the policy will be ineffective.
- For APIs with resource-level permissions, required resource types are marked with an asterisk (*). Specify the corresponding Alibaba Cloud Resource Name (ARN) in the Resource element of the policy.
- For APIs without resource-level permissions, it is shown as All Resources. Use an asterisk (*) in the Resource element of the policy.
Condition key: The condition keys defined by the service. The key allows for granular control, applying to either actions alone or actions associated with specific resources. In addition to service-specific condition keys, Alibaba Cloud provides a set of common condition keys applicable across all RAM-supported services.
Dependent action: The dependent actions required to run the action. To complete the action, the RAM user or the RAM role must have the permissions to perform all dependent actions.

Action

Access level

Resource type

Condition key

Dependent action

rocketmq:GetTrace

get

*Topic

acs:rocketmq:{#regionId}:{#accountId}:instance/{#InstanceId}/topic/{#TopicName}

None

Request syntax

GET /instances/{instanceId}/topics/{topicName}/traces/{messageId} HTTP/1.1

Path Parameters

Parameter	Type	Required	Description	Example
instanceId	string	Yes	The ID of the instance to query.	rmq-cn-zvp2vtypu05
topicName	string	Yes	The name of the topic to query.	linkedcare-image
messageId	string	Yes	The message ID.	012A5AB0BBEC8A000104C6342B00001ECF

Request parameters

Parameter	Type	Required	Description	Example
startTime	string	No	The start time.	2023-05-10 10:42:11
endTime	string	No	The end time.	2024-09-09 09:00:00

Response elements

Element	Type	Description	Example
	object	The response.
requestId	string	The request ID. Each request has a unique ID. You can use this ID to troubleshoot issues.	7779A8FC-1BCD-5A1D-A603-C4A9BD8ADC49
success	boolean	Indicates whether the request was successful.	true
data	object	The returned data.
regionId	string	The region ID.	cn-hangzhou
instanceId	string	The instance ID.	rmq-cn-7e22ody****
topicName	string	The topic name.	topic_test
messageInfo	object	The message information.
regionId	string	The region ID.	cn-beijing
instanceId	string	The instance ID.	rmq-cn-u0t2ygjq505
topicName	string	The topic name.	Topic_normal_inspector
messageId	string	The message ID.	0A79275A00207A4F0F2916C92F9A0B94
bornTime	string	The time when the message was generated.	2023-03-22 12:17:08
storeTime	string	The time when the message was stored.	2023-03-22 12:17:08
body	string	The message body.	{}
bornHost	string	The source of the message.	x.x.x.x
storeHost	string	The location where the message is stored.	x.x.x.x
messageType	string	The message type.	NORMAL
messageTag	string	The list of tags.	xx
messageGroup	string	The former sharding key. This parameter is specific to ordered messages.	xx
messageKeys	array	The business ID.
	string	The business ID.	xx
userProperties	object	The user-defined properties.
	string	The user-defined properties.	xx
transactionId	string	The transaction ID.	xx
liteTopicName	string	The name of the lightweight topic.	abc
producerInfo	object	The trace information of the producer.
records	array<object>	The list of production records.
	object	The list of production records.
userName	string	The producer name.	xxx
clientHost	string	The hostname.	xx.xx.xx.xx
produceTime	string	The time when the message was sent.	2023-03-22 12:17:08
produceDuration	integer	The time taken to send the message.	100
produceStatus	string	The sending status.	SUCCESS
arriveTime	string	The arrival time.	2023-03-22 12:17:08
messageSource	string	The message source.	CONSOLE
dlqOriginTopic	string	The dead-letter queue topic.	test_topic
dlqOriginMessageId	string	The ID of the message in the dead-letter queue.	0A79275A00207A4F0F2916C92F9A0B94
recallTime	string	The time when the revoke request was initiated. This field is not empty when `messageSource` is `recall`.	空 \| 2023-03-22 12:17:08
brokerInfo	object	The trace information of the broker.
presetDelayTime	string	The preset delivery time.	2023-03-22 12:17:08
delayStatus	string	The status of the scheduled message.	SUCCESS
operations	array<object>	The list of operations.
	object	The list of operations.
operateType	string	The operation type.	ADD
operateTime	string	The operation time.	2023-03-22 12:17:08
recallResult	string	The result of the revoke operation. This field is not empty when a revoke record exists.	空 \| RECALL_OK \| RECALL_FAIL
consumerInfos	array<object>	The trace information of the consumer.
	array<object>	The trace information of the consumer.
consumerGroupId	string	The consumer group ID.	GID_inspector_group
records	array<object>	The list of consumption records.
	array<object>	The list of consumption records.
userName	string	The consumer name.	test
clientHost	string	The hostname.	xx.xx.xx.xx
fifoEnable	boolean	Indicates whether messages are consumed in order.	true
consumeStatus	string	The consumption status.	SUCCESS
operations	array<object>	The list of operations.
	object	The list of operations.
operateType	string	The operation type.	ADD
operateTime	string	The operation time.	2023-03-22 12:17:08
invisibleTime	integer	The invisibility duration, in milliseconds.	100
deadMessage	boolean	Indicates whether the message is a dead-letter message.	true
popCk	string	The POP checkpoint.	123
consumeStatus	string	The consumption status.	SUCCESS
deadMessage	boolean	Indicates whether the message is a dead-letter message.	true
deadLetterInfo	object	The information about the dead-letter message.
topicName	string	The topic name.	Register_Sync
messageId	string	The message ID.	7F000001001F7A4F0F29463F0376047D
toDlqTime	string	The time when the message arrived at the dead-letter queue.	2023-03-22 12:17:08
code	string	The error code.	InvalidConsumerGroupId
message	string	The error message.	The instance cannot be found.
httpStatusCode	integer	The HTTP status code.	200
dynamicCode	string	The dynamic error code.	InstanceId
dynamicMessage	string	The dynamic error message.	instanceId

Examples

Success response

JSON format

{
  "requestId": "7779A8FC-1BCD-5A1D-A603-C4A9BD8ADC49",
  "success": true,
  "data": {
    "regionId": "cn-hangzhou",
    "instanceId": "rmq-cn-7e22ody****",
    "topicName": "topic_test",
    "messageInfo": {
      "regionId": "cn-beijing",
      "instanceId": "rmq-cn-u0t2ygjq505",
      "topicName": "Topic_normal_inspector",
      "messageId": "0A79275A00207A4F0F2916C92F9A0B94",
      "bornTime": "2023-03-22 12:17:08",
      "storeTime": "2023-03-22 12:17:08",
      "body": "{}",
      "bornHost": "x.x.x.x",
      "storeHost": "x.x.x.x",
      "messageType": "NORMAL",
      "messageTag": "xx",
      "messageGroup": "xx",
      "messageKeys": [
        "xx"
      ],
      "userProperties": {
        "key": "xx"
      },
      "transactionId": "xx",
      "liteTopicName": "abc"
    },
    "producerInfo": {
      "records": [
        {
          "userName": "xxx",
          "clientHost": "xx.xx.xx.xx",
          "produceTime": "2023-03-22 12:17:08",
          "produceDuration": 100,
          "produceStatus": "SUCCESS",
          "arriveTime": "2023-03-22 12:17:08",
          "messageSource": "CONSOLE",
          "dlqOriginTopic": "test_topic",
          "dlqOriginMessageId": "0A79275A00207A4F0F2916C92F9A0B94",
          "recallTime": "空 | 2023-03-22 12:17:08"
        }
      ]
    },
    "brokerInfo": {
      "presetDelayTime": "2023-03-22 12:17:08",
      "delayStatus": "SUCCESS",
      "operations": [
        {
          "operateType": "ADD",
          "operateTime": "2023-03-22 12:17:08"
        }
      ],
      "recallResult": "空 | RECALL_OK | RECALL_FAIL"
    },
    "consumerInfos": [
      {
        "consumerGroupId": "GID_inspector_group",
        "records": [
          {
            "userName": "test",
            "clientHost": "xx.xx.xx.xx",
            "fifoEnable": true,
            "consumeStatus": "SUCCESS",
            "operations": [
              {
                "operateType": "ADD",
                "operateTime": "2023-03-22 12:17:08",
                "invisibleTime": 100,
                "deadMessage": true
              }
            ],
            "popCk": "123"
          }
        ],
        "consumeStatus": "SUCCESS",
        "deadMessage": true,
        "deadLetterInfo": {
          "topicName": "Register_Sync",
          "messageId": "7F000001001F7A4F0F29463F0376047D",
          "toDlqTime": "2023-03-22 12:17:08"
        }
      }
    ]
  },
  "code": "InvalidConsumerGroupId",
  "message": "The instance cannot be found.",
  "httpStatusCode": 200,
  "dynamicCode": "InstanceId",
  "dynamicMessage": "instanceId"
}

Error codes

See Error Codes for a complete list.

Release notes

See Release Notes for a complete list.