Querying Span Data

Function

This API is used to query span data.

URI

POST /v1/apm2/openapi/view/trace/span-search

Request Parameters

**Table 1** Request header parameters
Parameter	Mandatory	Type	Description
x-business-id	Yes	Long	Application ID.
X-Auth-Token	Yes	String	User token obtained from IAM.

**Table 2** Request body parameters
Parameter	Mandatory	Type	Description
region	Yes	String	Region name.
order_param	No	OrderParam object	Sorting parameter.
real_source_full_match	No	Boolean	Whether exact search is performed.
source_full_match	No	Boolean	Full match search.
tags_content	No	String	Search by the header, body, custom parameter, or other tag keywords.
start_time_string	No	String	Start time.
end_time_string	No	String	End time.
time_used_min	No	Long	Minimum duration.
time_used_max	No	String	Maximum duration.
contain_tags_content	No	Boolean	Whether the search result contains tag details.
page_size	No	Integer	Number of records returned on each page.
page	No	Integer	Number of the page on which data is queried. By default, data on the first page is queried.
parameters	No	String	Parameter.
codes	No	Array of integers	Status codes in string format. Multiple status codes can be queried at a time.
global_trace_id	No	String	Virtual trace ID, which may correspond to multiple actual trace IDs. The virtual trace ID will be transferred from the beginning to the end.
global_path	No	String	Path that a virtual trace ID passes through.
trace_id	No	String	Global ID generated when the root span is invoked, which will be transparently transmitted during invocations.
span_id	No	String	ID of an RPC call. For a root span to be invoked, the value is 1. For the next spans to be invoked, the values are 1-1, 1-2, and so on.
env_id	No	Long	Environment ID.
instance_id	No	Long	Instance ID.
app_id	No	Long	Component ID.
biz_id	Yes	Long	Application ID.
domain_id	No	Integer	Tenant ID.
source	No	String	This parameter exists only when a root event exists.
real_source	No	String	URL that is actually invoked. This parameter exists when a root event exists.
start_time	No	Long	Start time.
time_used	No	Long	Time required.
code	No	Integer	Status code, which is valid for HTTP invocation.
class_name	No	String	Class name.
is_async	No	Boolean	Whether the invocation is asynchronous.
tags	No	Map<String,String>	Custom parameters, header or body parameters, httpMethod, bizCode, or parameters that may be added later.
has_error	No	Boolean	Whether an error occurs.
error_reasons	No	String	Error type.
type	No	String	Type.
http_method	No	String	http_method in tags. Only the URL monitoring item has this parameter.
biz_code	No	String	Status code collected.

**Table 3** OrderParam
Parameter	Mandatory	Type	Description
field	No	String	timeUsed: response time. startTime: generation time.
order	No	String	ASC: ascending order. DESC: descending order. Ensure that field is also set. Enumeration values: ASC DESC

Response Parameters

Status code: 200

**Table 4** Response body parameters
Parameter	Type	Description
total	Integer	Total number of returned records.
span_info_list	Array of ClientSpanInfo objects	Span information.

**Table 5** ClientSpanInfo
Parameter	Type	Description
global_trace_id	String	Virtual trace ID.
global_path	String	Path that a virtual trace ID passes through.
trace_id	String	Trace ID.
span_id	String	Span ID.
env_id	Long	Environment ID.
instance_id	Long	Instance ID.
app_id	Long	Component ID.
biz_id	Long	Application ID.
domain_id	Integer	Tenant ID.
source	String	This parameter exists only when a root event exists.
real_source	String	URL that is actually invoked. This parameter exists when a root event exists.
start_time	Long	Start time.
time_used	Long	Time required.
code	Integer	Status code, which is valid for HTTP invocation.
class_name	String	Class name.
is_async	Boolean	Whether the invocation is asynchronous.
tags	Map<String,String>	Custom parameters, header or body parameters, httpMethod, bizCode, or parameters that may be added later.
has_error	Boolean	Whether an error is reported.
error_reasons	String	Error cause.
type	String	Type, such as mysql and kafka.
http_method	String	http_method in tags. Only the URL monitoring item has this parameter.
biz_code	String	Status code collected.

Example Requests

Query the span data whose region ID is xxx" and application ID is 162 in a specified time range.

/v1/apm2/openapi/view/trace/span-search

{
  "region" : "xxx",
  "biz_id" : 162,
  "page" : 1,
  "page_size" : 15,
  "start_time_string" : "2022-10-25 10:03:16",
  "end_time_string" : "2022-10-25 10:23:16",
  "codes" : [ ]
}

Example Responses

Status code: 200

OK: The request is successful.

{
  "total" : 2,
  "span_info_list" : [ {
    "async" : false,
    "global_trace_id" : "16-1666684411910-1326",
    "global_path" : null,
    "trace_id" : "16-1666684411910-1326",
    "span_id" : "1",
    "env_id" : 11,
    "instance_id" : 16,
    "app_id" : 11,
    "biz_id" : 162,
    "domain_id" : 1,
    "source" : "/apm2/health/v1/health-check",
    "real_source" : "/apm2/health/v1/health-check",
    "start_time" : 1666684411910,
    "time_used" : 1,
    "code" : 200,
    "class_name" : "org/apache/catalina/core/StandardHostValve",
    "is_async" : false,
    "tags" : { },
    "has_error" : false,
    "error_reasons" : null,
    "type" : "Tomcat",
    "http_method" : "GET",
    "estimated_start_time" : null,
    "estimated_end_time" : null,
    "biz_code" : null,
    "env_name" : "xxx",
    "instance_name" : "apm2-apm-pu-task-6b5bbfc84d-gtrrs(*.*.*.*)",
    "app_name" : "apm-pu-task",
    "region" : "xxx"
  }, {
    "async" : false,
    "global_trace_id" : "15-1666684400114-1332",
    "global_path" : null,
    "trace_id" : "15-1666684400114-1332",
    "span_id" : "1",
    "env_id" : 11,
    "instance_id" : 15,
    "app_id" : 11,
    "biz_id" : 162,
    "domain_id" : 1,
    "source" : "/apm2/health/v1/health-check",
    "real_source" : "/apm2/health/v1/health-check",
    "start_time" : 1666684400114,
    "time_used" : 0,
    "code" : 200,
    "class_name" : "org/apache/catalina/core/StandardHostValve",
    "is_async" : false,
    "tags" : { },
    "has_error" : false,
    "error_reasons" : null,
    "type" : "Tomcat",
    "http_method" : "GET",
    "estimated_start_time" : null,
    "estimated_end_time" : null,
    "biz_code" : null,
    "env_name" : "xxx",
    "instance_name" : "apm2-apm-pu-task-6b5bbfc84d-rxlhr(*.*.*.*)",
    "app_name" : "apm-pu-task",
    "region" : "xxx"
  } ]
}

Status Codes

Status Code	Description
200	OK: The request is successful.
400	Bad Request: Semantic or parameter error.
401	Unauthorized: No permissions.
403	Forbidden: Access forbidden.
404	Not Found: The requested resource is not found.