otel-weaver

OpenTelemetry Weaver

当组织希望在上游 OTel 语义约定的基础上定义自己的语义约定，并据此生成语言绑定时，请使用此技能。

用法：

• 配合 otel-semantic-conventions，确定哪些属性已存在于上游，因而不应在本地注册表中重新声明
• 最新 Weaver 版本：如果 otel-sdk-versions 索引中列出了 Weaver，则使用该索引；否则使用 https://github.com/open-telemetry/weaver/releases；references/ci-integration.md 中记录了带日期的 Weaver/semconv 兼容性信息，可用于离线回答

如果无法使用配套技能：

• 不要停止
• 如果可以从官方来源核实指导内容，就不要只依赖记忆
• 查阅 Weaver 仓库、schemas/semconv-syntax.v2.md 和 docs/usage.md / docs/validate.md
• 说明使用了哪种替代方案，并将任何未经核实的事项保留为未解决状态

心智模型

包含三个组成部分：

1. 注册表 — YAML 文件目录。必须包含 manifest.yaml；其中声明 file_format: definition_manifest/2.0（版本支持情况见：带日期的记录），其 schema_url（OTel Schema URL 格式：http[s]://host/path/<version>）既用于命名注册表，也通过最后一个路径段标明其版本。依赖项也必须包含 schema_url，并可选包含 registry_path。其余文件声明 attributes、metrics、spans、events、entities。schema_url 中的版本段由你管理；有更改时应递增版本。（semconv_version 和 schema_base_url 已弃用，改用 schema_url；顶层 name 不是 v0.28.0 manifest 字段。）
2. 模板 — MiniJinja 文件目录（与 Jinja2 兼容，但并非完整的 Jinja2——自 v0.22.0 起，默认关闭自动转义，并支持循环中的 break / continue），另有每种目标语言对应的 weaver.yaml，用于描述要运行哪些模板、使用何种过滤器、采用何种 application_mode，以及输出文件名。
3. 策略 — 由 Regorus（兼容 OPA）引擎评估的 Rego 规则，分属四个包：before_resolution（原始解析组；不受支持，使用 --v2 时会跳过）、after_resolution（已解析的注册表）、comparison_after_resolution（仅在传入 --baseline-registry 时使用）和 live_check_advice（在 live-check 期间按样本评估）。内置 OTel 策略是基础；自定义策略则叠加组织规则。

这三项取代了手工编写的 const.go（或同类文件）：常量块变为注册表，编写常量的工作变为代码生成，约定俗成的知识则变为策略。

不可妥协的规则

• 通过 https://github.com/open-telemetry/weaver#install 中记录的方法之一安装 Weaver（发布二进制文件、otel/weaver:vX.Y.Z Docker 镜像或 setup-weaver GitHub Action）。切勿执行 brew install weaver——它会安装 Scribd 的另一个无关工具。
• 上游 semconv 属性应通过 ref 引用，而不是重新声明。边界域（http、db、messaging、rpc、network、gen-ai 等）属于上游 OTel semconv，而不是本地注册表。运行时应使用语言 SDK 的 semconv 包来处理这些属性。
• 每个属性和信号定义都必须包含 stability；枚举成员也要包含——weaver registry check 不会检测缺失的 stability（参见 registry-authoring.md）。
• 在 v2 中，属性引用可以细化 brief、note、examples 和 annotations 等字段，但不能细化 stability 或 deprecated；这些字段始终取自属性定义。
• 组织本地属性、指标和跨度应使用域名前缀（例如 ecommerce.、acme.）。
• 对生成的输出运行语言格式化工具（gofmt -w、prettier、ruff format 等）。Jinja 的空白处理会产生多个空行；如果不进行格式化，CI 中的差异检查会错误地失败。
• 编写模板前，先确认解析后的架构形状。对于 definition/2 注册表，使用 {"v2": true} 调用分组 jq 辅助函数；v2 模板 ctx 会保留 key 等属性字段、name 等指标字段、跨度的 type／kind 和结构化的 span.name.note，以及实体的 type／identity／description。有关如何转储确切形状，请参见 references/template-authoring.md。

工作流

1. 安装或定位 Weaver。 按照 https://github.com/open-telemetry/weaver#install 中的上游安装说明操作——选择固定版本的发布二进制文件、otel/weaver:vX.Y.Z Docker 镜像或 setup-weaver GitHub Action。在 CI 和可复现的本地运行中使用 Docker。
2. 编写注册表。 必需内容：manifest.yaml，以及一个或多个声明属性、属性组、指标、跨度、事件或实体的 definition/2 YAML 文件。参见 references/registry-authoring.md。
3. 编写模板。 在 templates/registry/<lang>/ 下为每种语言创建一个目标目录，其中包含 weaver.yaml 和 *.j2。参见 references/template-authoring.md。
4. 验证并生成。 使用 weaver registry check --v2 -r ./telemetry/registry/ 快速获取反馈。使用 weaver registry generate --v2 --registry ./telemetry/registry/ --templates ./telemetry/templates/ <lang> <output-dir> 生成代码。对输出运行语言格式化工具。
5. 接入 CI。 设置三个检查关卡：check（架构）、generate + git diff --exit-code（确保已提交的代码为最新版本）、与基础分支进行 diff（发现破坏性变更）。参见 references/ci-integration.md。

Weaver CLI 还有许多本工作流未涉及的子命令：用于快速检查注册表的 stats 和 json-schema、用于保持文档中的 semconv 片段为最新的 update-markdown、用于处理实时 OTLP 遥测数据的 emit／live-check／infer、用于写入自包含解析后注册表工件的 package（用于替代已弃用的 resolve）、用于向 LLM 工具公开注册表的 mcp，以及提供 HTTP + UI 模式的 serve。这些都不在本文范围内（见下文），但在认定 check／generate／diff 已涵盖全部功能前，值得先了解它们的存在。

注意事项

这些问题会浪费时间，而且上游文档中并未明确说明：

1. brew install weaver 安装的是错误的工具。请使用 GitHub releases 或 Docker。
2. 生成的输出未经过格式化工具整理。在运行 weaver registry generate 后，务必运行对应语言的格式化工具。
3. Jq 辅助函数默认针对旧版 schema。对于 definition/2，请传入 {"v2": true}，并使用保留的 v2 字段：属性 key、指标 name、span 的 type/kind 和 span.name.note，以及实体的 type/identity/description。编写模板前，务必先生成并检查筛选后的 ctx。
4. comment Jinja 筛选器使用关键字参数：attr.brief | comment(format="go")。它已经会输出 // 前缀；请勿再添加一个。
5. 属性、指标、span、事件和实体都有预构建的分组 jq 筛选器（semconv_grouped_attributes、semconv_grouped_metrics、semconv_grouped_spans、semconv_grouped_events、semconv_grouped_entities）。对于 definition/2，请使用（例如）semconv_grouped_spans({"v2": true}) 作为折叠式 YAML 标量；不带参数的辅助函数默认选择旧版 schema。
6. 对于自定义 v2 definition 文件，weaver registry check 会输出“File format definition/2 is not yet stable”（警告；在 references/ci-integration.md 的带日期记录中仍然如此）。这是正常情况；请勿将其视为失败。缺少 manifest file_format 也会发出警告；请添加该字段来修复。
7. --future 默认不启用，但对于自定义 v2 registry，它仍会将 definition/2 不稳定警告（以及 manifest 缺少 file_format 的警告）提升为错误。请在格式稳定前保持关闭。
8. generate 的 CLI 参数顺序：目标目录名称是位置参数，位于 --registry 和 --templates 之后；输出目录紧随其后。--templates 指向包含目标目录的父目录，而不是特定语言的子目录。
9. registry 中的 span 名称与运行时名称：必需的 schema 字段是 type、kind（client/server/producer/consumer/internal）、brief、stability，以及结构化的 name: { note: "..." }。对于内部业务 span，将带点的类型标识符放入 name.note，并在运行时渲染解析后的 span.name.note 字符串，是一种简洁的做法。
10. 哪些内容不应放入本地 registry。 DB、HTTP、消息传递、RPC、网络、GenAI 等边界 span/属性遵循上游 OTel semconv。在将上游内容作为 manifest 依赖项引入之前，这些内容的检测应直接引用语言 SDK 的 semconv 包。这是最常见的建模错误。
11. Counter 和 UpDownCounter 的名称不应附加 _total；这是 semconv v1.44.0 的命名规则。
12. 根据 semconv v1.44.0 的单位指南，时长测量工具应使用秒（s）。

按需加载的参考资料

• registry YAML 字段参考：references/registry-authoring.md
• Jinja2 模式、jq 筛选器、解析后结构速查表：references/template-authoring.md
• 可直接采用的 GitHub Actions 示例及带日期的版本兼容性记录：references/ci-integration.md
• 从手动维护常量迁移到 registry 的指南：references/migration-playbook.md
• 语义约定技能：otel-semantic-conventions
• 手动检测技能：manual-instrumentation

不在范围内

以下是顺理成章的后续工作，但不属于此技能范围：

• 将 registry 发布为供下游使用者使用的带版本工件（weaver registry package）
• 将上游语义约定声明为 manifest 依赖项
• 针对实时 OTLP 遥测数据使用 weaver registry live-check/emit/infer
• weaver registry mcp / weaver serve
• 超出内置策略范围的自定义 Rego 策略
• 辅助函数代码生成（MyMetricName(meter) 封装器）

验证约定

如果你创建或修改了 Weaver 注册表、模板或 CI 集成：

• 完成前重新打开已更改的文件
• 针对 definition/2 注册表运行 weaver registry check --v2，并记录结果
• 运行 weaver registry generate --v2 和语言格式化工具，然后验证 git diff --exit-code 没有差异
• 使用代码库证据确认每个适用项

报告最终检查结果时使用：

• [x] 已完成
• [~] 不适用，并说明原因
• [ ] 尚未解决

使用以下检查项：

• 注册表包含 manifest.yaml，其中有 file_format: definition_manifest/2.0，且 schema_url 的最后一个路径段为版本号
• 每个定义和枚举成员都有 stability
• 组织本地属性/指标/跨度使用域前缀
• 本地没有重复添加边界域（http/db/messaging/rpc/network/gen-ai）条目
• Counter 和 UpDownCounter 名称没有 _total 后缀
• 时长直方图使用 s（秒）
• 模板使用与解析后的架构相匹配的 jq 筛选器（对于 definition/2，调用带有 {"v2": true} 的预构建 semconv_grouped_* 辅助函数）
• 生成的输出符合格式规范
• CI 运行 check、generate + git diff --exit-code，以及与基准分支的 diff
• 已重新阅读更改过的文件
• 已说明剩余风险或缺口