概述 - AgentKit 文档

VeADK 通过运行日志和调用链追踪帮助定位模型、工具及执行流程的问题。日志记录离散事件；追踪将一次请求中的多个操作关联起来，便于查看耗时和调用关系追踪使用 OpenTelemetry 的 span 与生成式 AI 属性。实际采集范围取决于运行时和工具的埋点；接入外部平台还需要匹配其协议、端点与凭证运行日志的级别与格式见应用日志

核心概念

span

span 是一次可被追踪的执行单元，记录名称、起止时间、属性以及父子关系。VeADK 会为一次完整请求生成一棵 span 树，覆盖智能体运行、模型调用、工具执行等节点，并遵循生成式 AI 语义规范标注 gen_ai.operation.name、gen_ai.span.kind 等属性。

追踪器 `OpentelemetryTracer`

OpentelemetryTracer 是统一的追踪入口。它持有一组导出器，初始化时将每个导出器接入追踪管线，并自动附加一个内存导出器用于本地留存与落盘。

导出器 exporter

导出器负责把 span 数据发送到具体的后端平台。每个导出器对应一个后端，可单独或组合使用。VeADK 内置以下导出器：

导出器	类	目标平台	文档
APMPlus	`APMPlusExporter`	火山引擎 APMPlus，追踪与指标	APMPlus
Cozeloop	`CozeloopExporter`	Cozeloop，链路观测与评测	Cozeloop
TLS	`TLSExporter`	火山引擎日志服务 TLS	TLS 日志服务
内存	`InMemoryExporter`	进程内存，本地调试与落盘	内存导出器

追踪数据可能包含用户输入、模型回答和工具数据。启用外部导出器前，确认数据发送目标、访问权限与保留周期；调用 force_export() 只会触发刷新，不代表远端已成功接收

给智能体挂载追踪器

先完成模型配置。下面的示例只保存在内存中，不需要外部观测平台；运行后会输出模型回复和本地 JSON 文件路径

app.py

import asyncio
from pathlib import Path

from veadk import Agent, Runner
from veadk.tracing.telemetry.opentelemetry_tracer import OpentelemetryTracer

tracer = OpentelemetryTracer()
agent = Agent(name="trace_demo", tracers=[tracer])
runner = Runner(agent=agent, app_name="trace_demo", user_id="demo-user")
response = asyncio.run(
    runner.run("用一句话解释智能体的用途", session_id="demo-session")
)
print(response)
Path("traces").mkdir(exist_ok=True)
path = tracer.dump(user_id="demo-user", session_id="demo-session", path="traces")
print(path)

配置好每个平台的端点、凭证和目标资源后，一个追踪器可以同时挂多个导出器。下例是替换上方追踪器的配置片段：

from veadk.tracing.telemetry.exporters.apmplus_exporter import APMPlusExporter
from veadk.tracing.telemetry.exporters.cozeloop_exporter import CozeloopExporter
from veadk.tracing.telemetry.exporters.tls_exporter import TLSExporter
from veadk.tracing.telemetry.opentelemetry_tracer import OpentelemetryTracer

tracer = OpentelemetryTracer(
    exporters=[APMPlusExporter(), CozeloopExporter(), TLSExporter()]
)

追踪器参数

OpentelemetryTracer 接受以下字段：

参数	类型	默认值	说明
`name`	`str`	`veadk_opentelemetry_tracer`	追踪器标识，用于日志与落盘文件命名。
`exporters`	`list[BaseExporter]`	`[]`	导出器列表。不允许显式加入 `InMemoryExporter`，否则会校验报错；内存导出器由追踪器自动附加。
`apmplus_managed_externally`	`bool`	—	只读属性。初始化时是否检测到已存在的全局 `TracerProvider`。为 `True` 时表示 VeADK 复用外部 provider 而不再覆盖，并跳过该追踪器中 `APMPlusExporter` 的链路注册；这不表示外部 provider 已配置 APMPlus。

InMemoryExporter 由 OpentelemetryTracer 自动管理，用于留存已完成且被采样的 span。请勿手动加入 exporters 列表，否则初始化会报错。

复用全局 TracerProvider

默认情况下，OpentelemetryTracer 初始化时会创建并设置全局 TracerProvider。如果在初始化之前已存在一个全局 TracerProvider（例如由其他库或应用主程序设置），VeADK 将复用该 provider 而不再覆盖它。已有全局 provider 时，APMPlusExporter 对象仍保留在导出器列表中，但该追踪器跳过它的链路注册。Cozeloop、TLS 和内存导出器仍会附加。通过 ENABLE_APMPLUS=true 自动创建的导出器也遵循这一行为 apmplus_managed_externally 仅表示初始化时检测到了已有 provider。它不检查该 provider 的目标平台，也不保证 APMPlus 收到数据。应用已配置 OpenTelemetry 时，应在同一处配置 APMPlus 的上报目标，并在平台上确认 Trace ID

通过环境变量启用导出器

除显式构造导出器外，Agent 会根据以下环境变量在运行时自动挂载对应导出器（值为 true 时启用）。若智能体未显式提供 tracers，会自动创建一个 OpentelemetryTracer：

环境变量	启用的导出器
`ENABLE_APMPLUS`	`APMPlusExporter`
`ENABLE_COZELOOP`	`CozeloopExporter`
`ENABLE_TLS`	`TLSExporter`

三个环境变量均为 false（默认）时，Agent 不会创建追踪器；此时若需要追踪，请显式构造 OpentelemetryTracer 并通过 tracers 传入。

内容追踪

默认情况下，span 会记录智能体、模型与工具的输入输出内容。在涉及敏感数据的场景中，可关闭内容采集，减少 VeADK 采集的内容数据。该行为由 OpenTelemetryConfig.trace_content 控制。

配置项	环境变量	类型	默认值	说明
`trace_content`	`OBSERVABILITY_OPENTELEMETRY_TRACE_CONTENT`	`bool`	`True`	是否将提示词、补全与工具输入输出内容写入 span。设为 `false` 时关闭对应内容字段的采集；第三方埋点和应用日志需单独配置。

# 关闭内容采集
export OBSERVABILITY_OPENTELEMETRY_TRACE_CONTENT=false

本地落盘

OpentelemetryTracer 内置的内存导出器会按 session_id 留存 span，可调用 dump 将当前会话的 span 导出为本地 JSON 文件，用于离线分析：

path = tracer.dump(user_id="demo-user", session_id="demo-session", path="traces")
print(f"trace 已写入 {path}")

导出的 JSON 包含每个 span 的名称、span_id、trace_id、起止时间、属性以及父 span 关系。更多细节参见内存导出器。

概览

快速开始

核心组件

可观测

扩展

前端

安全

部署

概述

核心概念

span

追踪器 `OpentelemetryTracer`

导出器 exporter

给智能体挂载追踪器

追踪器参数

复用全局 TracerProvider

通过环境变量启用导出器

内容追踪

本地落盘

​核心概念

​span

​追踪器 OpentelemetryTracer

​导出器 exporter

​给智能体挂载追踪器

​追踪器参数

​复用全局 TracerProvider

​通过环境变量启用导出器

​内容追踪

​本地落盘

核心概念

span

追踪器 `OpentelemetryTracer`

导出器 exporter

给智能体挂载追踪器

追踪器参数

复用全局 TracerProvider

通过环境变量启用导出器

内容追踪

本地落盘