statsd

package
v0.0.0-...-3667945 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Aug 26, 2019 License: MIT Imports: 18 Imported by: 0

README

Telegraf Service Plugin: statsd

Configuration
# Statsd Server
[[inputs.statsd]]
  ## Protocol, must be "tcp", "udp4", "udp6" or "udp" (default=udp)
  protocol = "udp"

  ## MaxTCPConnection - applicable when protocol is set to tcp (default=250)
  max_tcp_connections = 250

  ## Address and port to host UDP listener on
  service_address = ":8125"

  ## The following configuration options control when telegraf clears it's cache
  ## of previous values. If set to false, then telegraf will only clear it's
  ## cache when the daemon is restarted.
  ## Reset gauges every interval (default=true)
  delete_gauges = true
  ## Reset counters every interval (default=true)
  delete_counters = true
  ## Reset sets every interval (default=true)
  delete_sets = true
  ## Reset timings & histograms every interval (default=true)
  delete_timings = true

  ## Percentiles to calculate for timing & histogram stats
  percentiles = [90]

  ## separator to use between elements of a statsd metric
  metric_separator = "_"

  ## Parses tags in the datadog statsd format
  ## http://docs.datadoghq.com/guides/dogstatsd/
  parse_data_dog_tags = false

  ## Statsd data translation templates, more info can be read here:
  ## https://github.com/influxdata/telegraf/blob/master/docs/DATA_FORMATS_INPUT.md#graphite
  # templates = [
  #     "cpu.* measurement*"
  # ]

  ## Number of UDP messages allowed to queue up, once filled,
  ## the statsd server will start dropping packets
  allowed_pending_messages = 10000

  ## Number of timing/histogram values to track per-measurement in the
  ## calculation of percentiles. Raising this limit increases the accuracy
  ## of percentiles but also increases the memory usage and cpu time.
  percentile_limit = 1000
Description

The statsd plugin is a special type of plugin which runs a backgrounded statsd listener service while telegraf is running.

The format of the statsd messages was based on the format described in the original etsy statsd implementation. In short, the telegraf statsd listener will accept:

  • Gauges
    • users.current.den001.myapp:32|g <- standard
    • users.current.den001.myapp:+10|g <- additive
    • users.current.den001.myapp:-10|g
  • Counters
    • deploys.test.myservice:1|c <- increments by 1
    • deploys.test.myservice:101|c <- increments by 101
    • deploys.test.myservice:1|c|@0.1 <- with sample rate, increments by 10
  • Sets
    • users.unique:101|s
    • users.unique:101|s
    • users.unique:102|s <- would result in a count of 2 for users.unique
  • Timings & Histograms
    • load.time:320|ms
    • load.time.nanoseconds:1|h
    • load.time:200|ms|@0.1 <- sampled 1/10 of the time

It is possible to omit repetitive names and merge individual stats into a single line by separating them with additional colons:

  • users.current.den001.myapp:32|g:+10|g:-10|g
  • deploys.test.myservice:1|c:101|c:1|c|@0.1
  • users.unique:101|s:101|s:102|s
  • load.time:320|ms:200|ms|@0.1

This also allows for mixed types in a single line:

  • foo:1|c:200|ms

The string foo:1|c:200|ms is internally split into two individual metrics foo:1|c and foo:200|ms which are added to the aggregator separately.

Influx Statsd

In order to take advantage of InfluxDB's tagging system, we have made a couple additions to the standard statsd protocol. First, you can specify tags in a manner similar to the line-protocol, like this:

users.current,service=payroll,region=us-west:32|g
Measurements:

Meta:

  • tags: metric_type=<gauge|set|counter|timing|histogram>

Outputted measurements will depend entirely on the measurements that the user sends, but here is a brief rundown of what you can expect to find from each metric type:

  • Gauges
    • Gauges are a constant data type. They are not subject to averaging, and they don’t change unless you change them. That is, once you set a gauge value, it will be a flat line on the graph until you change it again.
  • Counters
    • Counters are the most basic type. They are treated as a count of a type of event. They will continually increase unless you set delete_counters=true.
  • Sets
    • Sets count the number of unique values passed to a key. For example, you could count the number of users accessing your system using users:<user_id>|s. No matter how many times the same user_id is sent, the count will only increase by 1.
  • Timings & Histograms
    • Timers are meant to track how long something took. They are an invaluable tool for tracking application performance.
    • The following aggregate measurements are made for timers:
      • statsd_<name>_lower: The lower bound is the lowest value statsd saw for that stat during that interval.
      • statsd_<name>_upper: The upper bound is the highest value statsd saw for that stat during that interval.
      • statsd_<name>_mean: The mean is the average of all values statsd saw for that stat during that interval.
      • statsd_<name>_stddev: The stddev is the sample standard deviation of all values statsd saw for that stat during that interval.
      • statsd_<name>_sum: The sum is the sample sum of all values statsd saw for that stat during that interval.
      • statsd_<name>_count: The count is the number of timings statsd saw for that stat during that interval. It is not averaged.
      • statsd_<name>_percentile_<P> The Pth percentile is a value x such that P% of all the values statsd saw for that stat during that time period are below x. The most common value that people use for P is the 90, this is a great number to try to optimize.
Plugin arguments
  • protocol string: Protocol used in listener - tcp or udp options
  • max_tcp_connections []int: Maximum number of concurrent TCP connections to allow. Used when protocol is set to tcp.
  • service_address string: Address to listen for statsd UDP packets on
  • delete_gauges boolean: Delete gauges on every collection interval
  • delete_counters boolean: Delete counters on every collection interval
  • delete_sets boolean: Delete set counters on every collection interval
  • delete_timings boolean: Delete timings on every collection interval
  • percentiles []int: Percentiles to calculate for timing & histogram stats
  • allowed_pending_messages integer: Number of messages allowed to queue up waiting to be processed. When this fills, messages will be dropped and logged.
  • percentile_limit integer: Number of timing/histogram values to track per-measurement in the calculation of percentiles. Raising this limit increases the accuracy of percentiles but also increases the memory usage and cpu time.
  • templates []string: Templates for transforming statsd buckets into influx measurements and tags.
  • parse_data_dog_tags boolean: Enable parsing of tags in DataDog's dogstatsd format (http://docs.datadoghq.com/guides/dogstatsd/)
Statsd bucket -> InfluxDB line-protocol Templates

The plugin supports specifying templates for transforming statsd buckets into InfluxDB measurement names and tags. The templates have a measurement keyword, which can be used to specify parts of the bucket that are to be used in the measurement name. Other words in the template are used as tag names. For example, the following template:

templates = [
    "measurement.measurement.region"
]

would result in the following transformation:

cpu.load.us-west:100|g
=> cpu_load,region=us-west 100

Users can also filter the template to use based on the name of the bucket, using glob matching, like so:

templates = [
    "cpu.* measurement.measurement.region",
    "mem.* measurement.measurement.host"
]

which would result in the following transformation:

cpu.load.us-west:100|g
=> cpu_load,region=us-west 100

mem.cached.localhost:256|g
=> mem_cached,host=localhost 256

There are many more options available, More details can be found here

Documentation

Index

Constants

View Source
const (
	// UDP packet limit, see
	// https://en.wikipedia.org/wiki/User_Datagram_Protocol#Packet_structure
	UDP_MAX_PACKET_SIZE int = 64 * 1024

	MaxTCPConnections = 250
)

Variables

This section is empty.

Functions

This section is empty.

Types

type RunningStats

type RunningStats struct {
	PercLimit int
	// contains filtered or unexported fields
}

RunningStats calculates a running mean, variance, standard deviation, lower bound, upper bound, count, and can calculate estimated percentiles. It is based on the incremental algorithm described here:

https://en.wikipedia.org/wiki/Algorithms_for_calculating_variance

func (*RunningStats) AddValue

func (rs *RunningStats) AddValue(v float64)

func (*RunningStats) Count

func (rs *RunningStats) Count() int64

func (*RunningStats) Lower

func (rs *RunningStats) Lower() float64

func (*RunningStats) Mean

func (rs *RunningStats) Mean() float64

func (*RunningStats) Percentile

func (rs *RunningStats) Percentile(n int) float64

func (*RunningStats) Stddev

func (rs *RunningStats) Stddev() float64

func (*RunningStats) Sum

func (rs *RunningStats) Sum() float64

func (*RunningStats) Upper

func (rs *RunningStats) Upper() float64

func (*RunningStats) Variance

func (rs *RunningStats) Variance() float64

type Statsd

type Statsd struct {
	// Protocol used on listener - udp or tcp
	Protocol string `toml:"protocol"`

	// Address & Port to serve from
	ServiceAddress string

	// Number of messages allowed to queue up in between calls to Gather. If this
	// fills up, packets will get dropped until the next Gather interval is ran.
	AllowedPendingMessages int

	// Percentiles specifies the percentiles that will be calculated for timing
	// and histogram stats.
	Percentiles     []int
	PercentileLimit int

	DeleteGauges   bool
	DeleteCounters bool
	DeleteSets     bool
	DeleteTimings  bool
	ConvertNames   bool

	// MetricSeparator is the separator between parts of the metric name.
	MetricSeparator string
	// This flag enables parsing of tags in the dogstatsd extension to the
	// statsd protocol (http://docs.datadoghq.com/guides/dogstatsd/)
	ParseDataDogTags bool

	// UDPPacketSize is deprecated, it's only here for legacy support
	// we now always create 1 max size buffer and then copy only what we need
	// into the in channel
	// see https://github.com/influxdata/telegraf/pull/992
	UDPPacketSize int `toml:"udp_packet_size"`

	sync.Mutex

	// bucket -> influx templates
	Templates []string

	// Protocol listeners
	UDPlistener *net.UDPConn
	TCPlistener *net.TCPListener

	MaxTCPConnections int `toml:"max_tcp_connections"`

	MaxConnections     selfstat.Stat
	CurrentConnections selfstat.Stat
	TotalConnections   selfstat.Stat
	PacketsRecv        selfstat.Stat
	BytesRecv          selfstat.Stat
	// contains filtered or unexported fields
}

func (*Statsd) Description

func (_ *Statsd) Description() string

func (*Statsd) Gather

func (s *Statsd) Gather(acc telegraf.Accumulator) error

func (*Statsd) SampleConfig

func (_ *Statsd) SampleConfig() string

func (*Statsd) Start

func (s *Statsd) Start(_ telegraf.Accumulator) error

func (*Statsd) Stop

func (s *Statsd) Stop()

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL