Crate opinionated_metrics

source · [−]
Expand description

An “opinioned” interface to the metrics library.

Our goal is to provide a set of sensible defaults, so that:

  1. Programs using opinionated_metrics can set up metrics reporting with just a few lines of code.
  2. Users have one consistent way to configure metrics reporting.

Features

Here’s what’s implemented, and what might get done depending on what the maintainers need at work.

  • Backends
    • Logging
    • NewRelic
    • Prometheus
    • (PRs for other popular backends will be considered!)
  • Modes
    • Metrics reporting for CLI tools.
    • Metrics reporting for servers.
  • Automatic reporting at scheduled intervals.

Example (CLI)

// Set up metrics reporting for a CLI tool, using environment variables.
let metrics_handle = opinionated_metrics::initialize_cli()?;

// Do stuff.

// Send a metrics report when the CLI tool has finished running.
metrics_handle.report().await?;

Configuration

Depending on what environment variables are set, we will use different reporting backends:

  • NEW_RELIC_API_KEY: Report metrics to NewRelic.
  • None of the above: Log metrics in Prometheus format using tracing::info.

Metric naming conventions

For best results across different metrics reporting systems, we recommend following the Prometheus metric naming conventions, except using periods to separate the different components of the name.

Example metric names:

  • myapp.requests.total: Counter with no units.
  • myapp.processed.bytes_total: Counter with units.
  • myapp.memory_usage.bytes: Gauge with units.

Label naming

Labels should be “low-arity”. Specifically, that means that labels should have only a small number of possible values, because each possible label value will require most backends to store a new time series.

Structs

Builder
A builder that can be used to configure metrics reporting.
Error
A metrics-related error
Handle
A handle that can be used to interact with the metrics registry.

Enums

Mode
What mode (CLI or server) should we use?

Functions

initialize_cli
Initialize an appropriate metrics registry, configured for a CLI tool.