Debug Message Traces Using the GetTrace API - ApsaraMQ for RocketMQ - Alibaba Cloud - ApsaraMQ for RocketMQ

Retrieves the message trace for 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, in YYYY-MM-DD HH:mm:ss format.	2023-05-10 10:42:11
endTime	string	No	The end time, in YYYY-MM-DD HH:mm:ss format.	2024-09-09 09:00:00

Response elements

Element	Type	Description	Example
	object	result
requestId	string	The request ID. Each request has a unique ID that you can use to troubleshoot issues.	7779A8FC-1BCD-5A1D-A603-C4A9BD8ADC49
success	boolean	Indicates whether the request was successful.	true
data	object	The returned result.
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, in YYYY-MM-DD HH:mm:ss format.	2023-03-22 12:17:08
storeTime	string	The time when the message was stored in the log broker, in YYYY-MM-DD HH:mm:ss format.	2023-03-22 12:17:08
body	string	The message body.	{}
bornHost	string	The origin of the message.	x.x.x.x
storeHost	string	The log broker address 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 previous sharding key. This field is exclusive to ordered messages.	xx
messageKeys	array	The message key.
	string	The message key.	xx
userProperties	object	The user properties.
	string	The user properties.	xx
transactionId	string	The transaction ID.	xx
liteTopicName	string	The lite topic name.	abc
producerInfo	object	The producer message trace information.
records	array<object>	The list of producer records.
	object	The list of producer records.
userName	string	The producer name.	xxx
clientHost	string	The hostname.	xx.xx.xx.xx
produceTime	string	The time when the message was sent, in YYYY-MM-DD HH:mm:ss format.	2023-03-22 12:17:08
produceDuration	integer	The time taken to send the message.	100
produceStatus	string	The send status.	SUCCESS
arriveTime	string	The time when the message arrived, in YYYY-MM-DD HH:mm:ss format.	2023-03-22 12:17:08
messageSource	string	The message source.	CONSOLE
dlqOriginTopic	string	The dead-letter queue topic.	test_topic
dlqOriginMessageId	string	The dead-letter queue message ID.	0A79275A00207A4F0F2916C92F9A0B94
recallTime	string	The time when the recall request was initiated. This field is non-empty when messageSource is "recall".	2023-03-22 12:17:08
brokerInfo	object	The broker message trace information.
presetDelayTime	string	The preset delivery time, in YYYY-MM-DD HH:mm:ss format.	2023-03-22 12:17:08
delayStatus	string	The scheduled message 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, in YYYY-MM-DD HH:mm:ss format.	2023-03-22 12:17:08
recallResult	string	The recall result. This field is non-empty when a recall record exists.	RECALL_OK \| RECALL_FAIL
consumerInfos	array<object>	The consumer message trace information.
	array<object>	The consumer message trace information.
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 ordered consumption is enabled.	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, in YYYY-MM-DD HH:mm:ss format.	2023-03-22 12:17:08
invisibleTime	integer	The invisible time, in milliseconds.	100
deadMessage	boolean	Indicates whether the message is a dead-letter message.	true
popCk	string	POP_CK	123
consumeStatus	string	The consumption status.	SUCCESS
deadMessage	boolean	Indicates whether the message is a dead-letter message.	true
deadLetterInfo	object	The dead-letter message information.
topicName	string	The topic name.	Register_Sync
messageId	string	The message ID.	7F000001001F7A4F0F29463F0376047D
toDlqTime	string	The time when the message arrived in the dead-letter queue, in YYYY-MM-DD HH:mm:ss format.	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": "Empty | 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": "Empty | 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.