pub struct MetricsLayer { /* private fields */ }
Available on crate feature metrics only.
Expand description

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
  • value.: Used for discrete data points (i.e., summing them does not make semantic sense)

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!(value.qux = 1);
info!(value.abc = -1);
info!(value.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)

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§

source§

impl MetricsLayer

source

pub fn new<M>(meter_provider: M) -> Selfwhere M: MeterProvider,

Create a new instance of MetricsLayer.

Trait Implementations§

source§

impl<S> Layer<S> for MetricsLayerwhere S: Subscriber + for<'span> LookupSpan<'span>,

source§

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

Notifies this layer that an event has occurred.
source§

fn on_register_dispatch(&self, collector: &Dispatch)

Performs late initialization when installing this layer as a Subscriber. Read more
source§

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

Performs late initialization when attaching a Layer to a Subscriber. Read more
source§

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. Read more
source§

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. Read more
source§

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.
source§

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.
source§

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.
source§

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

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

fn on_enter(&self, _id: &Id, _ctx: Context<'_, S>)

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

fn on_exit(&self, _id: &Id, _ctx: Context<'_, S>)

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

fn on_close(&self, _id: Id, _ctx: Context<'_, S>)

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

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.
source§

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. Read more
source§

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

Composes this Layer with the given Subscriber, returning a Layered struct that implements Subscriber. Read more
source§

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. Read more
source§

fn boxed(self) -> Box<dyn Layer<S> + Sync + Send, Global>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. Read more

Auto Trait Implementations§

Blanket Implementations§

source§

impl<T> Any for Twhere T: 'static + ?Sized,

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
source§

impl<T> Borrow<T> for Twhere T: ?Sized,

source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

impl<T> BorrowMut<T> for Twhere T: ?Sized,

source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
source§

impl<T> From<T> for T

source§

fn from(t: T) -> T

Returns the argument unchanged.

§

impl<T> FutureExt for T

§

fn with_context(self, otel_cx: Context) -> WithContext<Self>

Attaches the provided Context to this type, returning a WithContext wrapper. Read more
§

fn with_current_context(self) -> WithContext<Self>

Attaches the current Context to this type, returning a WithContext wrapper. Read more
source§

impl<T> Instrument for T

source§

fn instrument(self, span: Span) -> Instrumented<Self>

Instruments this type with the provided Span, returning an Instrumented wrapper. Read more
source§

fn in_current_span(self) -> Instrumented<Self>

Instruments this type with the current Span, returning an Instrumented wrapper. Read more
source§

impl<T, U> Into<U> for Twhere U: From<T>,

source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

source§

impl<T, U> TryFrom<U> for Twhere U: Into<T>,

§

type Error = Infallible

The type returned in the event of a conversion error.
source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
source§

impl<T, U> TryInto<U> for Twhere U: TryFrom<T>,

§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
§

impl<V, T> VZip<V> for Twhere V: MultiLane<T>,

§

fn vzip(self) -> V

source§

impl<T> WithSubscriber for T

source§

fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self>where S: Into<Dispatch>,

Attaches the provided Subscriber to this type, returning a WithDispatch wrapper. Read more
source§

fn with_current_subscriber(self) -> WithDispatch<Self>

Attaches the current default Subscriber to this type, returning a WithDispatch wrapper. Read more