Struct MetricsLayer

pub struct MetricsLayer<S> { /* private fields */ }

Available on crate feature metrics only.

A layer that publishes metrics via the OpenTelemetry SDK.

Usage

No configuration is needed for this Layer, as it’s only responsible for pushing data out to the opentelemetry family of crates. For example, when using opentelemetry-otlp, that crate will provide its own set of configuration options for setting up the duration metrics will be collected before exporting to the OpenTelemetry Collector, aggregation of data points, etc.

use tracing_opentelemetry::MetricsLayer;
use tracing_subscriber::layer::SubscriberExt;
use tracing_subscriber::Registry;

// Constructing a MeterProvider is out-of-scope for the docs here, but there
// are examples in the opentelemetry repository. See:
// https://github.com/open-telemetry/opentelemetry-rust/blob/dfeac078ff7853e7dc814778524b93470dfa5c9c/examples/metrics-basic/src/main.rs#L7

let opentelemetry_metrics =  MetricsLayer::new(meter_provider);
let subscriber = Registry::default().with(opentelemetry_metrics);
tracing::subscriber::set_global_default(subscriber).unwrap();

To publish a new metric, add a key-value pair to your tracing::Event that contains following prefixes:

• monotonic_counter. (non-negative numbers): Used when the counter should only ever increase
• counter.: Used when the counter can go up or down
• histogram.: Used to report arbitrary values that are likely to be statistically meaningful

Examples:

info!(monotonic_counter.foo = 1);
info!(monotonic_counter.bar = 1.1);

info!(counter.baz = 1);
info!(counter.baz = -1);
info!(counter.xyz = 1.1);

info!(histogram.qux = 1);
info!(histogram.abc = -1);
info!(histogram.def = 1.1);

Mixing data types

Floating-point numbers

Do not mix floating point and non-floating point numbers for the same metric. If a floating point number will be used for a given metric, be sure to cast any other usages of that metric to a floating point number.

Do this:

info!(monotonic_counter.foo = 1_f64);
info!(monotonic_counter.foo = 1.1);

This is because all data published for a given metric name must be the same numeric type.

Integers

Positive and negative integers can be mixed freely. The instrumentation provided by tracing assumes that all integers are i64 unless explicitly cast to something else. In the case that an integer is cast to u64, this subscriber will handle the conversion internally.

For example:

// The subscriber receives an i64
info!(counter.baz = 1);

// The subscriber receives an i64
info!(counter.baz = -1);

// The subscriber receives a u64, but casts it to i64 internally
info!(counter.baz = 1_u64);

// The subscriber receives a u64, but cannot cast it to i64 because of
// overflow. An error is printed to stderr, and the metric is dropped.
info!(counter.baz = (i64::MAX as u64) + 1)

Attributes

When MetricsLayer outputs metrics, it converts key-value pairs into Attributes and associates them with metrics.

For example:

// adds attributes bar="baz" and qux=2 to the `foo` counter.
info!(monotonic_counter.foo = 1, bar = "baz", qux = 2);

Implementation Details

MetricsLayer holds a set of maps, with each map corresponding to a type of metric supported by OpenTelemetry. These maps are populated lazily. The first time that a metric is emitted by the instrumentation, a Metric instance will be created and added to the corresponding map. This means that any time a metric is emitted by the instrumentation, one map lookup has to be performed.

In the future, this can be improved by associating each Metric instance to its callsite, eliminating the need for any maps.

Implementations

impl<S> MetricsLayer<S>

where S: Subscriber + for<'span> LookupSpan<'span>,

pub fn new<M>(meter_provider: M) -> MetricsLayer<S>

where M: MeterProvider,

Create a new instance of MetricsLayer.

Trait Implementations

impl<S> Layer<S> for MetricsLayer<S>

where S: Subscriber + for<'span> LookupSpan<'span>,

fn on_layer(&mut self, subscriber: &mut S)

Performs late initialization when attaching a Layer to a Subscriber.

fn register_callsite(&self, metadata: &'static Metadata<'static>) -> Interest

Registers a new callsite with this layer, returning whether or not the layer is interested in being notified about the callsite, similarly to Subscriber::register_callsite.

fn enabled(&self, metadata: &Metadata<'_>, ctx: Context<'_, S>) -> bool

Returns true if this layer is interested in a span or event with the given metadata in the current Context, similarly to Subscriber::enabled.

fn on_new_span(&self, attrs: &Attributes<'_>, id: &Id, ctx: Context<'_, S>)

Notifies this layer that a new span was constructed with the given Attributes and Id.

fn on_record(&self, span: &Id, values: &Record<'_>, ctx: Context<'_, S>)

Notifies this layer that a span with the given Id recorded the given values.

fn on_follows_from(&self, span: &Id, follows: &Id, ctx: Context<'_, S>)

Notifies this layer that a span with the ID span recorded that it follows from the span with the ID follows.

fn on_event(&self, event: &Event<'_>, ctx: Context<'_, S>)

Notifies this layer that an event has occurred.

fn on_enter(&self, id: &Id, ctx: Context<'_, S>)

Notifies this layer that a span with the given ID was entered.

fn on_exit(&self, id: &Id, ctx: Context<'_, S>)

Notifies this layer that the span with the given ID was exited.

fn on_close(&self, id: Id, ctx: Context<'_, S>)

Notifies this layer that the span with the given ID has been closed.

fn on_id_change(&self, old: &Id, new: &Id, ctx: Context<'_, S>)

Notifies this layer that a span ID has been cloned, and that the subscriber returned a different ID.

fn on_register_dispatch(&self, subscriber: &Dispatch)

Performs late initialization when installing this layer as a Subscriber.

fn event_enabled(&self, _event: &Event<'_>, _ctx: Context<'_, S>) -> bool

Called before on_event, to determine if on_event should be called.

fn and_then<L>(self, layer: L) -> Layered<L, Self, S>

where L: Layer<S>, Self: Sized,

Composes this layer around the given Layer, returning a Layered struct implementing Layer.

fn with_subscriber(self, inner: S) -> Layered<Self, S>

where Self: Sized,

Composes this Layer with the given Subscriber, returning a Layered struct that implements Subscriber.

fn with_filter<F>(self, filter: F) -> Filtered<Self, F, S>

where Self: Sized, F: Filter<S>,

Available on crate features registry and std only.

Combines self with a Filter, returning a Filtered layer.

fn boxed(self) -> Box<dyn Layer<S> + Send + Sync>

where Self: Sized + Layer<S> + Send + Sync + 'static, S: Subscriber,

Available on crate features alloc or std only.

Erases the type of this Layer, returning a Boxed dyn Layer trait object.