如何使用Dynatrace API通过traceID获取分布式追踪信息

前置准备 #

• 先在你的Dynatrace环境生成API访问令牌，令牌必须勾选Trace viewer（读取追踪数据）权限，无权限调用会直接返回403错误
• 确认你的环境访问地址：SaaS版格式为https://<你的环境标识>.live.dynatrace.com，自建托管版使用你实际部署的环境域名即可

接口说明 #

查询单条分布式追踪全量信息直接用Trace v2接口的单trace查询端点即可，请求方式为GET，直接把目标traceID拼在请求路径里，不需要额外传复杂查询参数。
接口路径：/api/v2/traces/{traceId}
返回结果包含全链路span列表、服务调用关系、各节点耗时、错误标记、关联日志/指标映射等所有分布式追踪相关的结构化数据，可以直接解析后对接自定义仪表盘的渲染逻辑。

可运行调用示例 #

curl命令示例 #

# 替换尖括号内的占位符为你的实际环境信息即可直接执行
curl -X GET "https://<YOUR_DYNATRACE_ENV_URL>/api/v2/traces/<TARGET_TRACE_ID>" \
  -H "Authorization: Api-Token <YOUR_API_TOKEN>" \
  -H "Content-Type: application/json"

Python调用示例（依赖requests库） #

import requests

# 以下配置项替换为你的实际信息
ENV_BASE_URL = "https://<YOUR_DYNATRACE_ENV_URL>"
API_TOKEN = "<YOUR_GENERATED_API_TOKEN>"
QUERY_TRACE_ID = "<TRACE_ID_TO_FETCH>"

request_headers = {
    "Authorization": f"Api-Token {API_TOKEN}",
    "Content-Type": "application/json"
}

resp = requests.get(
    f"{ENV_BASE_URL}/api/v2/traces/{QUERY_TRACE_ID}",
    headers=request_headers
)

if resp.status_code == 200:
    # 拿到结构化追踪数据，按需解析对接仪表盘即可
    trace_detail = resp.json()
    print(trace_detail)
else:
    print(f"请求异常，状态码{resp.status_code}，返回：{resp.text}")

注意事项 #

• 如果不需要全量返回字段，可以在请求中追加fields查询参数指定需要返回的字段，降低数据传输量，比如?fields=spanCount,duration,spans.tags就只会返回span总数、链路总耗时、各span的标签信息
• 传入的traceID必须和Dynatrace采集存储的格式完全一致，注意不要带多余空格、截断字符，否则会返回404
• 可查询的trace时间范围受你环境配置的追踪数据留存周期限制，超过留存期的数据会被清理，无法通过接口拉取
• 不要用单trace查询接口循环批量拉取数据，批量查询请使用/api/v2/traces端点搭配时间范围、过滤条件拉取，避免触发接口限流规则
• 对应接口的版本适配、字段枚举说明，可以直接登录你的Dynatrace环境，在右上角帮助中心搜索「Get trace by ID」查看和你当前环境版本完全匹配的官方说明，不同部署版本的字段可能存在细微差异。

内容的提问来源于stack exchange，提问作者san kumar