alebgl77/dsh-plugin-otel-genai

dsh-plugin-otel-genai

用于 DeepSeek Harness 的 OpenTelemetry GenAI 指标。

该插件将 harness 会话日志转换为
OpenTelemetry GenAI 语义约定
中定义的两个指标，并通过 OTLP/HTTP 导出它们。将其指向 OTel Collector、Grafana Alloy、
带 OTLP receiver 的 Prometheus 或 Grafana Cloud，harness 执行的每个模型步骤
都会按提供商和模型显示为 token 使用量和延迟。

不会有任何对话内容离开进程。该插件只读取 token 计数、
提供商路由和时间戳；消息文本、工具参数和工具结果
绝不会被触碰。内置的 @deepseek-ai/dsh-session-telemetry-otel
包覆盖相反的需求（将完整会话记录作为 OTel 日志）。

指标

| 指标 | 类型 | 单位 | 来源 |
|---|---|---|---|
| gen_ai.client.token.usage | histogram | {token} | OTel GenAI 约定 |
| gen_ai.client.operation.duration | histogram | s | OTel GenAI 约定 |
| dsh.genai.client.token.cache_read | histogram | {token} | 插件特定 |
| dsh.genai.client.token.reasoning | histogram | {token} | 插件特定 |

每个数据点上的属性：gen_ai.operation.name（chat）、
gen_ai.provider.name、gen_ai.request.model。gen_ai.client.token.usage
额外添加 gen_ai.token.type（input 或 output）。gen_ai.conversation.id
是可选的。

Token 计量遵循 harness 的 TokenUsage 契约：input 是计费的提示大小，
即未缓存输入加上缓存读取加上缓存写入；
output 是补全大小。缓存读取和推理 token 也会
在各自的直方图上报告，因为约定仅将它们作为 span
属性携带，而不是作为指标维度。

持续时间从 step/start 事件测量到同一步骤的
已结算 assistant/message，使用 harness 进程时钟。它涵盖
整个模型调用（包括流式传输），而不是提供商侧的延迟。

安装

npm install dsh-plugin-otel-genai

将条目添加到你的 cordis.yml 或 --patch 覆盖层中：

- name: dsh-plugin-otel-genai
config:
exporter:
url: http://localhost:4318/v1/metrics
headers:
authorization: !!js Bearer ${process.env.OTLP_TOKEN}
exportIntervalMillis: 15000        # optional, default 15000
serviceName: deepseek-harness      # optional, OTel service.name
includeConversationId: false       # optional, one series per session when true
providerNameMap:                   # optional, harness route -> gen_ai.provider.name
deepseek-eu: deepseek

exporter.url 必须是指向 OTLP 指标端点的 http(s) URL。该
插件会在加载时因 URL 缺失或格式错误以及导出间隔非正数而失败，
且在任何 exporter 被构造之前就会失败。

Grafana

当 OTel Collector 向 Prometheus 提供数据时，直方图会落地为
gen_ai_client_token_usage_token_sum、_count 和 _bucket。三个面板
覆盖了大多数 FinOps 问题：

过去一小时按模型划分的 token 数，按方向拆分：

sum by (gen_ai_request_model, gen_ai_token_type)
(increase(gen_ai_client_token_usage_token_sum[1h]))

按提供商划分的 p95 步骤延迟：

histogram_quantile(0.95,
sum by (le, gen_ai_provider_name)
(rate(gen_ai_client_operation_duration_seconds_bucket[5m])))

按模型划分的提示缓存命中率：

sum by (gen_ai_request_model) (increase(dsh_genai_client_token_cache_read_token_sum[1h]))
/
sum by (gen_ai_request_model)
(increase(gen_ai_client_token_usage_token_sum{gen_ai_token_type="input"}[1h]))

在 Grafana 转换中将 token 总和乘以你的提供商价格表，或者从
grafana-llmops-forge 导入现成的仪表盘，它
使用的正是这些指标和标签名称。

重复计数

指标消费方无法在事后对直方图去重，因此插件
必须将每个步骤恰好记录一次。有两条规则保证了这一点：

1. 用量从 assistant/message 读取，harness 会在每个
模型步骤中追加一次该消息，并附带适配器报告的用量。流式用量块和
重试尝试不会被计入。
2. seq < session.firstLiveSeq 的事件属于会话种子（恢复、
分叉、重放），会被跳过，因此重启的进程不会对从磁盘继承的
步骤重新计费。

如果你还以 FULL 模式运行 dsh-session-telemetry-otel，相同的用量
会在那里以日志记录的形式出现。请从其中一个来源进行聚合，而不是两者都聚合。

开发

pnpm install
pnpm run check   # typecheck + vitest

该包仅针对 @deepseek-ai/cordis 编译。它消费的两个 harness
事件（session/event、session/disposed）在 src/index.ts 中以结构化方式声明，
因此该插件不会固定 harness 版本。

许可证

MIT