Crate opentelemetry

source ·
Expand description

Implements the API component of OpenTelemetry.

Compiler support: requires rustc 1.64+

§Getting Started

use opentelemetry::{global, trace::{TraceContextExt, Tracer}, Context };

fn do_something() {
    let tracer = global::tracer("my_component");
    let _guard = Context::current_with_span(tracer.start("my_span")).attach();
    // do work tracked by the now current span
}

See the examples directory for different integration patterns.

§Traces

The trace module includes types for tracking the progression of a single request while it is handled by services that make up an application. A trace is a tree of Spans which are objects that represent the work being done by individual services or components involved in a request as it flows through a system.

§Creating and exporting spans

use opentelemetry::{global, trace::{Span, Tracer}, KeyValue};

// get a tracer from a provider
let tracer = global::tracer("my_service");

// start a new span
let mut span = tracer.start("my_span");

// set some attributes
span.set_attribute(KeyValue::new("http.client_ip", "83.164.160.102"));

// perform some more work...

// end or drop the span to export
span.end();

See the trace module docs for more information on creating and managing spans.

§Metrics

The metrics module includes types for recording measurements about a service at runtime.

§Creating instruments and recording measurements

use opentelemetry::{global, KeyValue};

// get a meter from a provider
let meter = global::meter("my_service");

// create an instrument
let counter = meter.u64_counter("my_counter").build();

// record a measurement
counter.add(1, &[KeyValue::new("http.client_ip", "83.164.160.102")]);

See the metrics module docs for more information on creating and managing instruments.

§Logs

The logs module contains the Logs Bridge API. It is not intended to be called by application developers directly. It is provided for logging library authors to build log appenders, that bridges existing logging systems with OpenTelemetry. Bridges for log and tracing libraries are provided via the opentelemetry-appender-log and opentelemetry-appender-tracing crates.

§Crate Feature Flags

The following core crate feature flags are available:

  • trace: Includes the trace API.
  • metrics: Includes the metrics API.
  • logs: Includes the logs bridge API.

The default feature flags are [“trace”, “metrics”, “logs”]

The following feature flags provides additional configuration for logs:

  • spec_unstable_logs_enabled: Allow users to control the log level

The following feature flags enable APIs defined in OpenTelemetry specification that is in experimental phase:

  • otel_unstable: Includes unstable APIs.

In addition to opentelemetry, the open-telemetry/opentelemetry-rust repository contains several additional crates designed to be used with the opentelemetry ecosystem. This includes exporters, samplers, as well as utility and adapter crates to assist in propagating context and instrumenting applications.

In particular, the following crates are likely to be of interest:

In addition, there are several other useful crates in the OTel Rust Contrib repo. A lot of crates maintained outside OpenTelemetry owned repos can be found in the OpenTelemetry Registry.

§Supported Rust Versions

OpenTelemetry is built against the latest stable release. The minimum supported version is 1.64. The current OpenTelemetry version is not guaranteed to build on Rust versions earlier than the minimum supported version.

The current stable Rust compiler and the three most recent minor versions before it will always be supported. For example, if the current stable compiler version is 1.49, the minimum supported version will not be increased past 1.46, three minor versions prior. Increasing the minimum supported compiler version is not considered a semver breaking change as long as doing so complies with this policy.

Modules§

  • baggage
    Primitives for sending name/value data across system boundaries.
  • global
    Utilities for working with global telemetry primitives
  • logs
    OpenTelemetry Logs Bridge API
  • metrics
    OpenTelemetry Metrics API
  • propagation
    OpenTelemetry Propagator interface
  • trace
    API for tracing applications and libraries.

Macros§

  • otel_debug
    Macro for logging debug messages in OpenTelemetry.
  • otel_error
    Macro for logging error messages in OpenTelemetry.
  • otel_info
    Note: These macros (otel_info!, otel_warn!, otel_debug!, and otel_error!) are intended to be used internally within OpenTelemetry code or for custom exporters and processors. They are not designed for general application logging and should not be used for that purpose.
  • otel_warn
    Macro for logging warning messages in OpenTelemetry.

Structs§

Enums§