DOCSEARCHbyAlgolia
Submit Docs

OpenTelemetry Rust

repository·main·Indexed 25 days ago

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

Rust implementation of the OpenTelemetry standard, providing APIs and SDKs to instrument applications for collecting and exporting traces, metrics, and logs. It includes support for various instrument types (Counter, UpDownCounter, Histogram, Gauge), context propagation via gRPC and HTTP, and bridges for logging frameworks like the tracing and log crates. Version 0.32.0.

Tokens
50.2K
Snippets
81
Records
249
Agent score
80%

What's inside opentelemetry-rust

  1. Introduction to OpenTelemetry Rust Metrics

    main
    OpenTelemetry Rust Metrics allows you to track application performance indicators such as request counts, response times, and resource utilization. This guide covers the Metrics API, including Meters, Instruments, and MeterProvider management, to help you implement robust metrics collection in Rust applications.

  2. Overview of OpenTelemetry Rust crates

    main

    The OpenTelemetry Rust ecosystem is composed of several crates depending on your needs:

    • opentelemetry: The core API crate required to instrument libraries and applications. It includes Context, Baggage, Propagators, Logging Bridge, Metrics, and Tracing APIs.
    • opentelemetry-sdk: The official SDK implementation containing Logging, Metrics, and Tracing SDKs, as well as propagator implementations.
    • opentelemetry-otlp: Exporter for sending logs, metrics, and traces in OTLP format to endpoints like the OTel Collector, Jaeger, or Prometheus.
    • opentelemetry-stdout: Exporter for sending telemetry to stdout (useful for learning and debugging).
    • opentelemetry-http: Utility functions for exporting telemetry and propagation over HTTP.
    • opentelemetry-appender-log: A logging appender that routes logs from the log crate to OpenTelemetry.
    • opentelemetry-appender-tracing: A logging appender that routes logs from the tracing crate to OpenTelemetry.
    • opentelemetry-prometheus: Pipeline and exporter for sending metrics to Prometheus.
    • opentelemetry-semantic-conventions: Provides standard OpenTelemetry semantic convention names.

  4. Understand the OpenTelemetry Rust API architecture

    main

    The opentelemetry crate provides the OpenTelemetry API for Rust, serving as a facade or no-op implementation. It defines traits for instrumentation but does not perform the actual processing or exporting of telemetry data.

    Key Components

    • Context API: Manages and propagates context for tracking trace execution across asynchronous tasks.
    • Propagators API: Defines how context is shared across process boundaries (e.g., microservices).
    • Baggage API: Allows attaching metadata to telemetry for sharing application-specific information across service boundaries.
    • Logs Bridge API: Enables bridging existing logging mechanisms (like log or tracing) with OpenTelemetry. Note: This is intended for bridge/appender authors, not end users.
    • Tracing API: Provides primitives for producing distributed traces.
    • Metrics API: Provides primitives for producing operational metrics (latency, throughput, etc.).

    Usage Recommendation

    • Library Authors: Should depend only on the opentelemetry crate. This allows your library to remain agnostic of the specific SDK or exporter used by the final application.
    • Application Developers: Must use the opentelemetry API in conjunction with an SDK (like opentelemetry-sdk) and one or more exporters to actually collect and send data.

  5. Understand OpenTelemetry Metrics Instrument Types

    main

    OpenTelemetry Rust provides a Metrics API via the opentelemetry crate for creating instruments. The opentelemetry-sdk crate implements the aggregation and forwarding of these measurements.

    Available instrument types include:

    • Counter: Monotonically increasing values (e.g., number of requests served).
    • UpDownCounter: Values that can increase or decrease (e.g., number of active connections).
    • Histogram: Distribution of values (e.g., request latency).
    • Gauge: The current value of something at the time of measurement (e.g., current CPU temperature).
    • Observable Counter / UpDownCounter / Gauge: Asynchronous variants where a user-supplied callback is invoked at collection time to report the current value.

  6. Understand OpenTelemetry Rust Metrics Memory Management

    main

    The OpenTelemetry Rust SDK uses specific strategies to manage memory during metrics aggregation:

    1. Pre-Aggregation: Aggregation occurs within the SDK locally before exporting to reduce data volume and network overhead.
    2. Cardinality Limits: The SDK respects limits on the number of unique attribute combinations to prevent memory exhaustion during 'cardinality explosions'.
    3. Memory Preallocation: The SDK attempts to pre-allocate memory required for instruments at the time of their creation to avoid allocations on the hot code path.

  7. Understand the purpose of opentelemetry-proto

    main
    The opentelemetry-proto crate provides auto-generated Protobuf types derived from the OpenTelemetry protocol specification. It also includes conversion implementations to transform these generated types into the high-level types defined in the opentelemetry crate. This crate is primarily used by exporters (such as opentelemetry-otlp) to handle the serialization and deserialization of telemetry data (traces, metrics, and logs) for transmission.

  8. Understand the OpenTelemetry Rust Layering Model

    main

    OpenTelemetry Rust is organized into layers to separate instrumentation from implementation. Developers should instrument against the API layer, while the SDK handles the heavy lifting of processing and exporting.

    1. Application code: Your code that uses the instrumentation.
    2. opentelemetry API: A lightweight facade used for instrumentation.
    3. opentelemetry-sdk: Provides concrete implementations, batching, aggregation, and lifecycle management.
    4. Processors / Readers: Components within the SDK that manage buffering and temporality.
    5. Exporters: Components that translate data into wire formats (e.g., OTLP, Zipkin, Prometheus, stdout) and handle transport to a Back-end or Collector.

  9. Bridge `log` crate logs to OpenTelemetry using `opentelemetry-appender-log`

    main
    The opentelemetry-appender-log crate provides a Log Appender that acts as a bridge, capturing logs emitted via the standard Rust log crate and forwarding them to the OpenTelemetry ecosystem. This allows you to use existing instrumentation based on the log macro system while exporting telemetry to OpenTelemetry-compatible backends.

  11. Understand OpenTelemetry Rust error handling patterns

    main

    OpenTelemetry Rust follows specific patterns for modeling errors in public API interfaces (such as SpanExporter, LogExporter, and PushMetricExporter) to ensure consistency and prevent breaking changes.

    Key principles include:

    • No panics: SDK APIs will not panic during regular operation; they return errors or log them.
    • Granular error types: Error types are consolidated within a trait only when they apply to all methods. If certain methods return different errors, the error types diverge to avoid forcing callers to handle unreachable error variants.
    • Cross-signal consolidation: Where different signals (Traces, Logs, Metrics) share the same failure modes (e.g., as dictated by the OpenTelemetry specification), they share a common error type (e.g., OTelSdkError).
    • Error boxing vs. stringification: If an error is not actionable by the caller, it is returned as a descriptive string. If the error is potentially recoverable, it is preserved using Box<dyn Error + Send + Sync> to allow the caller to inspect the source.

  12. Understand the OpenTelemetry Rust SDK architecture

    main

    The opentelemetry-sdk crate provides the official implementation of the OpenTelemetry specification for Rust. While the opentelemetry crate provides the API (traits and no-op implementations), opentelemetry-sdk provides the actual logic for:

    • Propagators Implementation: Context management and propagation.
    • Logs SDK: Implementation of the Logs SDK specification.
    • Tracing SDK: Implementation of the Tracing SDK specification.
    • Metrics SDK: Implementation of the Metrics SDK specification.

    Note that opentelemetry-sdk defines the telemetry pipeline and makes data available to processors, but it does not include exporting capabilities. You must use additional exporter crates to send data to backends.