OpenTelemetry Weaver Documentation

Weaver is a toolset for working with schematized telemetry. Its core capabilities are divided into registry management, code generation, and real-time telemetry validation:

Registry Management

• Validation: Lint syntax, semantics, and custom rules for your schema.
• Resolving: Consolidate a registry and its dependencies into a single artifact.
• Comparing: Compute differences between two versions of a registry.

Code Generation

• Produce non-code artifacts (like Markdown documentation) or code (like Go code) from your schema using templates.

Real-time Telemetry

• Live-checking: Validate emitted OTLP telemetry against a schema in real-time.
• Emitting: Generate example telemetry signals based on a schema to test your receivers.

The weaver_emit crate is a library designed to emit OpenTelemetry Line Protocol (OTLP) signals that have been generated from Weaver registries.

Note: This crate is currently marked as Work-In-Progress.

Weaver Forge is a Jinja-based documentation and code generation engine used by OTEL Weaver. It transforms a resolved semantic convention registry into various artifacts (e.g., Go, HTML, Markdown, or Rust code/docs).

Key features include:

• Jinja2 Compatibility: Uses MiniJinja for template logic.
• JQ Integration: Allows preprocessing resolved registries using JQ filters to transform, group, or sort data before it reaches the templates. This keeps template logic simple by moving complex data manipulation to the JQ layer.
• Custom Extensions: Includes specialized Jinja filters, functions, and tests specifically designed for semantic conventions.

Weaver Live Check is a developer tool designed to assess sample telemetry and provide findings for improvement. It works by loading a Semantic Convention Registry and comparing it against incoming samples.

Core Workflow:

1. Ingesters: Transform input sources (Files, stdin, or OTLP) into intermediary representations.
2. Advisors: Assess the data. This includes Built-in advisors (e.g., checking for missing_attribute or type_mismatch) and External advisors defined via Rego policies (e.g., OpenTelemetry Semantic Convention rules).
3. Output: Findings (PolicyFinding) are transformed via Jinja templates into the desired output format.

The Weaver Policy Engine automates the verification of semantic conventions and telemetry schemas to ensure long-term integrity, coherence, and quality. It uses declarative rules to prevent common issues such as:

• Using attributes marked as deprecated without setting the stability field to deprecated.
• High cardinality attributes.
• Using optional attributes where required.
• Unauthorized name changes or attribute removals from released groups.
• Missing owners or contacts fields.

Policies are decoupled from the engine and can be managed in separate repositories, allowing for both OpenTelemetry-standard and company-specific enforcement.

The OpenTelemetry Collector Proto package defines the protocol used by the OpenTelemetry collector. It is organized into several specialized packages based on the type of telemetry data being handled:

• common: Contains messages shared across different services.
• trace: Contains the Trace Service protocol definitions.
• metrics: Contains the Metrics Service protocol definitions.
• logs: Contains the Logs Service protocol definitions.

The weaver_semconv crate provides the data model for the OpenTelemetry semantic convention registry. It is designed to handle the serialization and deserialization of YAML files that follow the semantic convention registry format.

Because it uses serde annotations, you can easily read from or write to various formats supported by the Serde ecosystem, including YAML and JSON.

For detailed information on the syntax and semantics used by this data model, refer to the semantic convention Definition language or the JSON schema.

The weaver_search crate provides search capabilities for OpenTelemetry semantic convention registries. It uses a SearchContext engine to query resolved registries.

Key features include:

• Fuzzy text matching: Find conventions even with slight typos or partial names.
• Type filtering: Narrow results by specific OpenTelemetry types such as attributes, metrics, spans, events, or entities.
• Stability filtering: Filter by the stability level of the convention.
• Relevance scoring: Results are ranked based on how well they match the query.
• Pagination: Handle large result sets through paginated queries.