Crate tracing_opentelemetry 

Tracing OpenTelemetry

tracing is a framework for instrumenting Rust programs to collect structured, event-based diagnostic information. This crate provides a layer that connects spans from multiple systems into a trace and emits them to OpenTelemetry-compatible distributed tracing systems for processing and visualization.

Special Fields

Fields with an otel. prefix are reserved for this crate and have specific meaning. They are treated as ordinary fields by other layers. The current special fields are:

• otel.name: Override the span name sent to OpenTelemetry exporters. Setting this field is useful if you want to display non-static information in your span name.
• otel.kind: Set the span kind to one of the supported OpenTelemetry span kinds. These must be specified as strings such as "client" or "server". If it is not specified, the span is assumed to be internal.
• otel.status_code: Set the span status code to one of the supported OpenTelemetry span status codes.
• otel.status_description: Set the span description of the status. This should be used only if otel.status_code is also set.

Semantic Conventions

OpenTelemetry defines conventional names for attributes of common operations. These names can be assigned directly as fields, e.g. trace_span!("request", "server.port" = 80, "url.full" = ..), and they will be passed through to your configured OpenTelemetry exporter. You can find the full list of the operations and their expected field names in the semantic conventions spec.

Stability Status

The OpenTelemetry tracing specification is stable but the underlying opentelemetry crate is not so some breaking changes will still occur in this crate as well. Metrics are not yet fully stable. You can read the specification via the spec repository.

OpenTelemetry Logging

Logging to OpenTelemetry collectors is not supported by this crate, only traces and metrics are. If you need to export logs through OpenTelemetry, consider opentelemetry-appender-tracing.

Examples

use opentelemetry_sdk::trace::SdkTracerProvider;
use opentelemetry::trace::{Tracer, TracerProvider as _};
use tracing::{error, span};
use tracing_subscriber::layer::SubscriberExt;
use tracing_subscriber::Registry;

// Create a new OpenTelemetry trace pipeline that prints to stdout
let provider = SdkTracerProvider::builder()
    .with_simple_exporter(opentelemetry_stdout::SpanExporter::default())
    .build();
let tracer = provider.tracer("readme_example");

// Create a tracing layer with the configured tracer
let telemetry = tracing_opentelemetry::layer().with_tracer(tracer);

// Use the tracing subscriber `Registry`, or any other subscriber
// that impls `LookupSpan`
let subscriber = Registry::default().with(telemetry);

// Trace executed code
tracing::subscriber::with_default(subscriber, || {
    // Spans will be sent to the configured OpenTelemetry exporter
    let root = span!(tracing::Level::TRACE, "app_start", work_units = 2);
    let _enter = root.enter();

    error!("This event will be logged in the root span.");
});

Feature Flags

• metrics: Enables the MetricsLayer type, a layer that exports OpenTelemetry metrics from specifically-named events. This enables the metrics feature flag on the opentelemetry crate. Enabled by default.

Structs

MetricsLayermetrics

A layer that publishes metrics via the OpenTelemetry SDK.

OpenTelemetryLayer

An OpenTelemetry propagation layer for use in a project that uses tracing.

OtelData

Per-span OpenTelemetry data tracked by this crate.

Traits

OpenTelemetrySpanExt

Utility functions to allow tracing Spans to accept and return OpenTelemetry Contexts.

Functions

layer

Construct a layer to track spans via OpenTelemetry.