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 提供全景可观测的实践方案。

01

先认识 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 解决的是两类不同问题。

02

为什么有日志,还需要 Trace

Cloud Native

日志是一串按时间排列的事实,Trace 则是一棵带父子关系和时间区间的调用树。

只有日志时,我们可以知道“发生了什么”;有了 Trace,才更容易直接回答:

  • 一轮任务的总耗时分布在模型、工具和等待的哪些阶段;

  • 哪次工具调用失败,它属于哪一个推理步骤;

  • 同一个 Step 是否触发了模型重试;

  • 每次模型调用的 TTFT、输入 Token、输出 Token 和缓存 Token;

  • 主 Agent 与 Subagent 之间的执行和成本关系;

  • 多轮会话、多个模型乃至多个 Agent 的整体使用情况。

因此,Logs 与 Trace 不是二选一:日志保留完整事件账本,Trace 提供适合性能、错误和成本分径的结构化投影。

03

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。

04

路线 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…
— 以上为试看内容(约 40%),开通会员后阅读全文 —