Otel Weaver

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

Mental Model

Three moving parts:

1. 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.26.1 manifest field.)
2. 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.
3. 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.

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.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, and annotations, but not stability or deprecated; 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/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.

Workflow

1. 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.
2. 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.
3. Author templates. One target dir per language under templates/registry/<lang>/ with weaver.yaml plus *.j2. See references/template-authoring.md.
4. 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.
5. 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, package for writing a self-contained resolved registry artifact (the replacement for the deprecated resolve), 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.