DOCSEARCHbyAlgolia
Submit Docs

metrics-rs

repository·main·Indexed 23 days ago

https://github.com/metrics-rs/metrics

A high-performance, protocol-agnostic instrumentation framework for Rust. It provides a lightweight metrics facade (the metrics crate) for instrumenting code with counters, gauges, and histograms, and a variety of exporters to ship data to systems such as Prometheus, StatsD, New Relic, and Datadog. The ecosystem includes specialized crates like metrics-exporter-prometheus, metrics-exporter-tcp, metrics-tracing-context for tracing span integration, and the metrics-observer CLI tool for real-time metric observation.

Tokens
24.8K
Snippets
27
Records
188
Agent score
79%

What's inside metrics-rs

  2. Overview of the metrics-rs ecosystem

    main

    The metrics project provides a high-performance, protocol-agnostic instrumentation framework for Rust applications. It is designed to work for both library authors (who instrument their code) and application authors (who collect and export those metrics).

    Core Crates

    • metrics: A lightweight metrics facade, similar to the log crate. This is what library authors use to instrument their code.
    • metrics-tracing-context: Allows capturing tracing span fields as metric labels.
    • metrics-exporter-tcp: A metrics-compatible exporter for serving metrics over TCP.
    • metrics-exporter-prometheus: A metrics-compatible exporter for serving a Prometheus scrape endpoint.
    • metrics-util: Helper types and functions used across the metrics ecosystem.

  3. What is the metrics crate?

    main
    The metrics crate is a lightweight metrics facade for Rust. It provides macros similar to the log crate, allowing library and executable authors to instrument their code by collecting metrics (such as incrementing counters, gauges, and histograms) without being tied to a specific backend. The actual collection and exporting of these metrics are deferred to whatever metrics implementation is installed in the application.

  4. Use metrics-exporter-dogstatsd to send metrics to Datadog

    main
    The metrics-exporter-dogstatsd crate is a metrics-compatible exporter designed to send application metrics to a Datadog Agent. It integrates with the broader metrics ecosystem, allowing you to use standard metrics macros and functions to instrument your code and have those metrics exported via the DogStatsD protocol.

  5. Use metrics-exporter-tcp to export metrics over TCP

    main
    The metrics-exporter-tcp crate provides a metrics-compatible exporter that allows you to stream metrics to clients over a TCP connection. It is designed to work within the metrics-rs ecosystem, enabling applications to push instrumentation data to remote collectors or monitoring tools that support TCP-based metric ingestion.

  6. Use metrics-exporter-prometheus to export metrics to Prometheus

    main

    metrics-exporter-prometheus is a metrics-compatible exporter designed to send instrumentation data from the metrics crate to a Prometheus server. It allows you to leverage the unified metrics API in your Rust applications while providing a Prometheus-compatible endpoint for scraping.

    To use this exporter, add it to your Cargo.toml dependencies:

  7. Understand metrics-observer data display

    main

    The observer displays metrics as they are emitted. Note that because metrics-exporter-tcp does not store historical metrics, reconnecting to a process will cause all previous values to be lost; the observer will start collecting from scratch.

    Metric Types

    • Counters: Displayed as total: <value>, representing the total count since the connection was established.
    • Gauges: Displayed with the prefix current: <value>.
    • Histograms: Displays a pre-defined set of percentiles: minimum, p50, p99, p999, and maximum.

    Labels and Units

    • Labels: Shown in square brackets after the metric name (e.g., metric_name[system=foo]).
    • Units: If a metric has units defined, they are displayed using canonical labels (e.g., Tbps for terabits per second, MiB for mebibytes, or /s for count per second).
    • Time-based Scaling: Time-based units are automatically scaled to the most human-friendly format. For example, a value in nanoseconds representing 1.5 milliseconds will be displayed as 1.5ms. This scaling also applies to histogram percentiles.

  8. Choose an exporter for your application

    main

    While library authors only need to use the metrics crate, application authors must use an exporter to ship collected metrics to an analysis tool.

    Official Exporters

    • metrics-exporter-prometheus: For Prometheus scraping.
    • metrics-exporter-tcp: For serving metrics over TCP.

    Community Exporters

    • metrics-exporter-statsd: For StatsD.
    • metrics-exporter-newrelic: For New Relic.
    • metrics-exporter-sentry: For Sentry.
    • actix-web-metrics: Integration for the actix-web framework.
    • reqwest-metrics: Integration for the reqwest HTTP client.

  10. Run metrics-observer

    main

    metrics-observer is a text-based UI for observing metrics exported by metrics-exporter-tcp. By default, it attempts to connect to 127.0.0.1:5000.

    To connect to the default address:

    metrics-observer

    To connect to a custom address (e.g., a remote server):

    metrics-observer 192.168.1.1:5000
    # Connect to an application using the defaults of metrics-exporter-tcp
# which is 127.0.0.1:5000:
metrics-observer

# Specify a custom address to connect to:
metrics-observer 192.168.1.1:5000

  11. Key features of the DogStatsD exporter

    main

    The metrics-exporter-dogstatsd crate provides several advanced features for efficient metric reporting:

    • Client-side aggregation: Reduces downstream server load by using multi-value payloads for histograms (DSD v1.1) or aggregating points with timestamps for counters and gauges (DSD v1.3).
    • Histogram sampling: Uses reservoir sampling to maintain statistically representative samples (typically 1,000 to 2,000 samples) even with millions of inputs, limiting memory consumption.
    • Smart reporting: "Splays" the reporting of metrics over time to smooth out payload rates and avoid spiky resource consumption on the DogStatsD server.
    • Transport support: Supports UDP and Unix domain sockets in both SOCK_DGRAM and SOCK_STREAM modes.
    • Telemetry: Emits internal telemetry (active metrics, points flushed/dropped, bytes sent) under the datadog.dogstatsd.client namespace.

  12. How TCP exporter backpressure and buffering works

    main

    The TCP exporter uses a two-tier buffering system to manage throughput and prevent slow clients from impacting the application:

    1. Incoming Buffer: When metrics are fed to the exporter, they are placed in an internal buffer. If this buffer reaches the configured buffer_size limit, new incoming metrics are dropped.
    2. Client Buffers: Each connected client has its own buffer. If a client is slow (due to network or processing), its buffer will fill up. Once full, the exporter drops the oldest messages in that client's buffer (FIFO) to ensure the exporter can continue processing and fanning out metrics to other healthy clients.

    Recommendation: Always set a buffer_size using TcpBuilder::buffer_size to avoid potential memory exhaustion from unbounded growth.