DOCSEARCHbyAlgolia
Submit Docs

OpenTelemetry Specification

repository·main·Indexed 11 days ago

https://github.com/open-telemetry/opentelemetry-specification

Foundational requirements and expectations for all OpenTelemetry implementations to ensure interoperability in observability data. Includes details on the OpenTelemetry Enhancement Proposal (OTEP) process, development maturity levels, Semantic Versioning 2.0, and core data types such as AnyValue and Attribute Collections.

Tokens
229.9K
Snippets
229
Records
917
Agent score
88%

What's inside OpenTelemetry

  1. Overview of the OpenTelemetry Metrics Data Model

    main

    The OpenTelemetry metrics data model consists of a protocol specification and semantic conventions for delivering pre-aggregated metric timeseries data. It is designed to be highly interoperable, allowing for the unambiguous translation of data from existing formats like Prometheus and Statsd without loss of semantics or fidelity.

    Key capabilities include:

    • Interoperability: Supports importing from and exporting to various existing systems.
    • Transformation Support: Enables semantics-preserving transformations like temporal reaggregation, spatial reaggregation, and Delta-to-Cumulative conversion.
    • Flexibility: Supports both cumulative and delta transport to manage reliability, statelessness, and cost (via spatial and temporal reaggregation).

  2. Overview of the OpenTelemetry Specification

    main

    The OpenTelemetry Specification defines the cross-language requirements and expectations for all OpenTelemetry implementations. It ensures consistency across different programming languages and observability tools.

  3. Overview of the OTel Arrow Protocol

    main

    The OTelArrow protocol is a new protocol based on a generic columnar representation for metrics, logs, and traces. It is designed to significantly improve transmission efficiency for large batches of telemetry data and provides a superior representation for multivariate time-series.

    Key features include:

    • Bandwidth Reduction: Uses Apache Arrow's columnar format to optimize data transmission.
    • Multivariate Time-series Support: Better handling of complex time-series data.
    • Fallback Mechanism: Supports falling back to the standard OpenTelemetry protocol (OTLP) if an endpoint does not support OTelArrow.

    Reference Implementations:

    • OTel Arrow Adapter (Go): Specifies the protobuf spec and implements the OTel Arrow Encoder/Decoder.
    • Experimental OTel Collector: An implementation that exposes a new gRPC endpoint and provides support via the adapter library.

  4. Overview of OpenTelemetry Metrics

    main

    OpenTelemetry Metrics is designed to provide a standardized way to capture, aggregate, and export metric signals. The effort focuses on three primary design goals:

    1. Signal Correlation: Connecting metrics to other signals like traces (via exemplars), enriching metrics with Baggage and Context, and applying Resource attributes consistently across logs, metrics, and traces.
    2. Migration Path: Providing a semantic and capability-based path for OpenCensus users to migrate to OpenTelemetry.
    3. Protocol Compatibility: Supporting existing standards, specifically providing full support for Prometheus (allowing OTel clients and the Collector to match native Prometheus functionality) and the ability to collect StatsD metrics via the OpenTelemetry Collector.

  5. Overview of Resource and Entities Data Model Improvements

    main

    This proposal (part of the OpenTelemetry specification evolution) addresses friction in how Resources and Entities interact. The primary goals are to improve the data model to support:

    • Mutating Attributes: Allowing attributes that can change to participate in a Resource.
    • Lifecycle Mismatches: Enabling Resources to handle entities whose lifetimes do not align with the SDK's lifetime.
    • Async Lookup: Providing support for asynchronous resource lookups.
    • Improved Merge Rules: Fixing current Resource merge rules to ensure consistent implementation across the ecosystem.
    • Semantic Convention Progress: Enabling better modeling of semantic conventions within Resources.

  6. Overview of the Metric Configuration Service

    main

    The OpenTelemetry Metric Configuration Service allows for dynamic and remote configuration of metric collection schedules. It enables users to specify collection periods at runtime and propagate these changes to instrumented applications without restarting them.

    Key features include:

    • Per-metric granularity: Different metrics within the same application can have different collection periods.
    • Remote configuration: Configuration data is communicated from a backend service, allowing for third-party integrations.
    • Push-model oriented: This service is designed for systems using a "push" model (where the SDK pushes metrics to a backend), rather than a "pull" model (like Prometheus).

  8. Discover OpenTelemetry components via the OpenTelemetry Registry

    main
    The OpenTelemetry Registry is the central catalogue for discovering all known OpenTelemetry components. It includes both core components maintained by OpenTelemetry and third-party components. The Registry provides visibility into component ownership, quality, and compatibility, allowing users to find instrumentations for specific libraries and frameworks across different languages.

  9. Understand the OpenTelemetry Logs Vision

    main
    The OpenTelemetry Logs vision aims to treat logs as a first-class citizen alongside traces and metrics. The goal is to provide a unified observability experience through a common data model, a high-performance protocol, and a unified collection mechanism. This vision ensures that logs can be effectively correlated with other telemetry types and integrated into cloud-native environments.

  10. Understand the OpenTelemetry Specification Compliance Matrix

    main

    The OpenTelemetry specification compliance matrix tracks how different language implementations (e.g., Go, Java, Python, JS) support specific features of the specification. This is useful for developers to determine if a specific language SDK provides the necessary functionality for their observability requirements.

    Key to the matrix symbols:

    • +: Feature is supported.
    • -: Feature is not supported.
    • N/A: Feature is not applicable to the language.
    • (blank): Status of the feature is unknown.

    Optionality and Requirements:

    • X in the Optional column: The feature is optional for implementations.
    • (blank) in the Optional column: The feature is required.
    • * in the Optional column: For each type of exporter (e.g., OTLP), implementing at least one of the supported formats is required. Implementing more than one format is optional.

  11. Understand the OpenTelemetry Logs Data Model

    main

    The OpenTelemetry Logs Data Model provides a standardized way to represent logs from various sources, including system logs (e.g., Syslog), third-party application logs (e.g., Apache), and first-party application logs.

    It is designed to allow unambiguous mapping between existing log formats and the OpenTelemetry model, ensuring that data semantics are preserved during translation. The model is optimized for efficient serialization/deserialization (CPU) and storage (space) in concrete implementations like Protocol Buffers.

  12. OpenTracing Compatibility (Deprecated)

    main

    The OpenTelemetry project provides a bridge layer to allow OpenTracing-instrumented codebases to be recorded using OpenTelemetry. This is achieved via a Shim Layer that implements the OpenTracing API using the OpenTelemetry API.

    ⚠️ DEPRECATION NOTICE OpenTracing compatibility requirements are deprecated as of March 2026. Existing shims may be supported for backwards compatibility, but implementing new OpenTracing compatibility is not required. These requirements will be removed from the specification no earlier than March 2027.

    Usage Warnings: Consuming both the OpenTracing Shim and the OpenTelemetry API in the same codebase is not recommended because:

    1. Baggage Propagation Issues: If OpenTracing-instrumented code consumes baggage, the Baggage may not be properly propagated because the OpenTelemetry API is unaware of the association between the Shim's SpanContext and the underlying OpenTelemetry Baggage.
    2. In-process Propagation Mismatch: In languages with implicit in-process propagation in OpenTelemetry but none in OpenTracing (e.g., JavaScript), it can break expected semantics and lead to incorrect Context usage.