otel-weaver

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

OpenTelemetry Weaver

Use this skill when an organization wants to define its own semantic conventions on top of upstream OTel and generate language bindings from them.

Usage:

pair with
```
otel-semantic-conventions
```
to decide which attributes already exist upstream and should not be redeclared in the local registry
use
```
otel-sdk-versions
```
only for SDK package selection; Weaver versions are tracked separately at https://github.com/open-telemetry/weaver/releases

If a companion skill is unavailable:

do not stop
do not rely on memory alone when the guidance can be checked from official sources

consult the Weaver repo,

schemas/semconv-syntax.v2.md

, and

docs/usage.md

docs/validate.md

state which fallback you used and leave any unverified item unresolved

当组织希望在上游OTel语义约定基础上定义自己的语义约定，并从中生成语言绑定代码时，可使用本技能。

使用场景：

搭配
```
otel-semantic-conventions
```
技能，判断哪些属性已存在于上游语义约定中，无需在本地注册中心重新声明
仅在选择SDK包时使用
```
otel-sdk-versions
```
；Weaver的版本单独在https://github.com/open-telemetry/weaver/releases追踪

若配套技能不可用：

不要停滞
当指南可从官方来源查询时，不要仅依赖记忆

查阅Weaver仓库、

schemas/semconv-syntax.v2.md

以及

docs/usage.md

docs/validate.md

说明你使用的备选方案，并将未验证的项标记为未解决

Mental Model

核心模型

Three moving parts:

Registry — directory of YAML files.
```
manifest.yaml
```
is required; its
```
schema_url
```
(OTel schema URL format,
```
http[s]://host/path/<version>
```
) both names the registry and carries its version in the final path segment. Dependency entries also require
```
schema_url
```
plus optional
```
registry_path
```
. The rest declare
```
attributes
```
,
```
metrics
```
,
```
spans
```
,
```
events
```
,
```
entities
```
. The version segment of
```
schema_url
```
is yours to manage; bump it on changes. (
```
semconv_version
```
and
```
schema_base_url
```
are deprecated in favor of
```
schema_url
```
; top-level
```
name
```
is not a v0.25.1 manifest field.)
Templates — directory of MiniJinja files (Jinja2-compatible, not full Jinja2 — auto-escaping is off by default since v0.22.0 and loop
```
break
```
/
```
continue
```
are supported) plus a
```
weaver.yaml
```
per target language describing which templates to run, with what filter, in what
```
application_mode
```
, and with what output filename.
Policies — Rego rules evaluated by the Regorus (OPA-compatible) engine, in four packages:
```
before_resolution
```
(raw parsed groups; unsupported and skipped with
```
--v2
```
),
```
after_resolution
```
(resolved registry),
```
comparison_after_resolution
```
(only when
```
--baseline-registry
```
is passed), and
```
live_check_advice
```
(per-sample during
```
live-check
```
). Built-in OTel policies are the floor; custom policies layer on org rules.

These three replace a hand-rolled

const.go

(or equivalent): const blocks become the registry, the act of writing them becomes codegen, and tribal knowledge becomes policies.

包含三个核心部分：

注册中心 —— YAML文件目录。必须包含
```
manifest.yaml
```
；其中的
```
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.25.1版本清单的字段。）
模板 —— MiniJinja文件（兼容Jinja2，但并非完整Jinja2——自v0.22.0起默认关闭自动转义，且支持循环
```
break
```
/
```
continue
```
）目录，每个目标语言对应一个
```
weaver.yaml
```
文件，描述要运行哪些模板、使用什么过滤器、处于何种
```
application_mode
```
以及输出文件名。
策略 —— 由Regorus（兼容OPA）引擎执行的Rego规则，分为四个包：
```
before_resolution
```
（原始解析组；使用
```
--v2
```
时不支持并跳过）、
```
after_resolution
```
（解析后的注册中心）、
```
comparison_after_resolution
```
（仅在传入
```
--baseline-registry
```
时生效）、
```
live_check_advice
```
（
```
live-check
```
过程中按样本执行）。内置OTel策略是基础；自定义策略可叠加组织规则。

这三部分替代了手动编写的

const.go

（或等效文件）：常量块变为注册中心，编写常量的过程变为代码生成，经验性知识变为策略。

Non-Negotiable Rules

不可违背的规则

Install Weaver via one of the methods documented at https://github.com/open-telemetry/weaver#install (release binary,
```
otel/weaver:vX.Y.Z
```
Docker image, or the
```
setup-weaver
```
GitHub Action). Never
```
brew install weaver
```
— that resolves to an unrelated Scribd tool.
Reference upstream semconv attributes by
```
ref
```
rather than redeclaring them. Boundary domains (
```
http
```
,
```
db
```
,
```
messaging
```
,
```
rpc
```
,
```
network
```
,
```
gen-ai
```
, ...) belong in upstream OTel semconv, not in a local registry. Use the language SDK's semconv package for those at runtime.
Every attribute and signal definition needs
```
stability
```
; include it on enum members too, as required by the v2 syntax guide. Weaver v0.25.1 rejects missing definition stability but reports missing enum-member stability only as a non-fatal warning in normal mode.
Use a domain prefix (e.g.
```
ecommerce.
```
,
```
acme.
```
) for org-local attributes, metrics, and spans.
Run the language formatter (
```
gofmt -w
```
,
```
prettier
```
,
```
ruff format
```
, ...) on generated output. Jinja whitespace produces multiple blank lines; without formatting, the diff check in CI will fail spuriously.
Confirm the resolved schema shape before writing a template. For a
```
definition/2
```
registry, call the grouped jq helpers with
```
{"v2": true}
```
; the v2 template
```
ctx
```
preserves fields such as attribute
```
key
```
, metric
```
name
```
, span
```
type
```
/
```
kind
```
and structured
```
span.name.note
```
, plus entity
```
type
```
/
```
identity
```
/
```
description
```
. See
```
references/template-authoring.md
```
for how to dump the exact shape.

通过https://github.com/open-telemetry/weaver#install文档中记录的方法之一安装Weaver（发布二进制文件、
```
otel/weaver:vX.Y.Z
```
Docker镜像，或
```
setup-weaver
```
GitHub Action）。绝不要使用
```
brew install weaver
```
——这会安装一个无关的Scribd工具。
通过
```
ref
```
引用上游语义约定属性，而非重新声明。边界领域（
```
http
```
、
```
db
```
、
```
messaging
```
、
```
rpc
```
、
```
network
```
、
```
gen-ai
```
等）属于上游OTel语义约定，不应放在本地注册中心。运行时使用语言SDK的semconv包来处理这些领域。
每个属性和信号定义都需要
```
stability
```
；枚举成员也需要包含该字段，这是v2语法指南的要求。Weaver v0.25.1会拒绝缺失定义稳定性的内容，但在正常模式下仅将缺失枚举成员稳定性的情况报告为非致命警告。
为组织本地的属性、指标和跨度使用领域前缀（例如
```
ecommerce.
```
、
```
acme.
```
）。
对生成的输出运行语言格式化工具（
```
gofmt -w
```
、
```
prettier
```
、
```
ruff format
```
等）。Jinja的空格会产生多个空行；如果不格式化，CI中的差异检查会出现误判失败。
在编写模板前确认解析后的Schema结构。对于
```
definition/2
```
版本的注册中心，调用分组jq助手并传入
```
{"v2": true}
```
；v2模板的
```
ctx
```
会保留属性
```
key
```
、指标
```
name
```
、跨度
```
type
```
/
```
kind
```
和结构化
```
span.name.note
```
，以及实体
```
type
```
/
```
identity
```
/
```
description
```
等字段。请参阅
```
references/template-authoring.md
```
了解如何导出精确结构。

Workflow

工作流程

Install or locate Weaver. Follow the upstream install instructions at https://github.com/open-telemetry/weaver#install — pick a pinned release binary, the
```
otel/weaver:vX.Y.Z
```
Docker image, or the
```
setup-weaver
```
GitHub Action. Use Docker for CI and reproducible local runs.
Author the registry. Required:
```
manifest.yaml
```
plus one or more
```
definition/2
```
YAML files declaring attributes, attribute groups, metrics, spans, events, or entities. See
```
references/registry-authoring.md
```
.

Author templates. One target dir per language under

templates/registry/<lang>/

with

weaver.yaml

plus

*.j2

. See

references/template-authoring.md

Validate and generate.

weaver registry check --v2 -r ./telemetry/registry/

for fast feedback.

weaver registry generate --v2 --registry ./telemetry/registry/ --templates ./telemetry/templates/ <lang> <output-dir>

for codegen. Run the language formatter on the output.

Wire into CI. Three gates:
```
check
```
(schema),
```
generate
```
+
```
git diff --exit-code
```
(checked-in code is current),
```
diff
```
against the base branch (surfaces breaking changes). See
```
references/ci-integration.md
```
.

The Weaver CLI has more subcommands than this workflow touches:

stats

and

json-schema

for quick registry sanity checks,

update-markdown

for keeping semconv snippets in docs current,

emit

live-check

infer

for working against live OTLP telemetry,

mcp

for exposing a registry to LLM tooling, and

serve

for an HTTP+UI mode. All are out of scope here (see below) but worth knowing exist before assuming

check

generate

diff

is the whole surface.

安装或定位Weaver。遵循上游安装说明https://github.com/open-telemetry/weaver#install——选择固定版本的二进制文件、
```
otel/weaver:vX.Y.Z
```
Docker镜像，或
```
setup-weaver
```
GitHub Action。CI和可复现的本地运行使用Docker。
编写注册中心。必须包含：
```
manifest.yaml
```
以及一个或多个
```
definition/2
```
版本的YAML文件，用于声明属性、属性组、指标、跨度、事件或实体。请参阅
```
references/registry-authoring.md
```
。
编写模板。在
```
templates/registry/<lang>/
```
下为每种语言创建一个目标目录，包含
```
weaver.yaml
```
和
```
*.j2
```
文件。请参阅
```
references/template-authoring.md
```
。

验证与生成。运行

weaver registry check --v2 -r ./telemetry/registry/

获取快速反馈。运行

weaver registry generate --v2 --registry ./telemetry/registry/ --templates ./telemetry/templates/ <lang> <output-dir>

进行代码生成。对输出运行语言格式化工具。

集成到CI。三个检查环节：
```
check
```
（Schema验证）、
```
generate
```
+
```
git diff --exit-code
```
（确认已提交代码为最新）、与基准分支的
```
diff
```
（发现破坏性变更）。请参阅
```
references/ci-integration.md
```
。

Weaver CLI还有更多本工作流程未涉及的子命令：

stats

和

json-schema

用于快速的注册中心完整性检查，

update-markdown

用于保持文档中语义约定片段的更新，

emit

live-check

infer

用于处理实时OTLP遥测数据，

mcp

用于向LLM工具暴露注册中心，

serve

用于HTTP+UI模式。这些不在本文范围内（见下文），但在假设

check

generate

diff

是全部功能前，值得了解它们的存在。

Gotchas

常见陷阱

These cost time and are not obvious from the upstream docs:

```
brew install weaver
```
installs the wrong tool. Use GitHub releases or Docker.
Generated output is not formatter-clean. Always run the language formatter after
```
weaver registry generate
```
.
Jq helper defaults target the legacy schema. For
```
definition/2
```
, pass
```
{"v2": true}
```
and use the preserved v2 fields: attribute
```
key
```
, metric
```
name
```
, span
```
type
```
/
```
kind
```
and
```
span.name.note
```
, plus entity
```
type
```
/
```
identity
```
/
```
description
```
. Always generate and inspect the filtered
```
ctx
```
before writing a template.
The
```
comment
```
Jinja filter takes a keyword argument:
```
attr.brief | comment(format="go")
```
. It already emits the
```
// 
```
prefix; do not add another.
Attributes, metrics, spans, events, and entities all have prebuilt grouped jq filters (
```
semconv_grouped_attributes
```
,
```
semconv_grouped_metrics
```
,
```
semconv_grouped_spans
```
,
```
semconv_grouped_events
```
,
```
semconv_grouped_entities
```
). For
```
definition/2
```
, use (for example)
```
semconv_grouped_spans({"v2": true})
```
as a folded YAML scalar; the bare helper defaults select the legacy schema.
```
weaver registry check
```
emits "File format
```
definition/2
```
is not yet stable" (a warning) for custom v2 definition files in v0.25.1. This is normal; do not treat it as a failure.
```
--future
```
is opt-in but still elevates the
```
definition/2
```
instability warning to an error for a custom v2 registry in v0.25.1. Leave it off until the format goes stable.
CLI argument ordering for
```
generate
```
: target directory name is positional after
```
--registry
```
and
```
--templates
```
; the output directory follows.
```
--templates
```
points at the parent that contains target dirs, not at the language-specific subdir.
Span name in registry vs. runtime: required schema fields are
```
type
```
,
```
kind
```
(
```
client
```
/
```
server
```
/
```
producer
```
/
```
consumer
```
/
```
internal
```
),
```
brief
```
,
```
stability
```
, and a structured
```
name: { note: "..." }
```
. For internal business spans, putting the dotted type identifier in
```
name.note
```
and rendering the resolved
```
span.name.note
```
string at runtime is clean.
What does NOT belong in your local registry. DB, HTTP, messaging, RPC, network, GenAI, and similar boundary spans/attributes follow upstream OTel semconv. Until upstream is pulled in as a manifest dependency, instrumentation for those should reference the language SDK's semconv package directly. This is the most common modeling mistake.
Counter and UpDownCounter names should not append
```
_total
```
; this is the current semconv v1.44.0 naming rule.
Duration instruments should use seconds (
```
s
```
) under the current semconv v1.44.0 unit guidance.

这些问题会耗费时间，且在上游文档中并不明显：

```
brew install weaver
```
安装的是错误工具。请使用GitHub发布版本或Docker。
生成的输出未经过格式化。在
```
weaver registry generate
```
后务必运行语言格式化工具。
Jq助手默认针对旧版Schema。对于
```
definition/2
```
版本，传入
```
{"v2": true}
```
并使用保留的v2字段：属性
```
key
```
、指标
```
name
```
、跨度
```
type
```
/
```
kind
```
和
```
span.name.note
```
，以及实体
```
type
```
/
```
identity
```
/
```
description
```
。编写模板前务必生成并检查过滤后的
```
ctx
```
。
```
comment
```
Jinja过滤器接受关键字参数：
```
attr.brief | comment(format="go")
```
。它已自动添加
```
// 
```
前缀；不要重复添加。
属性、指标、跨度、事件和实体都有预构建的分组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。
在v0.25.1中，
```
weaver registry check
```
会为自定义v2定义文件发出"File format
```
definition/2
```
is not yet stable"（警告）。这是正常现象；不要将其视为失败。
```
--future
```
是可选参数，但在v0.25.1中仍会将自定义v2注册中心的
```
definition/2
```
不稳定性警告提升为错误。在格式稳定前请勿启用。
```
generate
```
的CLI参数顺序：目标目录名称是
```
--registry
```
和
```
--templates
```
之后的位置参数；输出目录紧随其后。
```
--templates
```
指向包含目标目录的父目录，而非特定语言的子目录。
注册中心中的跨度名称与运行时：Schema必填字段为
```
type
```
、
```
kind
```
（
```
client
```
/
```
server
```
/
```
producer
```
/
```
consumer
```
/
```
internal
```
）、
```
brief
```
、
```
stability
```
，以及结构化
```
name: { note: "..." }
```
。对于内部业务跨度，将点分隔的类型标识符放入
```
name.note
```
，并在运行时渲染解析后的
```
span.name.note
```
字符串是更简洁的做法。
不应放入本地注册中心的内容。DB、HTTP、消息传递、RPC、网络、GenAI等边界跨度/属性遵循上游OTel语义约定。在将上游作为清单依赖项引入前，这些领域的工具应直接引用语言SDK的semconv包。这是最常见的建模错误。
Counter和UpDownCounter的名称不应追加
```
_total
```
；这是当前semconv v1.44.0的命名规则。
时长工具应使用秒（
```
s
```
）；这是当前semconv v1.44.0的单位指南。

References To Load On Demand

按需查阅的参考资料

registry YAML field reference:
```
references/registry-authoring.md
```
Jinja2 patterns, jq filters, resolved-shape cheat sheet:
```
references/template-authoring.md
```
ready-to-lift GitHub Actions example:
```
references/ci-integration.md
```
hand-maintained-constants → registry walkthrough:
```
references/migration-playbook.md
```
semantic conventions skill:
```
otel-semantic-conventions
```
manual instrumentation skill:
```
manual-instrumentation
```

注册中心YAML字段参考：
```
references/registry-authoring.md
```
Jinja2模式、jq过滤器、解析结构速查表：
```
references/template-authoring.md
```
可直接复用的GitHub Actions示例：
```
references/ci-integration.md
```
手动维护常量→注册中心迁移指南：
```
references/migration-playbook.md
```
语义约定技能：
```
otel-semantic-conventions
```
手动埋点技能：
```
manual-instrumentation
```

Out Of Scope

超出范围的内容

These are natural follow-ups but not part of this skill:

publishing the registry as a versioned artifact for downstream consumers
declaring upstream semantic-conventions as a manifest dependency
```
weaver registry live-check
```
/
```
emit
```
/
```
infer
```
against live OTLP telemetry
```
weaver registry mcp
```
/
```
weaver serve
```
custom Rego policies beyond the built-ins
helper-function codegen (
```
MyMetricName(meter)
```
wrappers)

这些是自然的后续内容，但不属于本技能范畴：

将注册中心作为版本化工件发布给下游消费者
将上游语义约定声明为清单依赖项
针对实时OTLP遥测数据运行
```
weaver registry live-check
```
/
```
emit
```
/
```
infer
```
```
weaver registry mcp
```
/
```
weaver serve
```
内置策略之外的自定义Rego策略
辅助函数代码生成（
```
MyMetricName(meter)
```
包装器）

Verification Contract

验证约定

If you authored or modified a Weaver registry, templates, or CI integration:

re-open the changed files before finishing
run
```
weaver registry check --v2
```
against the
```
definition/2
```
registry and capture the result
run
```
weaver registry generate --v2
```
and the language formatter, then verify
```
git diff --exit-code
```
is clean
confirm each applicable item with codebase evidence

Report the final check with:

```
[x]
```
completed
```
[~]
```
not applicable, with a reason
```
[ ]
```
unresolved

Use these items:

registry has
```
manifest.yaml
```
with a
```
schema_url
```
whose final path segment is the version
every definition and enum member has
```
stability
```
org-local attributes/metrics/spans use a domain prefix
no boundary-domain (http/db/messaging/rpc/network/gen-ai) entries duplicated locally
Counter and UpDownCounter names have no
```
_total
```
suffix
duration histograms use
```
s
```
(seconds)
templates use jq filters that match the resolved schema (for
```
definition/2
```
, call the prebuilt
```
semconv_grouped_*
```
helpers with
```
{"v2": true}
```
)
generated output is formatter-clean
CI runs
```
check
```
,
```
generate
```
+
```
git diff --exit-code
```
, and
```
diff
```
against the base branch
changed files were re-read
remaining risks or gaps are stated

如果你编写或修改了Weaver注册中心、模板或CI集成：

在完成前重新打开修改过的文件
针对
```
definition/2
```
版本的注册中心运行
```
weaver registry check --v2
```
并记录结果
运行
```
weaver registry generate --v2
```
和语言格式化工具，然后验证
```
git diff --exit-code
```
结果为干净（无差异）
用代码库证据确认每个适用项

使用以下格式报告最终检查结果：

```
[x]
```
已完成
```
[~]
```
不适用，附原因
```
[ ]
```
未解决

检查项：

注册中心包含
```
manifest.yaml
```
，且其
```
schema_url
```
的最终路径段为版本号
每个定义和枚举成员都有
```
stability
```
字段
组织本地的属性/指标/跨度使用领域前缀
无边界领域（http/db/messaging/rpc/network/gen-ai）条目在本地重复声明
Counter和UpDownCounter名称无
```
_total
```
后缀
时长直方图使用
```
s
```
（秒）作为单位
模板使用与解析后Schema匹配的jq过滤器（对于
```
definition/2
```
版本，调用预构建的
```
semconv_grouped_*
```
助手并传入
```
{"v2": true}
```
）
生成的输出已格式化
CI运行
```
check
```
、
```
generate
```
+
```
git diff --exit-code
```
，以及与基准分支的
```
diff
```
已重新阅读修改过的文件
已说明剩余风险或空白点