:plugin: statsd
:type: output
:default_codec: plain

///////////////////////////////////////////
START - GENERATED VARIABLES, DO NOT EDIT!
///////////////////////////////////////////
:version: %VERSION%
:release_date: %RELEASE_DATE%
:changelog_url: %CHANGELOG_URL%
:include_path: ../../../../logstash/docs/include
///////////////////////////////////////////
END - GENERATED VARIABLES, DO NOT EDIT!
///////////////////////////////////////////

[id="plugins-{type}s-{plugin}"]

=== Statsd output plugin

include::{include_path}/plugin_header.asciidoc[]

==== Description

statsd is a network daemon for aggregating statistics, such as counters and timers,
and shipping over UDP to backend services, such as Graphite or Datadog. The general
idea is that you send metrics to statsd and every few seconds it will emit the
aggregated values to the backend. Example aggregates are sums, average and maximum
values, their standard deviation, etc. This plugin makes it easy to send such
metrics based on data in Logstash events.

You can learn about statsd here:

* https://codeascraft.com/2011/02/15/measure-anything-measure-everything/[Etsy blog post announcing statsd]
* https://github.com/etsy/statsd[statsd on github]

Typical examples of how this can be used with Logstash include counting HTTP hits
by response code, summing the total number of bytes of traffic served, and tracking
the 50th and 95th percentile of the processing time of requests.

Each metric emitted to statsd has a dot-separated path, a type, and a value. The
metric path is built from the `namespace` and `sender` options together with the
metric name that's picked up depending on the type of metric. All in all, the
metric path will follow this pattern:

    namespace.sender.metric

With regards to this plugin, the default namespace is "logstash", the default
sender is the `host` field, and the metric name depends on what is set as the
metric name in the `increment`, `decrement`, `timing`, `count`, `set` or `gauge`
options. In metric paths, colons (":"), pipes ("|") and at signs ("@") are reserved
and will be replaced by underscores ("_").

Example:
[source,ruby]
output {
  statsd {
    host => "statsd.example.org"
    count => {
      "http.bytes" => "%{bytes}"
    }
  }
}

If run on a host named hal9000 the configuration above will send the following
metric to statsd if the current event has 123 in its `bytes` field:

    logstash.hal9000.http.bytes:123|c

[id="plugins-{type}s-{plugin}-options"]
==== Statsd Output Configuration Options

This plugin supports the following configuration options plus the <<plugins-{type}s-{plugin}-common-options>> described later.

[cols="<,<,<",options="header",]
|=======================================================================
|Setting |Input type|Required
| <<plugins-{type}s-{plugin}-count>> |<<hash,hash>>|No
| <<plugins-{type}s-{plugin}-decrement>> |<<array,array>>|No
| <<plugins-{type}s-{plugin}-gauge>> |<<hash,hash>>|No
| <<plugins-{type}s-{plugin}-host>> |<<string,string>>|No
| <<plugins-{type}s-{plugin}-increment>> |<<array,array>>|No
| <<plugins-{type}s-{plugin}-namespace>> |<<string,string>>|No
| <<plugins-{type}s-{plugin}-port>> |<<number,number>>|No
| <<plugins-{type}s-{plugin}-sample_rate>> |<<number,number>>|No
| <<plugins-{type}s-{plugin}-sender>> |<<string,string>>|No
| <<plugins-{type}s-{plugin}-set>> |<<hash,hash>>|No
| <<plugins-{type}s-{plugin}-timing>> |<<hash,hash>>|No
|=======================================================================

Also see <<plugins-{type}s-{plugin}-common-options>> for a list of options supported by all
output plugins.

&nbsp;

[id="plugins-{type}s-{plugin}-count"]
===== `count` 

  * Value type is <<hash,hash>>
  * Default value is `{}`

A count metric. `metric_name => count` as hash. `%{fieldname}` substitutions are
allowed in the metric names.

[id="plugins-{type}s-{plugin}-decrement"]
===== `decrement` 

  * Value type is <<array,array>>
  * Default value is `[]`

A decrement metric. Metric names as array. `%{fieldname}` substitutions are
allowed in the metric names.

[id="plugins-{type}s-{plugin}-gauge"]
===== `gauge` 

  * Value type is <<hash,hash>>
  * Default value is `{}`

A gauge metric. `metric_name => gauge` as hash. `%{fieldname}` substitutions are
allowed in the metric names.

[id="plugins-{type}s-{plugin}-host"]
===== `host` 

  * Value type is <<string,string>>
  * Default value is `"localhost"`

The hostname or IP address of the statsd server.

[id="plugins-{type}s-{plugin}-increment"]
===== `increment` 

  * Value type is <<array,array>>
  * Default value is `[]`

An increment metric. Metric names as array. `%{fieldname}` substitutions are
allowed in the metric names.

[id="plugins-{type}s-{plugin}-namespace"]
===== `namespace` 

  * Value type is <<string,string>>
  * Default value is `"logstash"`

The statsd namespace to use for this metric. `%{fieldname}` substitutions are
allowed.

[id="plugins-{type}s-{plugin}-port"]
===== `port` 

  * Value type is <<number,number>>
  * Default value is `8125`

The port to connect to on your statsd server.

[id="plugins-{type}s-{plugin}-sample_rate"]
===== `sample_rate` 

  * Value type is <<number,number>>
  * Default value is `1`

The sample rate for the metric.

[id="plugins-{type}s-{plugin}-sender"]
===== `sender` 

  * Value type is <<string,string>>
  * Default value is `"%{host}"`

The name of the sender. Dots will be replaced with underscores. `%{fieldname}`
substitutions are allowed.

[id="plugins-{type}s-{plugin}-set"]
===== `set` 

  * Value type is <<hash,hash>>
  * Default value is `{}`

A set metric. `metric_name => "string"` to append as hash. `%{fieldname}`
substitutions are allowed in the metric names.

[id="plugins-{type}s-{plugin}-timing"]
===== `timing` 

  * Value type is <<hash,hash>>
  * Default value is `{}`

A timing metric. `metric_name => duration` as hash. `%{fieldname}` substitutions
are allowed in the metric names.



[id="plugins-{type}s-{plugin}-common-options"]
include::{include_path}/{type}.asciidoc[]

:default_codec!: