GitHub - open-telemetry/weaver: OTel Weaver lets you easily develop, validate, document, and deploy semantic conventions

OpenTelemetry Weaver

Observability by Design

Treat your telemetry like a public API

OpenTelemetry Weaver helps teams build observability by design, enabling consistent, type-safe, and automated telemetry through semantic conventions. With Weaver, you can define, validate, and evolve your telemetry schemas, ensuring reliability and clarity across your systems.

What is Observability by Design?

Have you ever experienced:

Broken alerts after a deployment because metric names changed?
Complex, hard-to-understand queries due to inconsistent naming?
Teams struggling to interpret unclear or undocumented signals?
Missing critical instrumentation discovered only in production?

Observability by Design solves these problems by treating your observability signals (metrics, traces, logs) as a first-class public API that requires the same quality standards as your code.

An introduction to Weaver and Observability by Design is presented in the official blog post: Observability by Design: Unlocking Consistency with OpenTelemetry Weaver

Install

Pre-built binaries:

Linux, Windows and Mac installers on the releases page.

Docker:

From source:

git clone https://github.com/open-telemetry/weaver.git
cd weaver
cargo build --release

GitHub Actions:

Use Weaver in your CI/CD workflows with the setup-weaver action. See the setup-weaver documentation or check out opentelemetry-weaver-examples for practical CI workflow examples.

Usage

Weaver provides a set of tools for working with schematized telemetry.

Registry: The schema definition
- Validation: Lint syntax, semantics and custom rules
- Resolving: Consolidate the registry and its dependencies into a single artifact
- Comparing: Compute the differences between two versions of a registry
Code generation: Produce (non-)code artifacts from the schema using templates
- e.g. Go code, Markdown documentation, etc.
Working with real telemetry
- Live-checking of emitted telemetry against a schema
- Emitting example telemetry based on a schema

Examples and How-Tos

Weaver Examples - Official OTel project showcasing weaver use cases through runnable examples.
O11y by design - from the CNCF 2025 presentation
Define your own telemetry schema - A guide on how to define your own telemetry schema using semantic conventions.

Media

OpenTelemetry Weaver - Observability by Design - CNCF presentation introducing Weaver's core concepts
OpenTelemetry Semantic Conventions and How to Avoid Broken Observability - SRECON Americas 2025 presentation
Observability by Design: Unlocking Consistency with OpenTelemetry Weaver - official blog post on opentelemetry.io
Presentation slides from the Semantic Convention SIG meeting on October 23, 2023.

Main Commands

Command	Description
weaver registry check	Validates a semantic convention registry
weaver registry resolve	Resolves a semantic convention registry
weaver registry diff	Generate a diff between two versions of a semantic convention registry
weaver registry generate	Generates artifacts from a semantic convention registry
weaver registry update-markdown	Update markdown files that contain markers indicating the templates used to update the specified sections
weaver registry live-check	Check the conformance level of an OTLP stream against a semantic convention registry
weaver registry emit	Emits a semantic convention registry as example signals to your OTLP receiver
weaver registry mcp	Run an MCP server for LLM integration
weaver completion	Generate shell completions

Getting Help

Documentation: docs/
Issues: GitHub Issues
Roadmap: Github Project
Discussions: OpenTelemetry Slack #weaver

Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines.

License

Apache License 2.0 - see LICENSE for details.

Stop treating observability as an afterthought. Start building it by design.