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:

docker pull otel/weaver

From source:

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

Examples and How-Tos

• O11y by design - from the CNCF 2025 presentation
• Weaver Example - doc-gen, code-gen, emit, live-check in CI/CD
• 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 completion	Generate shell completions

Documentation

• Weaver Architecture: A document detailing the architecture of the project.
• Weaver Configuration: A document detailing the configuration options available.
• Weaver Forge: An integrated template engine designed to generate documentation and code based on semantic conventions.
• Weaver Checker: An integrated policy engine for enforcing policies on semantic conventions.
• Weaver Live-check: Live check is a developer tool for assessing sample telemetry and providing advice for improvement.
• Schema Changes: A document describing the data model used to represent the differences between two versions of a semantic convention registry.
• Application Telemetry Schema OTEP: A vision and roadmap for the concept of Application Telemetry Schema.

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.