文档首页/ 应用性能管理 APM/ API参考（2.0）/ API/ VIEW/ 查询span数据
更新时间：2025-02-12 GMT+08:00
在线调试
CLI示例
查看PDF
分享

查询span数据

功能介绍

span数据查询接口。

URI

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

请求参数

表1 请求Header参数

参数

是否必选

参数类型

描述

x-business-id

是

Long

应用id。

X-Auth-Token

是

String

从IAM服务获取的用户Token。
表2 请求Body参数

参数

是否必选

参数类型

描述

region

是

String

region名称。

order_param

否

OrderParam object

排序参数。

real_source_full_match

否

Boolean

是否为精确搜索。

source_full_match

否

Boolean

全匹配搜索。

tags_content

否

String

header或body体，或自定义参数，或其他tags里字段的关键词搜索。

start_time_string

否

String

开始时间。

end_time_string

否

String

结束时间。

time_used_min

否

Long

最小耗时。

time_used_max

否

String

最大耗时。

contain_tags_content

否

Boolean

搜索结果是否包含tags内容详情。

page_size

否

Integer

每一页返回的行数。

page

否

Integer

查询第几页的数据,默认查询第一页。

parameters

否

String

参数。

codes

否

Array of integers

字符串格式的的状态码，用于支持多个状态码查询。

global_trace_id

否

String

vTraceId，虚拟traceId，一个vTraceId对应多个实际的traceId， vTraceId会从开始一直往下应用传输。

global_path

否

String

虚拟traceId经过的path路径。

trace_id

否

String

在root的span调用产生的全局id，以此往后透传。

span_id

否

String

代表一次rpc的调用的id，对于root的调用，值为字符串1，对于当前span调用的下一个spanId编号为1-1,1-2等格式，以此往后类推。

env_id

否

Long

环境id。

instance_id

否

Long

实例id。

app_id

否

Long

组件id。

biz_id

是

Long

应用id。

domain_id

否

Integer

租户id。

source

否

String

只有是根event也就是span的时候有值。

real_source

否

String

根event 的时候存在，实际调用的url。

start_time

否

Long

开始时间。

time_used

否

Long

耗时。

code

否

Integer

状态码，针对http的调用有效。

class_name

否

String

类名。

is_async

否

Boolean

是否异步的event。

tags

否

Map<String,String>

包含用户自定义参数，header或body体里的内容，httpMethod, bizCode，以及后续可能新增参数。

has_error

否

Boolean

是否有错误。

error_reasons

否

String

错误类型。

type

否

String

类型。

http_method

否

String

这里的method实际上是tags里面的http_method，只有url监控项才有。

biz_code

否

String

业务状态码的采集。
表3 OrderParam

参数

是否必选

参数类型

描述

field

否

String

timeUsed：响应时间，startTime：产生时间。

order

否

String

ASC：正序，DESC：逆序。填入时需要同时保证参数field填入。

枚举值：

  • ASC
  • DESC

响应参数

状态码： 200

表4 响应Body参数

参数

参数类型

描述

total

Integer

返回的总数。

span_info_list

Array of ClientSpanInfo objects

span信息。
表5 ClientSpanInfo

参数

参数类型

描述

global_trace_id

String

vTraceId，虚拟traceI。

global_path

String

虚拟traceId经过的path路径。

trace_id

String

traceId。

span_id

String

span id。

env_id

Long

环境Iid。

instance_id

Long

实例id。

app_id

Long

组件id。

biz_id

Long

应用id。

domain_id

Integer

租户id。

source

String

只有是根event也就是span的时候有值。

real_source

String

根event 的时候存在，实际调用的url。

start_time

Long

开始时间。

time_used

Long

耗时。

code

Integer

状态码，针对http的调用有效。

class_name

String

类名。

is_async

Boolean

是否异步。

tags

Map<String,String>

包含用户自定义参数，header或body体里的内容，httpMethod, bizCode，以及后续可能新增参数。

has_error

Boolean

是否报错。

error_reasons

String

报错原因。

type

String

类型，mysql，kafka等。

http_method

String

这里的method实际上是tags里面的http_method，只有url监控项才有。

biz_code

String

业务状态码的采集。

请求示例

分页查询region ID为xxx-roma-2，应用ID为162，指定起止时间的span数据。

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

{
  "region" : "xxx-roma-2",
  "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" : [ ]
}

响应示例

状态码： 200

OK，请求响应成功。

{
  "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-roma-2",
    "instance_name" : "apm2-apm-pu-task-6b5bbfc84d-gtrrs(172.16.3.7)",
    "app_name" : "apm-pu-task",
    "region" : "xxx-roma-2"
  }, {
    "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-roma-2",
    "instance_name" : "apm2-apm-pu-task-6b5bbfc84d-rxlhr(*.*.*.*)",
    "app_name" : "apm-pu-task",
    "region" : "xxx-roma-2"
  } ]
}

状态码

状态码

描述

200

OK，请求响应成功。

400

Bad Request，语义或参数有误。

401

Unauthorized，没有权限。

403

Forbidden，禁止访问。

404

Not Found，没有找到要请求的资源。

错误码

请参见错误码。

父主题： VIEW