otel-weaver

Name: otel-weaver
Author: ollygarden

69stars6forks

How to install otel-weaver?

ollygarden/opentelemetry-agent-skills/otel-weaver

$npx -y skills add ollygarden/opentelemetry-agent-skills --skill otel-weaver

Installs into the current project.

Summary

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, o

Files · 1

View on GitHub

SKILL.md

1	# OpenTelemetry Weaver
2
3	Use this skill when an organization wants to define its own semantic conventions on top of upstream OTel and generate language bindings from them.
4
5	Usage:
6	- pair with `otel-semantic-conventions` to decide which attributes already exist upstream and should not be redeclared in the local registry
7	- use `otel-sdk-versions` only for SDK package selection; Weaver versions are tracked separately at <https://github.com/open-telemetry/weaver/releases>
8
9	If a companion skill is unavailable:
10	- do not stop
11	- do not rely on memory alone when the guidance can be checked from official sources
12	- consult the Weaver repo, `schemas/semconv-syntax.v2.md`, and `docs/usage.md` / `docs/validate.md`
13	- state which fallback you used and leave any unverified item unresolved
14
15	## Mental Model
16
17	Three moving parts:
18
19	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 use `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.24.2 manifest field.)
20	2. Templates — directory of MiniJinja files (Jinja2-compatible, not full Jinja2 — auto-escaping is off by default since v0.24.x 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.
21	3. Policies — Rego rules evaluated by the Regorus (OPA-compatible) engine, in four packages: `before_resolution` (raw parsed groups), `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.
22
23	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.
24
25	## Non-Negotiable Rules
26
27	- 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.
28	- 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.
29	- Every attribute and signal definition needs `stability`; include it on enum members too, as required by the v2 syntax guide. Weaver v0.24.2 rejects missing definition stability but does not enforce enum-member stability.
30	- Use a domain prefix (e.g. `ecommerce.`, `acme.`) for org-local attributes, metrics, and spans.
31	- 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.
32	- 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`. See `references/template-authoring.md` for how to dump the exact shape.
33
34	## Workflow
35
36	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.
37	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`.
38	3. Author templates. One target dir per language under `templates/registry/<lang>/` with `weaver.yaml` plus `*.j2`. See `references/template-authoring.md`.
39	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-di

People who liked this also viewed

6 picks

Type

otel-weaver

69stars6forks

View on GitHub

How to install otel-weaver?

ollygarden/opentelemetry-agent-skills/otel-weaver

$npx -y skills add ollygarden/opentelemetry-agent-skills --skill otel-weaver

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# OpenTelemetry Weaver
2
3	Use this skill when an organization wants to define its own semantic conventions on top of upstream OTel and generate language bindings from them.
4
5	Usage:
6	- pair with `otel-semantic-conventions` to decide which attributes already exist upstream and should not be redeclared in the local registry
7	- use `otel-sdk-versions` only for SDK package selection; Weaver versions are tracked separately at <https://github.com/open-telemetry/weaver/releases>
8
9	If a companion skill is unavailable:
10	- do not stop
11	- do not rely on memory alone when the guidance can be checked from official sources
12	- consult the Weaver repo, `schemas/semconv-syntax.v2.md`, and `docs/usage.md` / `docs/validate.md`
13	- state which fallback you used and leave any unverified item unresolved
14
15	## Mental Model
16
17	Three moving parts:
18
19	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 use `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.24.2 manifest field.)
20	2. Templates — directory of MiniJinja files (Jinja2-compatible, not full Jinja2 — auto-escaping is off by default since v0.24.x 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.
21	3. Policies — Rego rules evaluated by the Regorus (OPA-compatible) engine, in four packages: `before_resolution` (raw parsed groups), `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.
22
23	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.
24
25	## Non-Negotiable Rules
26
27	- 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.
28	- 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.
29	- Every attribute and signal definition needs `stability`; include it on enum members too, as required by the v2 syntax guide. Weaver v0.24.2 rejects missing definition stability but does not enforce enum-member stability.
30	- Use a domain prefix (e.g. `ecommerce.`, `acme.`) for org-local attributes, metrics, and spans.
31	- 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.
32	- 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`. See `references/template-authoring.md` for how to dump the exact shape.
33
34	## Workflow
35
36	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.
37	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`.
38	3. Author templates. One target dir per language under `templates/registry/<lang>/` with `weaver.yaml` plus `*.j2`. See `references/template-authoring.md`.
39	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-di

People who liked this also viewed

6 picks

Type