Metrics
Inject Arc<Metrics> and record on counters, histograms and gauges; readings batch on a PeriodicReader and export through the same OTLP endpoint.
Metrics are the aggregate counterpart to traces — reach for them when you need a number over time (signups per minute, job duration percentiles, queue depth) rather than the story of one request.
OpenTelemetryModule provides Arc<Metrics>, the app’s meter: import it in
the module whose provider injects it, and inject it like any other
dependency. Telemetry itself needs no import — main’s OpenTelemetry::init()
installs the meter the module hands out — so an app recording no metric of its
own imports the module nowhere. The module installs Metrics in its own
register, as EventsModule installs EventBus, so the access graph gates
neither way (What is global): an app
in which nothing imports it fails the boot naming OpenTelemetryModule, and a
provider whose module skips the import reaches Metrics only when a module
importing it registered first — registered before, it fails the boot. The
import beside each injection is what puts the module first. In a suite, which
never runs main, Metrics record on a meter nothing exports.
A first counter
Section titled “A first counter”Ask Metrics for the instrument by name, then record on it. The first call
makes the instrument and every later one hands back the same, so asking at the
call site costs a lookup and needs no extra field.
use std::sync::Arc;
use nest_rs::core::injectable;use nest_rs::opentelemetry::{Attribute, Metrics};
#[injectable]pub struct SignupMetrics { #[inject] metrics: Arc<Metrics>,}
impl SignupMetrics { pub fn record_signup(&self, source: &'static str) { self.metrics .counter("users.created") .add(1, &[Attribute::new("source", source)]); }}The instruments are the four synchronous kinds of the OpenTelemetry Metrics API, under their names:
| Instrument | Asked for with | Records | For |
|---|---|---|---|
Counter | metrics.counter(name) | add(u64, …) | what only grows — signups, failed jobs |
UpDownCounter | metrics.up_down_counter(name) | add(i64, …), negative too | what is in flight — open sockets, queued jobs |
Histogram | metrics.histogram(name) | record(f64, …) | what is measured per event — a latency, a size |
Gauge | metrics.gauge(name) | record(f64, …) | what is sampled — a pool’s idle connections |
Each is a cheap Clone, so a service that records on every request may also
keep one in a field.
Units, descriptions and buckets
Section titled “Units, descriptions and buckets”What an instrument declares — the unit its values are in, what it measures, a
histogram’s bucket boundaries — is declared once, by the _with call that
makes it:
use nest_rs::opentelemetry::Describe;
let latency = self.metrics.histogram_with( "posts.publish.latency", Describe::default() .with_unit("ms") .with_description("time to publish a post"), &[5.0, 25.0, 100.0, 500.0],);latency.record(elapsed_ms, &[]);counter_with, up_down_counter_with and gauge_with take the same
Describe. A later call by the same name returns the instrument already made,
whatever it declares.
Attributes
Section titled “Attributes”The second argument to add and record is a slice of Attributes — the
metric’s labels at the OTel/Prometheus boundary. A value is a bool, an i64,
an f64 or a string:
use nest_rs::opentelemetry::Attribute;
self.metrics.counter("users.created").add(1, &[ Attribute::new("org_id", org_id.to_string()), Attribute::new("source", "api"),]);Stick to a small, bounded cardinality on the label set — every distinct attribute combination becomes a separate time series.
Export
Section titled “Export”Metrics batch on a
PeriodicReader and export through the
same OTLP endpoint as the traces (set OTEL_EXPORTER_OTLP_ENDPOINT, or
OTEL_EXPORTER_OTLP_METRICS_ENDPOINT for the metrics alone). Without an endpoint, or with
OTEL_METRICS_EXPORTER=none, instrument construction still works — counter() and friends return real handles, so
wiring compiles and runs — but the meter comes from a NoopMeterProvider and
every reading is dropped. The SDK says so once, at debug: Meter was obtained from a NoopMeterProvider. No metrics will be recorded., then how to set a provider. A test that needs to assert
on an increment has to hold its own counter; there is nothing to read back
here.
The interval is 60 seconds by default, and that will look broken. Traces and logs reach a collector immediately; metrics wait for the reader’s next flush. The natural first check — record on a counter, hit the route, look at the collector — shows spans and log records with zero metrics, for a full minute. Nothing is wrong; shorten the interval for a local run:
OTEL_METRIC_EXPORT_INTERVAL=5000 nestrs run dev apior pin it in code, as with any other field:
let _otel = OpenTelemetry::init_with(OpenTelemetryConfig { metric_interval: Duration::from_secs(5), ..OpenTelemetryConfig::from_env()?})?;The variable is the specification’s, in milliseconds, and wins over the pin.
Either is held to a second to an hour — a PeriodicReader on a zero period
is a tight export loop, and an hourly one reaches the collector after the
dashboards that read it — and OpenTelemetry::init fails with
OpenTelemetryError::Config outside that range, naming the variable or the
field. A value that is not a whole number of milliseconds fails it too,
naming the variable, where the SDK would keep its period in silence.
Resource attributes
Section titled “Resource attributes”Every exported metric carries the service-level resource attributes built from
OpenTelemetryConfig, under what OTEL_SERVICE_NAME and
OTEL_RESOURCE_ATTRIBUTES set:
service.name— the binary’s package name, which#[nest_rs::main]reads off its manifestservice.version— the binary’s package versiondeployment.environment.name— none unless setservice.instance.id— a fresh UUIDv7 per process by default, so restarts get distinct identities in the backend
These come from the
opentelemetry-semantic-conventions
schema, so any backend that understands OTel semconv (Grafana Cloud, Honeycomb,
Datadog OTLP, …) keys on them out of the box.
Going further
Section titled “Going further”- Traces — the per-request story metrics aggregate.
- Logs — structured events on the same OTLP endpoint.
- OpenTelemetry — the meter provider and OTLP export.