Crate prometheus_axum_middleware

prometheus-axum-middleware

Middleware and utilities for integrating Prometheus metrics with Axum applications using the default Prometheus registry.

This crate is different from axum-prometheus since it uses directy the real prometheus implementation behind the scenes, so you will be easily able to add your own metrics to the same registry using the builtin prometheus macros / apis. It also supports the prometheus remote write protocol, so you can push metrics to a Prometheus Pushgateway or remote write endpoint. The output is encoded using protobuffers and compressed with snappy, using the builtin prometheus_reqwest_remote_write crate. If you do not need the remote write support you can build the crate without the default features

Features

• Collects HTTP request metrics (counters, histograms, gauges) for method, endpoint, status and body sizes.
• Allows dynamic prefixing of metric names for multi-service environments.
• Supports excluding specific paths from metrics collection (e.g., health checks).
• Provides a /metrics endpoint compatible with Prometheus scraping.
• Includes a pusher for sending metrics to a Prometheus Pushgateway or remote write endpoint (feature).

Renaming Metrics

These metrics can be renamed by specifying environmental variables in your environment or by using the set_prefix function before starting using them:

• AXUM_HTTP_REQUESTS_TOTAL
• AXUM_HTTP_REQUESTS_DURATION_SECONDS
• AXUM_HTTP_REQUESTS_PENDING
• AXUM_HTTP_RESPONSE_BODY_SIZE (if body size tracking is enabled)

Public API

• set_prefix - Set a prefix for all HTTP metrics (should be called before the first request).
• add_excluded_paths - Exclude a slice of paths from metrics collection (e.g., /healthcheck).
• PrometheusAxumLayer - Axum middleware to record Prometheus metrics for each HTTP request.
• render - Handler for the /metrics endpoint, returns all metrics in Prometheus text format.
• install_pusher - Periodically push metrics to a Prometheus Pushgateway or remote write endpoint.

Usage

Add prometheus-axum-middleware to your Cargo.toml.

[dependencies]
prometheus-axum-middleware = "0.1.0"

Example

use prometheus_axum_middleware::{set_prefix, add_excluded_paths, PrometheusAxumLayer, render};
use axum::{Router, routing};
use std::net::SocketAddr;
 
#[tokio::main]
async fn main() {
    // Set up metrics before starting your Axum app
    set_prefix("myservice");
    add_excluded_paths(&["/healthcheck"]);
 
    let app = Router::new()
           .route("/test_body_size", routing::get(async || "Hello, World!"))
           .route("/metrics", routing::get(render))
           .layer(PrometheusAxumLayer::new());

    // Optionally, call `install_pusher` to push metrics to a remote endpoint
 
    let listener = tokio::net::TcpListener::bind(SocketAddr::from(([127, 0, 0, 1], 3000)))
        .await
        .unwrap();
    axum::serve(listener, app).await.unwrap()
}

Prometheus push gateway feature

This feature allows you to push metrics to a Prometheus Pushgateway using the remote write endpoint. The data sent to this endpoint is encoded using protobuffers and compressed with snappy, using the builtin prometheus_reqwest_remote_write crate. This feature is enabled by default and bring in several dependencies (reqwest, tracing, base64…), if you do not need the remote write support you can build the crate without the default features.

Structs

PrometheusAxumLayer

PrometheusService

Functions

add_excluded_paths

Adds one or more paths to the list of excluded paths for metrics collection, every url that starts with one of the paths in the list is excluded. This is useful for paths that you do not want to track metrics for, such as health checks or static assets, NOTE: the /metrics endpoint, used by prometheus to scrape the service is in the list by default.

install_pusher

Installs a Prometheus pusher that will send metrics to the specified push gateway URL at regular intervals. The job_name is the name of the job that will be used to identify the metrics. The push_url is the URL of the Prometheus push gateway. The interval is the duration between each push. The labels are additional labels that will be added to the metrics. The http_client is a reference to the reqwest client that will be used to send the metrics.

render

This function gathers the metrics and encodes them to a string

set_prefix

Sets a prefix for the HTTP request metrics. This is useful for namespacing metrics in environments where multiple applications NOTE: this should be called before the first request is processed, otherwise it will not take effect.