Struct MetricLayerBuilder

pub struct MetricLayerBuilder<'a, T, M, S: MetricBuilderState> { /* private fields */ }

A builder for GenericMetricLayer that enables further customizations.

Most of the example code uses PrometheusMetricLayerBuilder, which is only a type alias specialized for Prometheus.

Example

use axum_prometheus::PrometheusMetricLayerBuilder;

let (metric_layer, metric_handle) = PrometheusMetricLayerBuilder::new()
    .with_ignore_patterns(&["/metrics", "/sensitive"])
    .with_group_patterns_as("/foo", &["/foo/:bar", "/foo/:bar/:baz"])
    .with_group_patterns_as("/bar", &["/auth/*path"])
    .with_default_metrics()
    .build_pair();

Implementations

impl<'a, T, M, S> MetricLayerBuilder<'a, T, M, S>

where S: MetricBuilderState,

pub fn with_ignore_pattern(self, ignore_pattern: &'a str) -> Self

Skip reporting a specific route pattern.

In the following example

use axum_prometheus::PrometheusMetricLayerBuilder;

let metric_layer = PrometheusMetricLayerBuilder::new()
    .with_ignore_pattern("/metrics")
    .build();

any request that’s URI path matches “/metrics” will be skipped altogether when reporting to the external provider.

Supports the same features as axum’s Router.

Note: with_ignore_pattern and with_allow_pattern are mutually exclusive. If you call both, the last one called takes precedence and resets the previous patterns.

Note that ignore patterns are always checked before any other group pattern rule is applied and it short-circuits if a certain route is ignored.

pub fn with_ignore_patterns(self, ignore_patterns: &'a [&'a str]) -> Self

Skip reporting a collection of route patterns.

Equivalent with calling with_ignore_pattern repeatedly.

use axum_prometheus::PrometheusMetricLayerBuilder;

let metric_layer = PrometheusMetricLayerBuilder::new()
    .with_ignore_patterns(&["/foo", "/bar/:baz"])
    .build();

Supports the same features as axum’s Router.

Note: with_ignore_patterns and with_allow_patterns are mutually exclusive. If you call both, the last one called takes precedence and resets the previous patterns.

Note that ignore patterns are always checked before any other group pattern rule is applied and it short-circuits if a certain route is ignored.

pub fn with_allow_pattern(self, allow_pattern: &'a str) -> Self

Only report requests matching a specific route pattern.

In the following example

use axum_prometheus::PrometheusMetricLayerBuilder;

let metric_layer = PrometheusMetricLayerBuilder::new()
    .with_allow_pattern("/api/*path")
    .build();

only requests whose URI path matches “/api/*path” will be reported.

Supports the same features as axum’s Router.

Note: with_allow_pattern and with_ignore_pattern are mutually exclusive. If you call both, the last one called takes precedence and resets the previous patterns.

pub fn with_allow_patterns(self, allow_patterns: &'a [&'a str]) -> Self

Only report requests matching a collection of route patterns.

Equivalent with calling with_allow_pattern repeatedly.

use axum_prometheus::PrometheusMetricLayerBuilder;

let metric_layer = PrometheusMetricLayerBuilder::new()
    .with_allow_patterns(&["/api/*path", "/public/*path"])
    .build();

Supports the same features as axum’s Router.

Note: with_allow_patterns and with_ignore_patterns are mutually exclusive. If you call both, the last one called takes precedence and resets the previous patterns.

pub fn with_group_patterns_as( self, group_pattern: &'a str, patterns: &'a [&'a str], ) -> Self

Group matching route patterns and report them under the given (arbitrary) endpoint.

This feature is commonly useful for parametrized routes. Let’s say you have these two routes:

• /foo/:bar
• /foo/:bar/:baz

By default every unique request URL path gets reported with different endpoint label. This feature allows you to report these under a custom endpoint, for instance /foo:

use axum_prometheus::PrometheusMetricLayerBuilder;

let metric_layer = PrometheusMetricLayerBuilder::new()
    // the choice of "/foo" is arbitrary
    .with_group_patterns_as("/foo", &["/foo/:bar", "foo/:bar/:baz"])
    .build();

pub fn with_endpoint_label_type(self, endpoint_label: EndpointLabel) -> Self

Determine how endpoints are reported. For more information, see EndpointLabel.

pub fn enable_response_body_size(self, enable: bool) -> Self

Enable response body size tracking.

Note:

This may introduce some performance overhead.

pub fn no_initialize_metrics(self) -> Self

By default, all metrics are initialized via metrics::describe_* macros, setting descriptions and units.

This function disables this initialization.

impl<'a, T, M> MetricLayerBuilder<'a, T, M, LayerOnly>

pub fn new() -> MetricLayerBuilder<'a, T, M, LayerOnly>

Initialize the builder.

pub fn with_prefix(self, prefix: impl Into<Cow<'a, str>>) -> Self

Use a prefix for the metrics instead of axum. This will use the following metric names:

• {prefix}_http_requests_total
• {prefix}_http_requests_pending
• {prefix}_http_requests_duration_seconds

..and will also use {prefix}_http_response_body_size, if response body size tracking is enabled.

This method will take precedence over environment variables.

Note

This function inherently changes the metric names, beware to use the appropriate names. There’re functions in the utils module to get them at runtime.

impl<'a, T, M> MetricLayerBuilder<'a, T, M, LayerOnly>

where M: MakeDefaultHandle<Out = T>,

pub fn build(self) -> GenericMetricLayer<'a, T, M>

Finalize the builder and get the previously registered metric handle out of it.

impl<'a, T, M> MetricLayerBuilder<'a, T, M, LayerOnly>

where M: MakeDefaultHandle<Out = T> + Default,

pub fn with_default_metrics(self) -> MetricLayerBuilder<'a, T, M, Paired>

Attach the default exporter handle to the builder. This is similar to initializing with GenericMetricLayer::pair.

After calling this function you can finalize with the build_pair method, and can no longer call build.

impl<'a, T, M> MetricLayerBuilder<'a, T, M, LayerOnly>

pub fn with_metrics_from_fn( self, f: impl FnOnce() -> T, ) -> MetricLayerBuilder<'a, T, M, Paired>

Attach a custom built exporter handle to the builder that’s returned from the passed in closure.

Example

use axum_prometheus::{
       PrometheusMetricLayerBuilder, AXUM_HTTP_REQUESTS_DURATION_SECONDS, utils::SECONDS_DURATION_BUCKETS,
};
use metrics_exporter_prometheus::{Matcher, PrometheusBuilder};

let (metric_layer, metric_handle) = PrometheusMetricLayerBuilder::new()
    .with_metrics_from_fn(|| {
        PrometheusBuilder::new()
            .set_buckets_for_metric(
                Matcher::Full(AXUM_HTTP_REQUESTS_DURATION_SECONDS.to_string()),
                SECONDS_DURATION_BUCKETS,
            )
            .unwrap()
            .install_recorder()
            .unwrap()
    })
    .build_pair();

After calling this function you can finalize with the build_pair method, and can no longer call build.

impl<'a, T, M> MetricLayerBuilder<'a, T, M, Paired>

where M: MakeDefaultHandle<Out = T> + Default,

pub fn build_pair(self) -> (GenericMetricLayer<'a, T, M>, T)

Finalize the builder and get out the GenericMetricLayer and the exporter handle out of it as a tuple.

Trait Implementations

impl<'a, T: Clone, M: Clone, S: Clone + MetricBuilderState> Clone for MetricLayerBuilder<'a, T, M, S>

fn clone(&self) -> MetricLayerBuilder<'a, T, M, S>

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<'a, T: Default, M: Default, S: Default + MetricBuilderState> Default for MetricLayerBuilder<'a, T, M, S>

fn default() -> MetricLayerBuilder<'a, T, M, S>

Returns the “default value” for a type.