Configuration: StatsD metrics

This page documents the StatsD metrics export configuration for Ferron. The observability-statsd module sends the internal metrics of Ferron to a StatsD server over UDP. This lets you integrate with StatsD-compatible monitoring stacks, such as Graphite, Telegraf, and Datadog Agent.

The module supports the StatsD protocol and optional DogStatsD extensions. You can enable the DogStatsD extensions with the datadog directive.

Directives⁠#

You configure StatsD metrics in observability blocks with provider statsd:

observability {
    provider statsd
    host "127.0.0.1"
    port 8125
    prefix "myapp"
    datadog true
}

Configuration directives⁠#

The server sends each metric as a separate UDP datagram. The module does not wait for acknowledgments, so a missing or slow StatsD server does not slow down Ferron.

Metric name prefixes⁠#

The prefix directive prepends a namespace to every metric name. This is useful when several services share one StatsD server. With prefix "myapp", the metric ferron.http.server.request_count becomes myapp.ferron.http.server.request_count.

Without a prefix directive, the module sends metric names as-is. Ferron metric names already start with ferron., so you usually do not need a prefix.

Metric type mapping⁠#

Ferron emits OpenTelemetry-style metric events. The module maps them to StatsD types:

Histogram metrics become timers with the ms type. When the metric unit is seconds, the module converts the value to milliseconds. This matches the StatsD timer convention.

In Datadog mode (datadog true), histogram metrics use the DogStatsD histogram type h instead of ms. The module does not convert the unit in Datadog mode, because DogStatsD applies its own histogram aggregations.

Datadog extensions⁠#

Set datadog true to enable DogStatsD extensions:

• Metric tags. The module renders metric attributes as DogStatsD tags, for example |#ferron.host:localhost,http.response.status_code:200. Control plane metadata becomes tags with the ferron_control_plane_ key prefix.
• Histogram metric type. Histogram metrics use the DogStatsD histogram type h.

Tag values are sanitized for the DogStatsD tag syntax. The reserved characters ,, #, and : become ?. This prevents tag injection.

Without datadog, the module does not add tags and sends all histogram metrics as ms timers.

Baggage promotion⁠#

The baggage sub-directive promotes specific W3C Baggage keys into DogStatsD tags. This is useful for adding request-scoped context (such as tenant IDs or user roles) to your metrics without custom instrumentation. Promoted keys are only emitted when datadog is enabled, because vanilla StatsD has no tag syntax.

observability {
    provider statsd
    datadog true

    baggage {
        key "tenant.id" {
            attribute "tenant.id"
            max_distinct 100
        }
    }
}

Each key entry configures one baggage key to promote:

Example⁠#

observability {
    provider statsd
    host "statsd.internal.example.com"
    port 8125
    prefix "web"
}

This configuration sends metrics such as web.ferron.http.server.request_count:1|c to statsd.internal.example.com:8125.

For more information about the metrics Ferron emits, see Metrics.