https://github.com/open-telemetry/weaver
OTel Weaver lets you easily develop, validate, document, and deploy semantic conventions
https://github.com/open-telemetry/weaver
codegen documentation observability opentelemetry policy semconv
Last synced: 3 months ago
JSON representation
OTel Weaver lets you easily develop, validate, document, and deploy semantic conventions
- Host: GitHub
- URL: https://github.com/open-telemetry/weaver
- Owner: open-telemetry
- License: apache-2.0
- Created: 2024-02-07T18:14:56.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2025-03-28T22:14:35.000Z (about 1 year ago)
- Last Synced: 2025-03-28T23:24:14.708Z (about 1 year ago)
- Topics: codegen, documentation, observability, opentelemetry, policy, semconv
- Language: Rust
- Homepage:
- Size: 7.24 MB
- Stars: 99
- Watchers: 19
- Forks: 40
- Open Issues: 64
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Codeowners: CODEOWNERS
- Security: SECURITY.md
Awesome Lists containing this project
README
# OpenTelemetry Weaver
### Observability by Design
_Treat your telemetry like a public API_
[](https://github.com/open-telemetry/weaver/actions/workflows/ci.yml)
[](https://codecov.io/gh/open-telemetry/weaver)
[](https://github.com/open-telemetry/weaver/actions/workflows/audit.yml)
[](https://opensource.org/licenses/Apache-2.0)
[](https://cloud-native.slack.com/archives/C0697EXNTL3)
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](https://opentelemetry.io/blog/2025/otel-weaver/)
## Install
**Pre-built binaries:**
Linux, Windows and Mac installers on the [releases](https://github.com/open-telemetry/weaver/releases) page.
**Docker:**
```bash
docker pull otel/weaver
```
**From source:**
```bash
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](.github/actions/setup-weaver/README.md) or check out [opentelemetry-weaver-examples](https://github.com/open-telemetry/opentelemetry-weaver-examples) for practical CI workflow examples.
## Usage
Weaver provides a _set of tools_ for working with **schematized telemetry**.
- **[Registry](./docs/registry.md)**: The schema definition
- [**Validation**](./docs/validate.md): Lint syntax, semantics and custom rules
- **Resolving**: Consolidate the registry and its dependencies into a single artifact
- [**Comparing**](docs/schema-changes.md): Compute the differences between two versions of a registry
- [**Code generation**](./docs/codegen.md): Produce (non-)code artifacts from the schema using templates
- e.g. Go code, Markdown documentation, etc.
- Working with real telemetry
- [**Live-checking**](/crates/weaver_live_check/README.md) of emitted telemetry against a schema
- **Emitting** example telemetry based on a schema
Further reading:
- [Weaver Architecture](docs/architecture.md): A document detailing the architecture of the project.
- [Application Telemetry Schema OTEP](https://github.com/open-telemetry/opentelemetry-specification/blob/main/oteps/0243-app-telemetry-schema-vision-roadmap.md): A vision and roadmap for the concept of Application Telemetry Schema.
## Examples and How-Tos
- [Weaver Examples](https://github.com/open-telemetry/opentelemetry-weaver-examples) - Official OTel project showcasing weaver use cases through runnable examples.
- [O11y by design](https://github.com/jsuereth/o11y-by-design/) - from the CNCF 2025 presentation
- [Define your own telemetry schema](docs/define-your-own-telemetry-schema.md) - A guide on how to define your own
telemetry schema using semantic conventions.
## Media
- [OpenTelemetry Weaver - Observability by Design](https://www.youtube.com/watch?v=BJt6LyJEYD0) - CNCF presentation introducing Weaver's core concepts
- [OpenTelemetry Semantic Conventions and How to Avoid Broken Observability](https://www.youtube.com/watch?v=Vd6MheRkHss) - SRECON Americas 2025 presentation
- [Observability by Design: Unlocking Consistency with OpenTelemetry Weaver](https://opentelemetry.io/blog/2025/otel-weaver/) - official blog post on opentelemetry.io
- [Presentation slides from the Semantic Convention SIG meeting on October 23, 2023](https://docs.google.com/presentation/d/1nxt5VFlC1mUjZ8eecUYK4e4SxThpIVj1IRnIcodMsNI/edit?usp=sharing).
## Main Commands
| Command | Description |
|---------------------------------------------------------------------------|---------------------------------------------|
| [weaver registry check](docs/usage.md#registry-check) | Validates a semantic convention registry |
| [weaver registry resolve](docs/usage.md#registry-resolve) | Resolves a semantic convention registry |
| [weaver registry diff](docs/usage.md#registry-diff) | Generate a diff between two versions of a semantic convention registry |
| [weaver registry generate](docs/usage.md#registry-generate) | Generates artifacts from a semantic convention registry |
| [weaver registry update-markdown](docs/usage.md#registry-update-markdown) | Update markdown files that contain markers indicating the templates used to update the specified sections |
| [weaver registry live-check](docs/usage.md#registry-live-check) | Check the conformance level of an OTLP stream against a semantic convention registry |
| [weaver registry emit](docs/usage.md#registry-emit) | Emits a semantic convention registry as example signals to your OTLP receiver |
| [weaver registry mcp](docs/mcp-server.md) | Run an MCP server for LLM integration |
| [weaver completion](docs/usage.md#completion) | Generate shell completions |
## Getting Help
- **Documentation**: [docs/](docs/)
- **Issues**: [GitHub Issues](https://github.com/open-telemetry/weaver/issues)
- **Roadmap**: [Github Project](https://github.com/orgs/open-telemetry/projects/74)
- **Discussions**: [OpenTelemetry Slack #weaver](https://cloud-native.slack.com/archives/C0697EXNTL3)
## Contributing
We welcome contributions! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
## License
Apache License 2.0 - see [LICENSE](LICENSE) for details.
---
_Stop treating observability as an afterthought. Start building it by design._