How do I map my StatsD metrics to Prometheus using statsd_exporter?

Create a YAML configuration file with mapping rules that define how to transform StatsD metric names using glob or regex patterns. Reference captured parts with $n syntax in labels, and ensure rules are ordered correctly to avoid shadowing.

StatsD exporter vs native Prometheus client libraries: which is better?

Use the statsd_exporter if migrating from StatsD or supporting legacy apps; it bridges gaps with tagging and mapping. For new projects, native Prometheus clients are superior as they avoid translation overhead and offer direct integration.

Does statsd_exporter work with Datadog's DogStatsD tags?

Yes, it fully supports DogStatsD-style tags, converting them into Prometheus labels. However, extended aggregations are only compatible with DogStatsD tags, not other tagging styles, and mixing formats can cause errors.

What's the best cache strategy for high traffic in statsd_exporter?

For high throughput, use random replacement cache strategy with a large cache size (via --statsd.cache-size) to reduce locking. Tune event queue and flush parameters to balance performance and memory usage based on your metric cardinality.

How to deploy statsd_exporter as a sidecar in Kubernetes?

Add it as a container in your pod specs, using the Docker image prom/statsd-exporter. Mount your mapping config file as a volume, and configure relay mode if needed to forward metrics to existing StatsD servers during migration.

Can I reload the mapping config without restarting statsd_exporter?

Yes, enable the lifecycle API and send a PUT or POST request to the /-/reload endpoint. The configuration is also reloaded on SIGHUP, allowing dynamic updates without downtime.

StatsD exporter — Prometheus StatsD Metrics Exporter

What is StatsD exporter?

StatsD exporter is a bridge for monitoring systems that translates StatsD metrics into Prometheus format. It serves as a drop-in replacement for StatsD, enabling a gradual transition to native Prometheus instrumentation while supporting existing StatsD-based applications. It converts StatsD gauges, counters, timers, histograms, and distributions into Prometheus metrics (gauges, counters, summaries, or histograms) with flexible mapping rules.

Target Audience

DevOps engineers and SREs who are migrating from StatsD-based monitoring (e.g., using Librato, InfluxDB, DogStatsD, or SignalFX) to Prometheus, or who need to run both systems concurrently during a transition. It is also for teams deploying applications in sidecar patterns, such as in Kubernetes pods.

Value Proposition

Developers choose this exporter because it provides a seamless bridge with extensive tagging support for multiple StatsD variants, flexible metric mapping via glob or regex, and relay mode for gradual migration without disrupting existing workflows. Its sidecar-friendly design ensures per-instance metrics and maintains high performance with configurable caching and event flushing.

StatsD to Prometheus metrics exporter

Use Cases

Best For

Gradually migrating from a centralized StatsD server to Prometheus without losing existing metric data.
Running as a sidecar in Kubernetes pods to collect per-instance StatsD metrics and export them to Prometheus.
Translating StatsD metrics with Librato, InfluxDB, DogStatsD, or SignalFX-style tags into labeled Prometheus metrics.
Relaying StatsD metrics to an existing StatsD server while simultaneously exporting them to Prometheus for comparison.
High-throughput environments needing tunable event flushing and LRU or random-replacement caching for metric mapping performance.
Dynamically mapping dot-separated StatsD metric names into Prometheus metrics with structured labels using glob or regex rules.

Not Ideal For

Projects already fully instrumented with native Prometheus client libraries and no StatsD dependencies
Environments where StatsD metrics frequently mix different tagging styles (e.g., Librato with DogStatsD), as this causes undefined behavior
Teams needing sub-millisecond metric delivery without any batching, due to configurable event flushing that can introduce latency
Centralized StatsD setups without per-instance metric requirements, as the sidecar pattern adds deployment overhead

Pros & Cons

Pros

Flexible Metric Mapping

Supports both glob and regex-based mapping rules to transform dot-separated StatsD metrics into labeled Prometheus metrics, allowing dynamic label extraction via wildcard references like $1.

Broad Tagging Compatibility

Parses Librato, InfluxDB, DogStatsD, and SignalFX-style tags, converting them into Prometheus labels, though individual formats can be disabled via command-line flags for control.

Gradual Migration Support

Offers a relay mode to forward metrics to existing StatsD servers, enabling side-by-side operation during transition without disrupting current workflows, as shown in the sidecar diagram.

Performance Optimization

Includes configurable caching (LRU or random replacement), event queue sizing, and flushing intervals, allowing tuning for high-throughput environments as noted in the event flushing configuration section.

Cons

Tag Style Incompatibility

Mixing different tagging formats (e.g., Librato with DogStatsD) is considered an error with undefined behavior, limiting use in heterogeneous environments with diverse StatsD clients.

Configuration Complexity

Requires YAML mapping files for advanced transformations, with careful ordering needed for glob rules and slower regex matching that is executed after glob mappings, increasing setup complexity.

Interim Solution Limitation

Explicitly recommended as a temporary bridge in the README, urging users to switch to native Prometheus instrumentation long-term, which may necessitate future rework.

Frequently Asked Questions

What is StatsD exporter?

Target Audience

Value Proposition

Use Cases

Best For

Gradually migrating from a centralized StatsD server to Prometheus without losing existing metric data.
Running as a sidecar in Kubernetes pods to collect per-instance StatsD metrics and export them to Prometheus.
Translating StatsD metrics with Librato, InfluxDB, DogStatsD, or SignalFX-style tags into labeled Prometheus metrics.
Relaying StatsD metrics to an existing StatsD server while simultaneously exporting them to Prometheus for comparison.
High-throughput environments needing tunable event flushing and LRU or random-replacement caching for metric mapping performance.
Dynamically mapping dot-separated StatsD metric names into Prometheus metrics with structured labels using glob or regex rules.

Not Ideal For

Projects already fully instrumented with native Prometheus client libraries and no StatsD dependencies
Environments where StatsD metrics frequently mix different tagging styles (e.g., Librato with DogStatsD), as this causes undefined behavior
Teams needing sub-millisecond metric delivery without any batching, due to configurable event flushing that can introduce latency
Centralized StatsD setups without per-instance metric requirements, as the sidecar pattern adds deployment overhead

Pros & Cons

Pros

Flexible Metric Mapping

Supports both glob and regex-based mapping rules to transform dot-separated StatsD metrics into labeled Prometheus metrics, allowing dynamic label extraction via wildcard references like $1.

Broad Tagging Compatibility

Parses Librato, InfluxDB, DogStatsD, and SignalFX-style tags, converting them into Prometheus labels, though individual formats can be disabled via command-line flags for control.

Gradual Migration Support

Offers a relay mode to forward metrics to existing StatsD servers, enabling side-by-side operation during transition without disrupting current workflows, as shown in the sidecar diagram.

Performance Optimization

Cons

Tag Style Incompatibility

Mixing different tagging formats (e.g., Librato with DogStatsD) is considered an error with undefined behavior, limiting use in heterogeneous environments with diverse StatsD clients.

Configuration Complexity

Requires YAML mapping files for advanced transformations, with careful ordering needed for glob rules and slower regex matching that is executed after glob mappings, increasing setup complexity.

Interim Solution Limitation

Explicitly recommended as a temporary bridge in the README, urging users to switch to native Prometheus instrumentation long-term, which may necessitate future rework.

Frequently Asked Questions

StatsD exporter

What is StatsD exporter?

Overview

Use Cases

Best For

Not Ideal For

Pros & Cons

Pros

Cons

Frequently Asked Questions

Related Projects

Found a gem we're missing?

StatsD exporter

What is StatsD exporter?

Overview

Use Cases

Best For

Not Ideal For

Pros & Cons

Pros

Cons

Frequently Asked Questions

Related Projects

Found a gem we're missing?