otel-weaver
OpenTelemetry Weaver registry authoring, codegen, and CI enforcement. Use when adopting Weaver, authoring or reviewing a registry (manifest, attributes, metrics, spans, events), writing Jinja2 templates against the resolved schema, migrating hand-maintained telemetry constants, or wiring `weaver registry check`/`generate`/`diff` into CI.
ollygarden · 已有 AI 审核记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add ollygarden/opentelemetry-agent-skills --skill otel-weaver技能说明
name: otel-weaver
description: OpenTelemetry Weaver registry authoring, codegen, and CI enforcement. Use when adopting Weaver, authoring or reviewing a registry (manifest, attributes, metrics, spans, events), writing Jinja2 templates against the resolved schema, migrating hand-maintained telemetry constants, or wiring weaver registry check/generate/diff into CI.
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-conventionsto decide which attributes already exist upstream and should not be redeclared in the local registry - use
otel-sdk-versionsonly 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, anddocs/usage.md/docs/validate.md - state which fallback you used and leave any unverified item unresolved
Mental Model
Three moving parts:
- Registry — directory of YAML files.
manifest.yamlis required; itsschema_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 requireschema_urlplus optionalregistry_path. The rest declareattributes,metrics,spans,events,entities. The version segment ofschema_urlis yours to manage; bump it on changes. (semconv_versionandschema_base_urlare deprecated in favor ofschema_url; top-levelnameis not a v0.26.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/continueare supported) plus aweaver.yamlper target language describing which templates to run, with what filter, in whatapplication_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-registryis passed), andlive_check_advice(per-sample duringlive-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.
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.ZDocker image, or thesetup-weaverGitHub Action). Neverbrew install weaver— that resolves to an unrelated Scribd tool. - Reference upstream semconv attributes by
refrather 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.26.1 rejects missing definition stability but reports missing enum-member stability only as a non-fatal warning in normal mode. - In v2, an attribute reference may refine fields such as
brief,note,examples, andannotations, but notstabilityordeprecated; those always come from the attribute definition. - 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/2registry, call the grouped jq helpers with{"v2": true}; the v2 templatectxpreserves fields such as attributekey, metricname, spantype/kindand structuredspan.name.note, plus entitytype/identity/description. Seereferences/template-authoring.mdfor how to dump the exact shape.
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.ZDocker image, or thesetup-weaverGitHub Action. Use Docker for CI and reproducible local runs. - Author the registry. Required:
manifest.yamlplus one or moredefinition/2YAML files declaring attributes, attribute groups, metrics, spans, events, or entities. Seereferences/registry-authoring.md. - Author templates. One target dir per language under
templates/registry/<lang>/withweaver.yamlplus*.j2. Seereferences/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),diffagainst the base branch (surfaces breaking changes). Seereferences/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 as