////
This file is generated! See scripts/mage/docs_collector.go
////

:modulename: statsd

[[metricbeat-module-statsd]]
[role="xpack"]
== Statsd module

The `statsd` module is a Metricbeat module which spawns a UDP server and listens for metrics in StatsD compatible
format.

[float]
=== Metric types

The module supports the following types of metrics:

*Counter (c)*:: Measurement which accumulates over period of time until flushed (value set to 0).

*Gauge (g)*:: Measurement which can increase, decrease or be set to a value.

*Timer (ms)*:: Time measurement (in milliseconds) of an event.

*Histogram (h)*:: Time measurement, alias for timer.

*Set (s)*:: Measurement which counts unique occurrences until flushed (value set to 0).

[float]
=== Module-specific configuration notes

The `statsd` module has these additional config options:

*`ttl`*:: It defines how long a metric will be reported after it was last recorded.
Irrespective of the given ttl, metrics will be reported at least once.
A ttl of zero means metrics will never expire.

*`statsd.mapping`*:: It defines how metrics will mapped from the original metric label to the event json.
Here's an example configuration:
[source,yaml]
----
statsd.mappings:
  - metric: 'ti_failures' <1>
    value:
      field: task_failures <2>
  - metric: '<job_name>_start' <1>
    labels:
      - attr: job_name <3>
        field: job_name <4>
    value:
      field: started <2>
----

<1> `metric`, required: the label key of the metric in statsd, either as a exact match string
or as a template with named label placeholder in the format `<label_placeholder>`
<2> `value.field`, required: field name where to save the metric value in the event json
<3> `label[].attr`, required when using named label placeholder: reference to the named label placeholder defined in `metric`
<4> `label[].field`, required when using named label placeholder field name where to save the named label placeholder value from the template in the event json

=== Metricsets

Currently, there is only `server` metricset in `statsd` module.

[float]
==== `server`
The metricset collects metric data sent using UDP and publishes them under the `statsd` prefix.


[float]
=== Example configuration

The Statsd module supports the standard configuration options that are described
in <<configuration-metricbeat>>. Here is an example configuration:

[source,yaml]
----
metricbeat.modules:
- module: statsd
  host: "localhost"
  port: "8125"
  enabled: false
  #ttl: "30s"
----

[float]
=== Metricsets

The following metricsets are available:

* <<metricbeat-metricset-statsd-server,server>>

include::statsd/server.asciidoc[]

