tma1-ai/dsh-otel

English | 中文

DeepSeek Harness 跑一次花了多少 token、多少钱、多少时间，以 OpenTelemetry traces、metrics、logs 写进 GreptimeDB。

七个 Grafana dashboard 直接读这些数据。不需要 collector，不需要 sidecar，不用 fork DSH。它就是个普通插件，装上之后每一次 turn、模型调用和工具执行都变成一行可查的数据：

-- 最慢的工具调用，以及是哪个模型发起的。
SELECT span_name, model, duration_nano / 1000000 AS ms
FROM (
  SELECT span_name, duration_nano,
         MAX("span_attributes.gen_ai.request.model")
           OVER (PARTITION BY trace_id, "span_attributes.dsh.step") AS model
  FROM opentelemetry_traces
  WHERE "span_attributes.dsh.step" IS NOT NULL
)
WHERE span_name LIKE 'execute_tool%'
ORDER BY duration_nano DESC
LIMIT 10;

快速开始

需要 pnpm 10 或更高版本。dsh plugin 会转发给 PATH 上的 pnpm，而 dsh 的 profile 目录本身就是一个 pnpm workspace root，pnpm 9 会拒绝在那里安装，也会忽略 dsh 写下的 linker 设置。

启动数据库和 Grafana。grafana/ 下的 compose 栈会启动 GreptimeDB，并配好七个 dashboard。Grafana 的 provisioning 要从磁盘读这些 dashboard，因此只需获取该目录，无需 clone 整个仓库：

curl -fsSL https://github.com/tma1-ai/dsh-otel/archive/main.tar.gz \
  | tar -xz --strip-components=1 dsh-otel-main/grafana
cd grafana && docker compose up -d

**安装插件。**默认配置已指向上述数据库，无需额外配置：

dsh plugin --profile web add @tma1-ai/dsh-plugin-greptimedb

包自带 bundle patch，这一条命令就把它接进 profile。

**运行并查看数据。**trace 和 log 在 scheduledDelayMillis（默认 5 秒）内写入，metric 在下一个采集周期（默认 30 秒）写入。DSH 空闲时不产生数据，需先执行一次任务：

dsh web

Grafana 地址为 http://localhost:3000，已启用匿名 admin 访问，无需登录。建议从 Overview 开始。

如果只需要数据库，GreptimeDB 自带的控制台在 http://localhost:4000/dashboard/，看表和跑临时 SQL 够用：

docker run -p 127.0.0.1:4000-4003:4000-4003 \
  -v "$(pwd)/greptimedb_data:/greptimedb_data" \
  --name greptime --rm greptime/greptimedb:v1.2.0-beta.2 standalone start \
  --http-addr 0.0.0.0:4000 --rpc-bind-addr 0.0.0.0:4001 \
  --mysql-addr 0.0.0.0:4002 --postgres-addr 0.0.0.0:4003

两者都占 4000 端口，起一个就行。

版本兼容

DSH 的包 API 在预发布版之间会变，因此每个插件版本对应一个 DSH 版本：

插件	npm tag	DSH
0.1.0-beta.5	beta	0.1.2-alpha.5
0.1.0-beta.4 及更早	latest	0.1.1-rc.2

dsh plugin add 不指定版本时装的是 latest，对应 DSH 自己的 latest。要跟 DSH alpha 线就装 beta tag；参数会原样转给 pnpm add，指定确切版本号同理：

dsh plugin --profile web add @tma1-ai/dsh-plugin-greptimedb@beta

版本不匹配不会导致加载失败。插件照常挂载，然后逐条丢弃记录并打出 greptimedb-otel: dropped a telemetry record 告警，表里始终没有数据。

配置

要指向自己的数据库，在 $DSH_HOME/profiles/<name>/cordis.patch.yml 里覆盖这一行：

- id: greptimedb-otel
  name: '@tma1-ai/dsh-plugin-greptimedb'
  config:
    endpoint: https://<host>/v1/otlp
    database: <dbname>
    username: <user>
    password: <password>

profile patch 是整体替换目标行的 config，不是深合并，所以要保留的字段必须全部重述。

键	默认值	说明
endpoint	（必填）	OTLP base URL，如 http://localhost:4000/v1/otlp。三个信号各自的 /v1/{traces,metrics,logs} 后缀由插件拼接，写成单信号路径会在加载时拒绝。
database	public	作为 X-Greptime-DB-Name 发送。
username / password	（无）	Basic 认证，要么都填，要么都不填。
signals	三个全开	traces、metrics、logs 的任意子集。关掉的信号不构造 exporter。
content	none	允许多少 payload 离开进程，见 导出内容。
serviceName	dsh	OTel service.name。
logTable / traceTable	GreptimeDB 默认	覆盖目标表名。
ttl	180d	本插件建 log 和 trace 表时的保留期，通过 x-greptime-hints 发送，也接受 forever。GreptimeDB 只在自动建表时应用，已存在的表保持原设置，除非 ALTER TABLE。metric 表不在覆盖范围内，见已知限制。留空则不发这个 hint，沿用数据库默认值。
shutdownTimeoutMillis	3000	整个退出流程的截止时间。
metricIntervalMillis	30000	metric 采集周期，不得小于 exportTimeoutMillis。
maxExportBatchSize / maxQueueSize	512 / 2048	批量与缓冲上限。
scheduledDelayMillis / exportTimeoutMillis	5000 / 30000	导出节奏与单次请求超时。

配置写错会在插件加载时就报错并指明字段，不会拖到第一次导出。

Traces

turn span 是根，chat 和 tool span 作为它的同级子节点挂在下面，用 dsh.step 关联：

invoke_agent dsh              turn/start → turn/end
├── chat deepseek-chat        step/start → assistant/message
├── execute_tool bash         tool/call  → tool/result
└── chat deepseek-chat

时间戳取自触发它的那个 session 事件，不取处理时刻的时钟。

chat span 有四条闭合路径，每条都有确定的结束时间：

情况	结束时间	状态
模型正常返回	assistant/message	OK
流式过程被中断	assistant/message	OK，加 dsh.response.interrupted
请求失败	该 step 的 step/end	ERROR，带错误类型
没有结束事件（崩溃、退出）	最后一个事件的时间	UNSET，加 dsh.span.unclosed

Token 口径

DSH 的计数是不相交的：inputTokens 只含未命中缓存的输入，缓存读写是独立字段。而 gen_ai.usage.input_tokens 是计费总量，所以插件导出：

gen_ai.usage.input_tokens  = inputTokens + cacheReadTokens + cacheWriteTokens
gen_ai.usage.output_tokens = outputTokens          （已含 reasoning tokens）

明细仍可查：dsh.usage.uncached_input_tokens、dsh.usage.cache_read_tokens、dsh.usage.cache_write_tokens、dsh.usage.reasoning_tokens。

Metrics

指标	类型	维度
gen_ai.client.token.usage	Histogram	gen_ai.token.type（只有 input/output）、model、provider
gen_ai.client.operation.duration	Histogram	gen_ai.operation.name、model、provider
gen_ai.invoke_agent.duration	Histogram	gen_ai.operation.name
gen_ai.execute_tool.duration	Histogram	gen_ai.operation.name、gen_ai.tool.name
dsh.token.detail	Histogram	dsh.token.detail_kind（cache_read/cache_write/reasoning）、model、provider
dsh.tool.invocations	Counter	gen_ai.tool.name、dsh.tool.outcome
dsh.turns / dsh.steps	Counter

Logs

每个 session 事件一条记录。四个属性通过 X-Greptime-Log-Extract-Keys 变成真实列：

SELECT session_id, event_type, turn, step, body
FROM dsh_logs
WHERE session_id = '...' AND event_type = 'tool/result'
ORDER BY timestamp;

assistant/chunk 永不导出，同样的内容在汇总后的 assistant/message 里。

导出内容

由 content 决定，默认不导出任何 payload。

模式	导出内容
none（默认）	结构和计量：事件类型、turn 和 step 编号、token 数、工具名、耗时、成败、错误的 name 和 code。
full	增加用户与助手的消息正文、工具参数、工具结果。
full+prompt	增加 request/header：完整 system prompt 和全部工具 schema。

有三样东西在任何模式下都不离开进程：工具私有的 meta 载荷、失败 turn 的内部 error.message，以及请求失败时的异常消息和堆栈。

投影层是正向白名单。插件不认识的事件类型只导出身份标识，未来某个 DSH 插件声明的新类型也一样。

Dashboard

grafana/ 下有七个 Grafana dashboard，快速开始里的 compose 栈会把它们全部配好。

Dashboard	回答什么问题
Overview	用了多少 token、多快、多少来自缓存
Cost	花了多少钱、钱花在哪一档、账单为什么在涨
Sessions	一次对话跑了多久、用了几个 turn、在哪里失败
Agent loop	哪些工具在跑、失败率多少、一个 turn 用了几次模型调用、时间花在哪
Trace explorer	某一个 turn 内部到底发生了什么，逐 span 看
Log explorer	全部 session 事件，可按 session、类型和全文检索过滤
Metrics	同样的活动，通过 PromQL 读取，用于更长保留期和不受采样影响的分位数

Cost 用 dashboard 自己的四个变量给 token 计价，按每百万 token 计：未命中缓存的输入、缓存读、缓存写、输出。默认值是 DeepSeek 公布的 deepseek-v4-flash 高峰价（人民币）：3.0、0.10、3.0、9.0。同一组费率的美元值是 0.44、0.014、0.44、1.32。

Currency 只切换各面板的货币符号，不换算费率，所以切过去要顺手把四个数字改掉。它的取值是 Grafana 的单位串，currencyUSD 和 prefix:¥；要加别的货币，就在这个变量上多加一个选项。

一套费率作用于选中的全部模型，所以同时跑不同价位的模型时，用 Model 过滤器逐个看。算出来是估算，你的合同价和 provider 的时段折扣它都不知道。

每个表格都能继续下钻：trace id 打开该 turn 的 waterfall，session id 在 trace 和 log 视图之间跳转。每个 panel 的查询都由 node grafana/verify.mjs 对着真实数据库验证过。数据源的分工见 grafana/README.md，这些查询需要的索引见 grafana/indexes.sql。

配合 TMA1

TMA1 会把 OTLP 反代进它自己管理的 GreptimeDB。把 endpoint 指过去，DSH 就出现在 OTel GenAI 视图里：

endpoint: http://localhost:14318/v1/otlp

TMA1 的 tma1_token_usage_1m、cost_1m、latency_1m、status_1m 四张 Flow 表由 span_attributes.gen_ai.* 派生，本插件按规范填充这些字段。

开发

pnpm test     # 单测、profile 组装、Loader 启动
pnpm smoke    # 针对新打包 tarball 的打包检查
GREPTIMEDB_OTLP_ENDPOINT=http://localhost:4000/v1/otlp pnpm test   # 追加真实数据库往返

已知限制

• DSH 处于 pre-release，首个正式版本前会自由重命名和重组包结构。插件只用它的类型，所以不声明 peer 版本：DSH 每个版本都是预发布版，而 semver 不匹配 range 里没写明的预发布版，锁哪个 range 都会在下一个预发布版上失效。代价是 DSH 的重命名不会在安装时暴露，只能由 CI 发现；CI 运行的版本见版本兼容。
• 发布出去的 .d.ts 会 import DSH 的类型。 在没有 DSH 的环境中对本包做类型检查，需启用 skipLibCheck，或同时安装对应的 DSH 包。
• GenAI 语义规范仍是 experimental。 名字取自 @opentelemetry/semantic-conventions/incubating，会随它变动。span 同时带 gen_ai.provider.name 和已废弃的 gen_ai.system。
• ttl 覆盖不到 metric 表。 metric 走 metric engine，保留期是 physical table 的属性。hint 只到得了逻辑表，逻辑表会存下并显示它，但不会执行（greptimedb#8951）。请自行 ALTER TABLE greptime_physical_table SET 'ttl' = '180d'。
• 不做逐 turn flush。 导出遵循 batch processor 自身节奏。
• 关闭有时限。 shutdownTimeoutMillis 到期时仍在途的记录可能在退出时丢失。
• Subagent session 有独立 trace，不拼接进父 session。

License

Apache-2.0