Autometrics is an open source framework that makes it easy to understand the health and performance of your code in production.
The Rust library provides a macro that makes it trivial to track the most useful metrics for any function: request rate, error rate, and lantency. It then generates Prometheus queries to help you understand the data collected and inserts links to the live charts directly into each function's doc comments.
Autometrics also provides Grafana dashboards to get an overview of instrumented functions and enables you to create powerful alerts based on Service-Level Objectives (SLOs) directly in your source code.
```rust use autometrics::autometrics;
pub async fn create_user() { // Now this function will have metrics! } ```
Here is a demo of jumping from function docs to live Prometheus charts:
#[autometrics] macro instruments any function or impl block to track the most useful metricsopentelemetry, prometheus, or metrics)See Why Autometrics? for more details on the ideas behind autometrics.
To see autometrics in action:
shell
cargo run -p example-full-api
See the other examples for details on how to use the various features and integrations.
Or run the example in Gitpod:
Prometheus works by polling an HTTP endpoint on your server to collect the current values of all the metrics it has in memory.
Autometrics includes optional functions to help collect and prepare metrics to be collected by Prometheus.
In your Cargo.toml file, enable the optional prometheus-exporter feature:
toml
autometrics = { version = "*", features = ["prometheus-exporter"] }
Then, call the global_metrics_exporter function in your main function:
rust
pub fn main() {
let _exporter = autometrics::global_metrics_exporter();
// ...
}
And create a route on your API (probably mounted under /metrics) that returns the following:
rust
pub fn get_metrics() -> (http::StatusCode, String) {
match autometrics::encode_global_metrics() {
Ok(metrics) => (http::StatusCode::OK, metrics),
Err(err) => (http::StatusCode::INTERNAL_SERVER_ERROR, format!("{:?}", err))
}
}
Autometrics uses existing metrics libraries (see below) to produce and collect metrics.
If you are already using one of these to collect metrics, simply configure autometrics to use the same library and the metrics it produces will be exported alongside yours. You do not need to use the Prometheus exporter functions this library provides and you do not need a separate endpoint for autometrics' metrics.
Autometrics provides Grafana dashboards that will work for any project instrumented with the library.
Autometrics makes it easy to add Prometheus alerts using Service-Level Objectives (SLOs) to a function or group of functions.
This works using pre-defined Prometheus alerting rules, which can be loaded via the rule_files field in your Prometheus configuration. By default, most of the recording rules are dormant. They are enabled by specific metric labels that can be automatically attached by autometrics.
To use autometrics SLOs and alerts, create one or multiple Objectives based on the function(s) success rate and/or latency, as shown below. The Objective can be passed as an argument to the autometrics macro to include the given function in that objective.
```rust use autometrics::autometrics; use autometrics::objectives::{Objective, ObjectiveLatency, ObjectivePercentile};
const APISLO: Objective = Objective::new("api") .successrate(ObjectivePercentile::P99_9) .latency(ObjectiveLatency::Ms250, ObjectivePercentile::P99);
pub fn api_handler() { // ... } ```
Once you've added objectives to your code, you can use the Autometrics Service-Level Objectives(SLO) Dashboard to visualize the current status of your objective(s).
Autometrics creates Prometheus query links that point to http://localhost:9090 by default but you can configure it to use a custom URL using an environment variable in your build.rs file:
```rust // build.rs
fn main() { let prometheusurl = "https://your-prometheus-url.example"; println!("cargo:rustc-env=PROMETHEUSURL={prometheus_url}"); } ```
When using Rust Analyzer, you may need to reload the workspace in order for URL changes to take effect.
The Prometheus URL is only included in documentation comments so changing it will have no impact on the final compiled binary.
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).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 metricsmetrics - use the metrics crate for producing metricsprometheus - use the prometheus crate for producing metrics