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 directly the real prometheus implementation behind the scenes, while axum-prometheus uses metrics behind the scenes. The advantage is that you will be easily able to add your own metrics to the same registry using the builtin prometheus macros / apis. This crate 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, this will remove most of the dependencies of the crate.

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 render function to create 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 -> default value axum_http_request_total
AXUM_HTTP_REQUESTS_DURATION_SECONDS -> default value axum_http_requests_duration_seconds
AXUM_HTTP_REQUESTS_PENDING -> default value axum_http_requests_pending
AXUM_HTTP_RESPONSE_BODY_SIZE -> default value axum_http_response_body

Using set_prefix with value myservice the names of the counters will be:

myservice_http_requests_total
myservice_http_requests_duration_seconds
myservice_http_requests_pending
myservice_http_response_body

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.2.1"

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 brings in several dependencies (reqwest, tracing, base64...). If you do not need the remote write support you can build the crate without the default features.

License

Licensed under either of

Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

Disclaimer

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

prometheus-axum-middleware 0.2.1