mizcausevic-dev/otel-genai-validator

# otel-genai-validator 根据官方的[语义约定](https://opentelemetry.io/docs/specs/semconv/gen-ai/)验证 OpenTelemetry GenAI spans。提供库 + CLI。 ## 检查内容 | 规则 | 严重性 | 描述 | |---|---|---| | `missing-provider-name` | error | `gen_ai.provider.name` 是必填项 | | `missing-operation-name` | error | `gen_ai.operation.name` 是必填项 | | `unknown-operation-name` | warning | 不在已知集合内 (`chat`, `generate_content`, `text_completion`, `embeddings`, `retrieval`, `execute_tool`, `create_agent`, `invoke_agent`, `invoke_workflow`) | | `missing-request-model` | warning | 已知情况下推荐使用 `gen_ai.request.model` | | `missing-usage-input-tokens` | warning | 对于计费的 LLM 调用，推荐使用 `gen_ai.usage.input_tokens` | | `missing-usage-output-tokens` | warning | 对于计费的 LLM 调用，推荐使用 `gen_ai.usage.output_tokens` | | `negative-token-count` | error | token 数量 < 0 | | `legacy-token-attribute` | warning | 遗留的 `gen_ai.usage.prompt_tokens` / `completion_tokens` (已重命名为 `input_tokens` / `output_tokens`) | | `unexpected-span-kind` | warning | GenAI spans 通常为 CLIENT (3) 或 INTERNAL (1) | | `span-name-mismatch` | info | `span.name` 未遵循 `{operation.name} {request.model}` | ## CLI ``` npx otel-genai-validate [--summary] [--strict] [--skip rule,rule] [--out report.json] ``` 读取 OTLP/JSON 信封 —— `{ "resourceSpans": [ { "scopeSpans": [ { "spans": [...] } ] } ] }` —— 即 OTel Collector 文件导出器生成的结构。当产生任何 error 严重级别的结果时，将以非零状态退出；`--strict` 模式下，遇到 warning/info 也会失败。 ## 库 ``` import { validate, validateSpans } from "otel-genai-validator"; const payload = JSON.parse(/* OTLP/JSON */); const report = validate(payload); // { spans, findings, counts: { errors, warnings, infos }, ok } if (!report.ok) { for (const f of report.findings) { if (f.severity === "error") console.error(f.ruleId, f.message); } } ``` 如果你直接从 collector receiver 或内存中导出器消费 spans，`validateSpans(spans)` 可以接收已经扁平化处理的数组。 ## 组合使用 - **与 [`llm-cost-span-exporter`](https://github.com/mizcausevic-dev/llm-cost-span-exporter) 搭配** —— 根据相同的约定验证它生成的 spans。 - **与 [`a2a-mcp-bridge`](https://github.com/mizcausevic-dev/a2a-mcp-bridge) 搭配** —— 当 agent 调用工具时，在进行关联之前验证底层的 GenAI span。 ## 开发 ``` npm install npm run lint && npm run typecheck && npm run coverage && npm run build npm run demo ``` ## 许可证 [AGPL-3.0-or-later](LICENSE)

标签：API集成, GET参数, MITM代理, OpenTelemetry, 代码规范校验, 可观测性, 暗色界面, 生成式AI, 用户代理, 索引, 自动化攻击