weaver registry check/generate/diff into CI, or choosing a Weaver version for a semantic-conventions release.Use this skill when an organization wants to define its own semantic conventions on top of upstream OTel and generate language bindings from them.
\nUsage:
\notel-semantic-conventions to decide which attributes already exist upstream and should not be redeclared in the local registryotel-sdk-versions index if it lists Weaver, else https://github.com/open-telemetry/weaver/releases; references/ci-integration.md keeps a dated Weaver/semconv compatibility record for offline answersIf a companion skill is unavailable:
\nschemas/semconv-syntax.v2.md, and docs/usage.md / docs/validate.mdThree moving parts:
\nmanifest.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.)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.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.
otel/weaver:vX.Y.Z Docker image, or the setup-weaver GitHub Action). Never brew install weaver — that resolves to an unrelated Scribd tool.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.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.brief, note, examples, and annotations, but not stability or deprecated; those always come from the attribute definition.ecommerce., acme.) for org-local attributes, metrics, and spans.gofmt -w, prettier, ruff format, ...) on generated output. Jinja whitespace produces multiple blank lines; without formatting, the diff check in CI will fail spuriously.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.otel/weaver:vX.Y.Z Docker image, or the setup-weaver GitHub Action. Use Docker for CI and reproducible local runs.manifest.yaml plus one or more definition/2 YAML files declaring attributes, attribute groups, metrics, spans, events, or entities. See references/registry-authoring.md.templates/registry/<lang>/ with weaver.yaml plus *.j2. See references/template-authoring.md.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.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.
These cost time and are not obvious from the upstream docs:
\nbrew install weaver installs the wrong tool. Use GitHub releases or Docker.weaver registry generate.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.comment Jinja filter takes a keyword argument: attr.brief | comment(format=\"go\"). It already emits the // prefix; do not add another.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 (still so in the dated record in references/ci-integration.md). 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. Leave it off until the format goes stable.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.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._total; this is the semconv v1.44.0 naming rule.s) under the semconv v1.44.0 unit guidance.references/registry-authoring.mdreferences/template-authoring.mdreferences/ci-integration.mdreferences/migration-playbook.mdotel-semantic-conventionsmanual-instrumentationThese are natural follow-ups but not part of this skill:
\nweaver registry package)weaver registry live-check/emit/infer against live OTLP telemetryweaver registry mcp / weaver serveMyMetricName(meter) wrappers)If you authored or modified a Weaver registry, templates, or CI integration:
\nweaver registry check --v2 against the definition/2 registry and capture the resultweaver registry generate --v2 and the language formatter, then verify git diff --exit-code is cleanReport the final check with:
\n[x] completed[~] not applicable, with a reason[ ] unresolvedUse these items:
\nmanifest.yaml with a schema_url whose final path segment is the versionstability_total suffixs (seconds)definition/2, call the prebuilt semconv_grouped_* helpers with {\"v2\": true})check, generate + git diff --exit-code, and diff against the base branch