---
title: "链路追踪"
---

Tracing（链路追踪）对智能体执行过程进行**全链路记录**，是企业级智能体应用实现可观测性的核心。它把一次请求的完整流程——用户输入、模型推理、工具调用、记忆与知识库读写、响应生成——转化为可分析、可追溯的结构化数据，为调试、监控和优化提供依据。

## 在 VeADK 中开启观测

为智能体配置一个 `OpentelemetryTracer`，并指定一个或多个 Exporter，即可开启全链路观测。下例使用 APMPlus Exporter：

<Tabs items={['代码', '所需环境变量']}>
  <Tab value="代码">
    ```python title="examples/tracing/tracing_exporter.py"
    import asyncio
    from veadk import Agent, Runner
    from veadk.tracing.telemetry.exporters.apmplus_exporter import APMPlusExporter
    from veadk.tracing.telemetry.opentelemetry_tracer import OpentelemetryTracer

    # 初始化 Tracing Exporter
    exporters = [APMPlusExporter()]
    tracer = OpentelemetryTracer(exporters=exporters)

    # 定义智能体并挂载 tracer
    agent = Agent(tracers=[tracer])

    runner = Runner(agent=agent)
    response = asyncio.run(runner.run(messages="hi!"))
    print(response)
    ```
  </Tab>
  <Tab value="所需环境变量">
    可通过环境变量配置 Exporter：

    - `OBSERVABILITY_OPENTELEMETRY_APMPLUS_API_KEY`：APM 服务的 API Key
    - `OBSERVABILITY_OPENTELEMETRY_APMPLUS_ENDPOINT`：APM 服务的 Endpoint，例如 `http://apmplus-cn-beijing.volces.com:4317`
    - `OBSERVABILITY_OPENTELEMETRY_APMPLUS_SERVICE_NAME`：APM 的 Service Name，例如 `python_coder_agent    - `OBSERVABILITY_OPENTELEMETRY_TRACE_CONTENT`：是否采集 Agent、LLM 与工具输入输出内容，默认 `true`

    或在 `config.yaml` 中定义：

    ```yaml title="config.yaml"
    observability:
      opentelemetry        trace_content: true
        apmplus:
          endpoint: ...
          api_key: ...
          service_name: ...
    ```
  </Tab>
</Tabs>

开启后，日志中会打印出相关 Tracing 数据的 ID：

![TraceID 示意](/assets/images/observation/show_traceid.jpeg)

针对不同平台的完整接入方式，参见[在火山引擎观测](/cn/docs/framework/ve-tracing)。

## Tracing 的价值

引入 Tracing 后，你可以：

- **调试与定位问题**：快速定位逻辑错误、工具调用失败或模型输出异常发生的环节；
- **性能分析**：通过各模块的执行耗时发现瓶颈，优化模型调用与工具执行策略；
- **审计与合规**：保留完整的请求、响应与决策记录；
- **多 Agent 协调**：分析多 Agent 协作中各 Agent 的调用关系与数据流向。

## Tracing 数据结构

Tracing 数据由一系列 **Span** 组成，每个 Span 记录一次操作（如调用模型、执行工具）的名称、ID、起止时间与属性。下面是单个工具调用 Span 的示例：

```json title="tracing.json"
{
  "name": "execute_tool get_city_weather",
  "span_id": 15420762184471404328,
  "trace_id": 195590910357197178730434145750344919939,
  "start_time": 1762770336065962000,
  "end_time": 1762770336066380000,
  "attributes": {
    "gen_ai.operation.name": "execute_tool",
    "gen_ai.tool.name": "get_city_weather",
    "gen_ai.tool.input": "{\"name\": \"get_city_weather\"}",
    "gen_ai.tool.output": "{\"response\": {\"result\": \"Sunny, 25°C\"}}",
    "cozeloop.input": "{\"name\": \"get_city_weather\"}",
    "cozeloop.output": "{\"response\": {\"result\": \"Sunny, 25°C\"}}"
  },
  "parent_span_id": 18301436667977577407
}
```

各属性字段的含义见[埋点字段说明](/cn/docs/framework/span-attributes)。

在多 Agent 场景中，多个 Span 通过 `parent_span_id` 串联，展现 `coding_agent` 调度 `python_coder` 的完整链路：

```json title="tracing.json"
[
  {
    "name": "execute_tool transfer_to_agent",
    "span_id": 8839983747734433620,
    "trace_id": 161011438572144016825706884868588853689,
    "attributes": {
      "agent.name": "coding_agent",
      "gen_ai.operation.name": "execute_tool",
      "gen_ai.tool.name": "transfer_to_agent"
    },
    "parent_span_id": 5680387922600458423
  },
  {
    "name": "call_llm",
    "span_id": 6376035117066938110,
    "trace_id": 161011438572144016825706884868588853689,
    "attributes": {
      "agent.name": "python_coder",
      "gen_ai.request.model": "openai/doubao-seed-1-8-251228",
      "gen_ai.request.type": "chat",
      "gen_ai.span.kind": "llm",
      "gen_ai.prompt.0.role": "user",
      "gen_ai.prompt.0.content": "使用 Python 帮我写一段快速排序的代码。"
    },
    "parent_span_id": 11028930176666491606
  },
  {
    "name": "invoke_agent python_coder",
    "span_id": 11028930176666491606,
    "trace_id": 161011438572144016825706884868588853689,
    "attributes": {
      "gen_ai.span.kind": "agent",
      "gen_ai.operation.name": "invoke_agent",
      "gen_ai.agent.description": "擅长使用 Python 编程语言来解决问题。",
      "gen_ai.system": "openai",
      "agent.name": "python_coder"
    },
    "parent_span_id": 5680387922600458423
  },
  {
    "name": "invoke_agent coding_agent",
    "span_id": 987150150265236585,
    "trace_id": 161011438572144016825706884868588853689,
    "attributes": {
      "gen_ai.span.kind": "agent",
      "gen_ai.operation.name": "invoke_agent",
      "gen_ai.agent.description": "可以调用适合的智能体来解决用户问题。",
      "gen_ai.system": "openai",
      "agent.name": "coding_agent"
    },
    "parent_span_id": 11431457420615823859
  },
  {
    "name": "invocation",
    "span_id": 11431457420615823859,
    "trace_id": 161011438572144016825706884868588853689,
    "attributes": {
      "gen_ai.operation.name": "chain",
      "gen_ai.span.kind": "workflow",
      "gen_ai.system": "openai",
      "agent.name": "python_coder"
    },
    "parent_span_id": null
  }
]
```

<Callout type="info" title="与 OpenTelemetry 的兼容性">
  VeADK 的字段命名遵循 OpenTelemetry 生成式 AI 规范，你可以直接将 Tracing 数据导入到 OpenTelemetry 兼容的系统中进行分析和可视化。
</Callout>
