DeepSeek Harness 全景可观测实践
AI 编码 Agent 真正跑起任务后,问题往往不再是“它有没有完成”,而是:这一轮为什么花了 47 秒?时间卡在模型还是工具?失败后重试了几次?Token 消耗来自主 Agent 还是 Subagent?
DeepSeek Harness(下文简称 DSH)已经保存了很完整的 Session 日志,但要回答耗时、调用关系和成本问题,还需要把事件组织成 Trace 和 Metrics,才能看清问题的全貌。
为了采集 DSH 全景可观测数据,阿里云可观测团队基于开源的 LoongSuite,为 DSH 提供了两条开源可观测路线:一条是可以从 DSH 插件市场独立安装的 @loongsuite/dsh-plugin,另一条是 LoongSuite Pilot 内置的 DSH 集成。它们都基于 OpenTelemetry GenAI 语义[1],数据可以进入用户自己选择的兼容后端,但部署形态和适用场景并不相同。
本文从实践角度出发,为 DeepSeek Harness 提供全景可观测的实践方案。
先认识 DeepSeek Harness
Cloud Native
DeepSeek Harness(https://github.com/deepseek-ai/deepseek-harness)是 DeepSeek 开源的编码 Agent 运行时。模型负责生成,而 Harness 负责维护会话、组织 ReAct 循环、执行工具调用、管理权限与沙箱,并在需要时派生 Subagent。
DSH 以 npm 包 @deepseek-ai/dsh 分发,命令行入口是 dsh。官方随包提供 Web 和 headless 两种 Profile 模板,也允许用户安装和组合自定义 Profile,例如第三方终端界面。Web 默认监听 127.0.0.1:3080。
它的插件体系建立在 Cordis 之上,配置由多层 patch 组合而成。用户层配置支持热更新,因此插件可以在不侵入 Agent 主循环的情况下,订阅原生生命周期并增加新的数据出口。
DSH 本身也保存 append-only 的 Session 事件流,其中包含 Turn、Step、工具调用、模型消息和流式增量;官方还提供了默认关闭的 OTLP Logs 插件。这些日志非常适合审计、回放和事实排查,但日志与 Trace、Metrics 解决的是两类不同问题。
为什么有日志,还需要 Trace
Cloud Native
日志是一串按时间排列的事实,Trace 则是一棵带父子关系和时间区间的调用树。
只有日志时,我们可以知道“发生了什么”;有了 Trace,才更容易直接回答:
一轮任务的总耗时分布在模型、工具和等待的哪些阶段;
哪次工具调用失败,它属于哪一个推理步骤;
同一个 Step 是否触发了模型重试;
每次模型调用的 TTFT、输入 Token、输出 Token 和缓存 Token;
主 Agent 与 Subagent 之间的执行和成本关系;
多轮会话、多个模型乃至多个 Agent 的整体使用情况。
因此,Logs 与 Trace 不是二选一:日志保留完整事件账本,Trace 提供适合性能、错误和成本分径的结构化投影。
LoongSuite 的两条 DSH 可观测路线
Cloud Native
先看两条路线实际经过的数据路径。
两条路线遵循同一套 OpenTelemetry GenAI 语义,但采集位置、数据路径和适用场景不同。
这里有一个容易混淆的地方:Pilot 中的 DSH 插件是 Pilot 采集链路的一部分,负责把 DSH 原生事件落到本地、交给 daemon 继续处理;它不是另一个面向插件市场、可以脱离 Pilot 单独安装和直发 OTLP 的插件。
▍应该怎么选
同时使用 Claude Code、Codex、Cursor、Qoder、OpenClaw、DSH 等多个 Agent,或者需要本地 Dashboard、长期日志和统一成本视图:优先选择 Pilot。
只使用 DSH,并且已有 Jaeger、Tempo、SigNoz、Langfuse 或 OpenTelemetry Collector:优先选择独立插件,链路最短。
两条路线在技术上可以共存,但如果同时向同一个后端、同一个服务名发送 DSH Trace,会形成两份语义相近的链路。除非是在做对照验证,否则建议只让其中一条路线负责 DSH Trace。
路线 A:独立插件,两分钟直发 OTLP
Cloud Native
@loongsuite/dsh-plugin[2]已发布正式版 0.1.0,并已被 DSH 社区插件市场[3]收录。当前版本支持 DSH >=0.1.0-rc.6,要求 Node.js >=22.19.0。
DSH 插件按 Profile 安装。观测 Web Profile:
dsh plugin --profile web add @loongsuite/dsh-plugin
如果还要观测 headless 任务,需要再安装到对应 Profile:
dsh plugin --profile headless add @loongsuite/dsh-plugin
最小配置只需要标准 OTLP 地址和服务名:
export OTEL_SERVICE_NAME=dsh-agentexport OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318dsh --profile web
公共 endpoint 会自动补成 /v1/traces 和 /v1/metrics。如果后端只接收 Trace,可以关闭 Metric 导出:
OTEL_METRICS_EXPORTER=none dsh --profile web
插件直接监听 DSH 的 Session、Turn、Step、llm/stream 和 Tool 生命周期,在进程内构建 ENTRY → AGENT → STEP → LLM / TOOL 调用树。每次真实模型调用都对应独立的 LLM Span,因此同一 Step 中的失败与重试不会被合并。
▍接入 Langfuse
Langfuse 接收 OTLP Trace,但不接收 OTLP Metric。可以在 $DSH_HOME/profiles/ 中显式填写完整 Trace 地址:
- id: loongsuite-observability config: traceEndpoint: https://cloud.langfuse.com/api/public/otel/v1/traces serviceName: dsh-agent headers: Authorization: "Basic" x-langfuse-ingestion-version: "4" captureContent: false exportMetrics: false
自建 Langfuse 时替换域名即可。鉴权值是 public_key:secret_key 的 Base64 结果,不要把真实密钥提交到仓库。
▍接入云监控 2.0
云监控 2.0 - 接入中心 - 应用监控&链路追踪 - OpenTelemetry。
点击获取 LicenseKey, 填入应用名,选择公网,HTTP。
然后配置:
- id: loongsuite-observability config: endpoint: https://project>.region…