# 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.

- **Type:** Skill
- **Install:** `agentstack add skill-ollygarden-opentelemetry-agent-skills-otel-weaver`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [ollygarden](https://agentstack.voostack.com/s/ollygarden)
- **Installs:** 0
- **Category:** [Developer Tools](https://agentstack.voostack.com/c/developer-tools)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [ollygarden](https://github.com/ollygarden)
- **Source:** https://github.com/ollygarden/opentelemetry-agent-skills/tree/main/skills/otel-weaver

## Install

```sh
agentstack add skill-ollygarden-opentelemetry-agent-skills-otel-weaver
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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 

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 and names the registry, declares `semconv_version` and `schema_url`. The rest declare `attributes`, `metrics`, `spans`, `events`, `entities`. The local registry's `semconv_version` is yours to manage; bump it on changes.
2. **Templates** — directory of Jinja2 files 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. 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  (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 entry needs `stability`. Weaver refuses to generate without it.
- 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. Run `weaver registry resolve -r  -f json -o /tmp/r.json` and inspect — input `key`/`name`/`type` fields are renamed at resolve time (see `references/template-authoring.md`).

## Workflow

1. **Install or locate Weaver.** Follow the upstream install instructions at  — 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 at least one of `attributes.yaml` / `metrics.yaml` / `spans.yaml` / `events.yaml`. See `references/registry-authoring.md`.
3. **Author templates.** One target dir per language under `templates/registry//` with `weaver.yaml` plus `*.j2`. See `references/template-authoring.md`.
4. **Validate and generate.** `weaver registry check -r ./telemetry/registry/` for fast feedback. `weaver registry generate --registry ./telemetry/registry/ --templates ./telemetry/templates/  ` 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`.

## Gotchas

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

1. `brew install weaver` installs the wrong tool. Use GitHub releases or Docker.
2. Generated output is not formatter-clean. Always run the language formatter after `weaver registry generate`.
3. Resolved field names differ from input. Attribute input `key` → resolved `name`. Metric input `name` → resolved `metric_name`. Span input `type` → resolved `id` of the form `span.`, with a flat `name` string equal to the input `name.note`. Always resolve and inspect before writing a template.
4. The `comment` Jinja filter takes a keyword argument: `attr.brief | comment(format="go")`. It already emits the `// ` prefix; do not add another.
5. There is no prebuilt jq filter for spans. Use:
   ```
   semconv_signal("span"; {}) | group_by(.root_namespace) | map({root_namespace: .[0].root_namespace, spans: . | sort_by(.id)})
   ```
   It **must be single-quoted** in `weaver.yaml`; the colons in jq syntax collide with YAML mapping rules otherwise.
6. `weaver registry check` emits "File format `definition/2` is not yet stable" on every run as of 0.22.1. This is normal; do not treat it as a failure.
7. `--future` is opt-in but breaks today on `definition/2`. Note this in CI guidance and re-enable once the format goes stable.
8. 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.
9. 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 using the resolved `span.name` string at runtime is clean.
10. **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.
11. Drop the `.total` suffix from counter names — OTel naming has moved away from it.
12. Use seconds (`s`) for duration histograms, not milliseconds. Migrating from `ms` is a natural step when authoring the schema; flag it.

## 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`

## 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` against a local collector
- custom Rego policies beyond the built-ins
- helper-function codegen (`MyMetricName(meter)` wrappers)

## 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` against the registry and capture the result
- run `weaver registry generate` 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 `name`, `semconv_version`, `schema_url`
- every entry 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 names have no `.total` suffix
- duration histograms use `s` (seconds)
- templates use jq filters that match the resolved schema, with the spans filter single-quoted
- 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

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [ollygarden](https://github.com/ollygarden)
- **Source:** [ollygarden/opentelemetry-agent-skills](https://github.com/ollygarden/opentelemetry-agent-skills)
- **License:** Apache-2.0

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-ollygarden-opentelemetry-agent-skills-otel-weaver
- Seller: https://agentstack.voostack.com/s/ollygarden
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.