Call the DescribeTrace API to query the list of spans under a trace using the specified trace instance ID and TraceID

Request instructions

Request method: POST

Request URL: https://{tls-endpoint}/DescribeTrace

Request parameters

The table below lists only the unique request parameters for this API and some common parameters For more details, see Common Parameters

Body

Parameters	Type	Required	Example value	Description
TraceId	String	Yes	ef97a7****	Trace ID.
TraceInstanceId	String	Yes	0fdaa6b6-3c9f-424c-8664-fc0d222c****	Trace instance ID.

Response parameters

The table below only lists the response parameters specific to this API. For more information, see Return Structure.

Parameters	Type	Example value	Description
Trace	Object of Trace	/	Trace details, including the list of all Spans under this Trace.

Trace

Parameters	Type	Example value	Description
Spans	Array of Span	/	Contains the list of all spans under this trace. Each span represents an operation or event and includes details such as operation type, name, and timestamp.

Span

Parameters	Type	Example value	Description
Kind	String	SPAN_KIND_SERVER	The type of Span, used to identify the role of this Span in distributed tracing. The supported values are as follows. SPAN_KIND_UNSPECIFIED: Unspecified type; SPAN_KIND_INTERNAL: internal operation SPAN_KIND_SERVER: server receives request SPAN_KIND_CLIENT: client sends request SPAN_KIND_PRODUCER: message producer SPAN_KIND_CONSUMER: message consumer
Name	String	HTTP GET /api/users	The name of the Span identifies the operation or event represented by this Span.
Links	Array of SpanLink	[{"SpanId":"3e4f5a6b7c8d9e0f","TraceId":"1a2b3c4d5e6f7g8h","Attributes":[{"Key":"link.type","Value":"child"}],"TraceState":"vendor1=value1,vendor2=value2"}]	Link list of the Span shows the associations between the current Span and other Spans. Each link contains the target Span’s TraceId and SpanId, as well as optional attributes and trace states.
Events	Array of SpanEvent	[{"Name":"cache.hit","Timestamp":1622548800000000,"Attributes":[{"Key":"cache.key","Value":"user_123"}]}]	Span event list, used to record specific events in the Span lifecycle. Each event contains a name, timestamp, and an optional list of attributes.
SpanId	String	3e4f5a6b7c8d****	ID that uniquely identifies a Span within a Trace, used to distinguish different operations or events.
Status	Object of Status	{"Code":"OK","Message":"Operation successful"}	Status information for the Span includes a status code and error message. Status codes are as follows. UNSET: Status not set OK: Operation succeeded ERROR: Operation failed.
EndTime	Integer	1622548800000000	End time of Span, measured in microseconds, indicating when the operation or event was completed.
TraceId	String	ef97a7****	Trace ID.
Resource	Object of Resource	/	Resource information associated with Span, including a list of attributes describing the resource.
StartTime	Integer	1622548800000000	Start time of the Span in microseconds, representing when the operation or event began.
Attributes	Array of KeyValue	[{"Key":"http.method","Value":"GET"},{"Key":"http.status_code","Value":"200"}]	Property list of Span, used to store additional information related to Span. Each property consists of a key-value pair.
TraceState	String	vendor1=value1,vendor2=value2	Trace status information that follows the W3C Trace Context specification tracestate header format. It is used to pass vendor-specific tracing status information. Separate multiple key-value pairs with commas. Each pair consists of the vendor name and its corresponding value.
ParentSpanId	String	1a2b3c4d5e6f****	Unique identifier of the parent Span, representing the direct parent Span of the current Span. If the current Span is the root node, this field is empty.
InstrumentationLibrary	Object of InstrumentationLibrary	{"Name":"opentelemetry-java","Version":"1.0.0"}	Span detection library information, including the name and version of the detection library that generated this Span.

SpanLink

Parameters	Type	Example value	Description
SpanId	String	3e4f5a6b7c8d****	An ID that uniquely identifies a Span within a Trace. It is used to distinguish different operations or events.
TraceId	String	ef97a7****	Trace ID.
Attributes	Array of KeyValue	[{"Key":"http.method","Value":"GET"},{"Key":"http.status_code","Value":"200"}]	Span attribute list, used to store additional information related to the Span. Each attribute is a key-value pair.
TraceState	String	vendor1=value1,vendor2=value2	Status information of Trace, following the tracestate header format in the W3C Trace Context specification, used to transmit vendor-specific trace state information. Separate multiple key-value pairs with commas. Each pair consists of a vendor name and the corresponding value.

SpanEvent

Parameters	Type	Example value	Description
Name	String	cache.hit	Span event name used to identify specific events that occur in a Span's lifecycle, such as cache hits or database queries.
Timestamp	Integer	1622548800000000	Timestamp of the Span event in microseconds, indicating the exact time when the event occurred.
Attributes	Array of KeyValue	[{"Key":"http.method","Value":"GET"},{"Key":"http.status_code","Value":"200"}]	Span attribute list, used to store additional information related to the Span. Each attribute is made up of a key-value pair.

Status

Parameters	Type	Example value	Description
Code	String	OK	The status code of Span indicates the result of the operation or event represented by this Span. Supported values are as follows. UNSET: Status not set. OK: Operation successful. ERROR: Operation failed.
Message	String	/	Error message in Span status, describing the specific cause or details of an operation failure.

Resource

Parameters	Type	Example value	Description
Attributes	Array of KeyValue	[{"Key":"service.name","Value":"user-service"},{"Key":"service.version","Value":"1.0.0"},{"Key":"deployment.environment","Value":"production"}]	Span attribute list for linked resources, used to describe additional information about the resource. Each attribute consists of a key-value pair.

KeyValue

Parameters	Type	Example value	Description
Key	String	http.method	The key of the Span attribute is used to identify the attribute name, usually to store additional information related to Span, such as HTTP methods or status codes.
Value	String	GET	Specific values of the Span attribute are used to store additional information related to the Span, such as HTTP method and status code.

InstrumentationLibrary

Parameters	Type	Example value	Description
Name	String	opentelemetry-java	The name of the detection library that generated this span, used to identify the library or framework that created the span.
Version	String	1.0.0	The version number of the detection library for this Span identifies the specific library or framework version that created the Span.

Sample request

Sample response

Error Code

You can visit Public Error Code to get more information about error codes.

Torch Log Service