AgentKit Studio
任务指南

可观测性(OTel)

托管运行时把会话事件流导出成 OTLP trace;配置端点、Header 与证书,并在观测页确认 trace 已经上报。

可观测性(observability)把一次运行拆成可检索的 trace:每个 turn、每个模型步骤、每次工具调用各是一个 span。 导出走标准 OTLP/HTTP JSON,目标是平台注入的观测端点;Studio 的 观测 页读同一个 Trace Store。

前置条件

  • 会话跑在托管运行时上。本地桌面会话永不导出——这类会话既没有平台身份,也没有注入的观测环境。
  • 平台已注入观测环境变量。没有端点时插件不注册任何东西,Host 行为与之前完全一致。

两条上报路线

主路线指向主观测后端(Langfuse 等),用 OTEL_EXPORTER_OTLP_TRACES_ENDPOINT,或 OTEL_EXPORTER_OTLP_ENDPOINT 加 /v1/traces。 副路线指向云监控(可选),用 CLOUD_MONITOR_OTLP_TRACES_ENDPOINT。 两条路线同时发送:同一批 span 各投一份,任一条失败不影响另一条。

环境变量

路由与身份

变量必填默认说明
AGENTENGINE_MANAGED_RUNTIME_NAME其一—托管运行时名称;与下一个变量任一存在才启用导出
AGENTENGINE_AGENT_ID其一—平台 Agent 标识
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT推荐—完整 trace 端点,优先级最高
OTEL_EXPORTER_OTLP_ENDPOINT可选—Base 端点;未设上一条时自动补 /v1/traces
OTEL_SERVICE_NAME可选agentengine.dsh-observability写入 service.name
OTEL_RESOURCE_ATTRIBUTES可选空附加资源属性,格式 k=v,k2=v2

两条都不设就完全不导出

只设 endpoint 而没设身份,或只设身份而不设端点,都不导出——两者必须同时满足。

变量说明
OTEL_EXPORTER_OTLP_TRACES_HEADERStrace 专用 Header,优先
OTEL_EXPORTER_OTLP_HEADERS通用 Header,作为后备
CLOUD_MONITOR_OTLP_TRACES_HEADERS副路线 trace 专用 Header,优先
CLOUD_MONITOR_OTLP_HEADERS副路线通用 Header

格式是逗号分隔的 k=v,k2=v2;值支持 percent 编码(%20 之类会先解码)。 解析时跳过没有键或没有 = 的片段,不会因为一个畸形片段丢掉整行。

export OTEL_EXPORTER_OTLP_TRACES_HEADERS='Authorization=Bearer%20<token>,X-Scope=agentkit'

证书

主路线使用私有 CA 时,用标准 OTel 变量指向 PEM 文件:

变量说明
OTEL_EXPORTER_OTLP_TRACES_CERTIFICATEtrace 专用证书路径,优先
OTEL_EXPORTER_OTLP_CERTIFICATE通用证书路径,作为后备
DSH_OTEL_CA_PEM_BASE64遗留的内联 base64 PEM,仅在没有挂载文件时使用

证书是追加,不是替换

这些证书会被追加到平台信任根之后,而不是替换它们。 这样主用私有 CA 时,仍然公开可信的云监控副路线不会被一并打断。 同理,运行时的 ca 选项不会覆盖默认证书存储。

接入步骤

在托管运行时上确认注入

部署到云端后,在实例里确认三个变量都在:

printenv | grep -E '^(AGENTENGINE_(MANAGED_RUNTIME_NAME|AGENT_ID)|OTEL_EXPORTER_OTLP)'

三个都在,说明平台已经注入观测环境;缺身份变量就是没在托管运行时上,此时不会导出。

需要时补端点和 Header

如果平台只注入了身份而没注入端点,或者你要临时指向另一个后端:

export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT='https://otel.example.test/v1/traces'
export OTEL_EXPORTER_OTLP_TRACES_HEADERS='Authorization=Bearer%20<token>'

只改环境变量、不改代码。想彻底关掉导出,把端点变量清空即可——插件会退化成 no-op。 私有 CA 的场景按上一节挂 PEM 文件,不要靠关闭证书校验绕过。

打开观测页

运行中心 → 观测。页面顶部徽章从「读取中」变成 Trace Store 已连接 就说明后端通了。

汇总卡有四格:

卡片数据来源
运行次数时间范围内的运行总数(近 24 小时 / 近 7 天)
完成率已完成运行的比例
平均耗时Runtime 上报的平均耗时,单位 ms
Token 用量输入与输出合计

下面是时间分桶柱状图,以及可选的云端统计行(会话数 / Tokens / 错误数)。

找到这次运行的 trace

用工具栏四个筛选收窄:

控件作用
搜索框同时匹配 Trace ID、Run、Session、Agent
时间范围24 小时 或 7 天
按 Agent 筛选下拉选具体 Agent
状态筛选全部 / 进行中 / 已完成 / 失败

列表每页 12 条,列是 Trace(名称 + 等宽 ID)、执行位置(本地 / 云端 · 本机留存凭据)、Agent / Run、状态、耗时、Tokens、开始时间。 还有 RUNNING / PENDING / QUEUED 的 trace 时,列表每 5 秒自动刷新;页面切到后台时暂停。

打开 Trace 详情

点任意一行打开详情弹窗,它有七个页签:

页签内容
Spans每个 span 的名称、Span ID、耗时、状态;点一条可切换
属性选中 span 的属性 JSON
事件选中 span 的事件数组
资源executionLocation、来源(provenance)与资源属性
轨迹工具调用轨迹
模型请求请求体统计(见下)
原始 OTLP点 读取 OTLP 拉取实际发送的 JSON

模型请求 页签显示每条请求的字符数与字节数:总计、工具定义字符数(含工具个数)、系统提示词字符数、对话内容字符数。 它只是大小统计,不保存提示词正文;字符数不等于 Token 用量。 只有新运行的 Codex Chat Completions 代理会提供这份统计,其他记录显示「此记录没有请求体统计」。

确认已经上报

按顺序核对三件事:

  1. 列表里有这次运行 —— 状态是 SUCCEEDED / COMPLETED,耗时与 Tokens 都不为空。
  2. Spans 页签里有层级 —— 顶层是 dsh.turn,下面挂 chat 生成 span,再下面是 execute_tool <工具名>。
  3. 原始 OTLP 里有内容 —— 点 读取 OTLP,返回的 resourceSpans[0].scopeSpans[0].spans 非空,且 service.name 是你配置的值(默认 agentengine.dsh-observability)。

三条都满足就是真的发出去了。任一条不满足,先看下面「没有 Trace」那一行。

导出会话日志

详情弹窗右上角有 导出 Session。它要求该 trace 上带 SessionId,否则提示「当前 Trace 没有 Session ID,无法导出会话日志」。 导出的是完整事件记录,适合贴进工单。

Span 结构与上报行为

Span 名称何时产生关键属性
dsh.turn每个 turn(turn/start .. turn/end)dsh.turn.number、langfuse.session.id、dsh.turn.reason
chat每个模型步骤(step/start .. step/end),类型是 generationgen_ai.request.model、gen_ai.system、gen_ai.usage.*、dsh.step.number
execute_tool <工具名>每次 tool/call .. tool/result,以及 Codex 的工具生命周期gen_ai.tool.name、dsh.tool.call_id、error.type

每次运行还带身份属性:agentengine.invocation_id、agentengine.run_id、agentengine.platform_session_id、agentengine.agent_id、agentengine.version_id、agentengine.runtime_name。 当运行有平台 InvocationId 时,trace id 就是它那 32 位十六进制,可以直接按 trace 查。

导出行为:缓冲每 3 秒刷写(step/end 与 turn/end 立即刷写),单次请求超时 5 秒,缓冲上限 512 个 span(超出丢弃最旧),失败日志每 60 秒最多一条。

提示词、模型输出、工具参数、工具结果一律不导出。 只导出模型名、供应商、Token 用量、工具名、运行身份和错误身份——这是代码里的硬约束,不是配置项。

常见错误

症状原因处理
观测页显示「还没有 Trace」会话不在托管运行时上,或端点/身份变量缺失按「接入步骤」第 1 步核对三个变量;本地会话永远不会出现
徽章停在「读取中」Trace Store 不可达检查网络与后端地址,点 重新读取
列表为空但后端有数据时间范围或筛选太窄把范围切到 7 天,清空 Agent 与状态筛选
提示「部分观测数据暂不可用」汇总或列表其中一个请求失败刷新;持续失败说明该子接口不可用
详情里 Span 一直「正在读取 Span…」trace 详情请求失败关掉弹窗重开;仍失败看错误提示
导出 Session 报没有 Session ID该 trace 未携带会话标识用同一会话的另一次运行导出
模型请求 页显示没有统计该记录不是 Codex Chat Completions 代理产生的正常现象,不代表请求大小为零
主路线通了、副路线报错私有 CA 只影响了副路线的公开信任链用标准证书变量追加,不要替换默认存储

相关参考

本页导航