Lib.rs

Autometrics is an observability micro-framework built for developers.

The Rust library provides a macro that makes it easy to instrument any function with the most useful metrics: request rate, error rate, and latency. Autometrics uses instrumented function names to generate Prometheus queries so you don’t need to hand-write complicated PromQL.

To make it easy for you to spot and debug issues in production, Autometrics inserts links to live charts directly into each function’s doc comments and provides dashboards that work out of the box. It also enables you to create powerful alerts based on Service-Level Objectives (SLOs) directly in your source code. Lastly, Autometrics writes queries that correlate your software’s version info with anomalies in the metrics to help you quickly identify commits that introduced bugs or latency.

Example

use autometrics::autometrics;
use axum::{http::StatusCode, routing::*, Router, Server};

// 1. Instrument your functions with metrics
#[autometrics]
pub async fn create_user() -> Result<(), ()> {
  Ok(())
}

// 2. Export your metrics to Prometheus
pub async fn get_metrics() -> (StatusCode, String) {
  match autometrics::encode_global_metrics() {
    Ok(metrics) => (StatusCode::OK, metrics),
    Err(err) => (StatusCode::INTERNAL_SERVER_ERROR, format!("{:?}", err))
  }
}

// 3. Initialize the metrics collector in your main function
#[tokio::main]
pub async fn main() {
  let _exporter = autometrics::global_metrics_exporter();

  let app = Router::new()
      .route("/users", post(create_user))
      .route("/metrics", get(get_metrics));
  Server::bind(&([127, 0, 0, 1], 0).into())
      .serve(app.into_make_service());
}

Features

• ✨ #[autometrics] macro instruments any function or impl block to track the most useful metrics
• 💡 Writes Prometheus queries so you can understand the data generated without knowing PromQL
• 🔗 Injects links to live Prometheus charts directly into each function's doc comments
• 🔍 Identify commits that introduced errors or increased latency
• 🚨 Define alerts using SLO best practices directly in your source code
• 📊 Grafana dashboards work out of the box to visualize the performance of instrumented functions & SLOs
• ⚙️ Configurable metric collection library (opentelemetry, prometheus, or metrics)
• ⚡ Minimal runtime overhead

See Why Autometrics? for more details on the ideas behind autometrics.

Identifying commits that introduced problems

Autometrics makes it easy to spot versions and commits that introduce errors or latency.

It produces a build_info metric and uses the following labels to expose the version info of your app to Prometheus:

Using vergen to set the Git details

# Cargo.toml

[build-dependencies]
vergen = { version = "8.1", features = ["git", "gitcl"] }

// build.rs
fn main() {
  vergen::EmitBuilder::builder()
      .git_sha(true)
      .git_branch()
      .emit()
      .expect("Unable to generate build info");
}

Configuring Autometrics

Custom Prometheus URL

Autometrics inserts Prometheus query links into function documentation. By default, the links point to http://localhost:9090 but you can configure it to use a custom URL using an environment variable in your build.rs file:

// build.rs

fn main() {
  // Reload Rust analyzer after changing the Prometheus URL to regenerate the links
  let prometheus_url = "https://your-prometheus-url.example";
  println!("cargo:rustc-env=PROMETHEUS_URL={prometheus_url}");
}

Feature flags

• prometheus-exporter - exports a Prometheus metrics collector and exporter (compatible with any of the Metrics Libraries)
• custom-objective-latency - by default, Autometrics only supports a fixed set of latency thresholds for objectives. Enable this to use custom latency thresholds. Note, however, that the custom latency must match one of the buckets configured for your histogram or the alerts will not work. This is not currently compatible with the prometheus or prometheus-exporter feature.
• custom-objective-percentile by default, Autometrics only supports a fixed set of objective percentiles. Enable this to use a custom percentile. Note, however, that using custom percentiles requires generating a different recording and alerting rules file using the CLI + Sloth (see here).

Metrics Libraries

Configure the crate that autometrics will use to produce metrics by using one of the following feature flags:

• opentelemetry (enabled by default) - use the opentelemetry crate for producing metrics
• metrics - use the metrics crate for producing metrics
• prometheus - use the prometheus crate for producing metrics