statsite

Statsite

Statsite is a metrics aggregation server. Statsite is based heavily on Etsy's StatsD https://github.com/etsy/statsd, and is wire compatible.

Features

• Multiple metric types
  • Key / Value
  • Gauges
  • Counters
  • Timers
  • Sets
• Efficient summary metrics for timer data:
  • Mean
  • Min/Max
  • Standard deviation
  • Median, Percentile 95, Percentile 99
  • Histograms
• Dynamic set implementation:
  • Exactly counts for small sets
  • HyperLogLog for large sets
• Included sinks:
  • Graphite
  • InfluxDB
  • Ganglia
  • Librato
  • CloudWatch
  • OpenTSDB
  • HTTP
• Binary protocol
• TCP, UDP, and STDIN
• Fast

Architecture

Statsite is designed to be both highly performant, and very flexible. To achieve this, it implements the stats collection and aggregation in pure C, using an event loop to be extremely fast. This allows it to handle hundreds of connections, and millions of metrics. After each flush interval expires, statsite performs a fork/exec to start a new stream handler invoking a specified application. Statsite then streams the aggregated metrics over stdin to the application, which is free to handle the metrics as it sees fit.

This allows statsite to aggregate metrics and then ship metrics to any number of sinks (Graphite, SQL databases, etc). There is an included Python script that ships metrics to graphite.

Statsite tries to minimize memory usage by not storing all the metrics that are received. Counter values are aggregated as they are received, and timer values are stored and aggregated using the Cormode-Muthukrishnan algorithm from "Effective Computation of Biased Quantiles over Data Streams". This means that the percentile values are not perfectly accurate, and are subject to a specifiable error epsilon. This allows us to store only a fraction of the samples.

Histograms can also be optionally maintained for timer values. The minimum and maximum values along with the bin widths must be specified in advance, and as samples are received the bins are updated. Statsite supports multiple histograms configurations, and uses a longest-prefix match policy.

Handling of Sets in statsite depend on the number of entries received. For small cardinalities (<64 currently), statsite will count exactly the number of unique items. For larger sets, it switches to using a HyperLogLog to estimate cardinalities with high accuracy and low space utilization. This allows statsite to estimate huge set sizes without retaining all the values. The parameters of the HyperLogLog can be tuned to provide greater accuracy at the cost of memory.

The HyperLogLog is based on the Google paper, "HyperLogLog in Practice: Algorithmic Engineering of a State of The Art Cardinality Estimation Algorithm".

Install

The following quickstart will probably work. If not, see INSTALL.md for detailed information.

Download and build from source. This requires autoconf, automake and libtool to be available, available usually through a system package manager. Steps:

$ git clone https://github.com/statsite/statsite.git
$ cd statsite
$ ./autogen.sh
$ ./configure
$ make
$ ./statsite

If you get any errors, you may need to check if all dependencies are installed, see INSTALL.md.

Building the test code may generate errors if libcheck is not available. To build the test code successfully, do the following:

$ cd deps/check-0.10.0/
$ ./configure
$ make
# make install
# ldconfig (necessary on some Linux distros)
$ cd ../../
$ make test

At this point, the test code should build successfully.

Docker

You can build your own image of docker using the Dockerfile

$ git clone https://github.com/statsite/statsite.git
$ cd statsite
$ docker build -t statsite/statsite:latest .
$ docker run statsite/statsite:latest

You can override the configuration via a mount that provide a statsite.conf

$ docker run -v /config/statsite:/etc/statsite statsite/statsite:latest

Or override the configuration with a different path by passing it in the CMD

$ docker run -v /config/statsite:/tmp statsite/statsite:latest -f /tmp/statsite.docker.example

See statsite.docker.conf for a starting point

Usage

Statsite is configured using a simple INI file. Here is an example configuration file:

[statsite]
port = 8125
udp_port = 8125
log_level = INFO
log_facility = local0
flush_interval = 10
timer_eps = 0.01
set_eps = 0.02
stream_cmd = python sinks/graphite.py localhost 2003 statsite

[histogram_api]
prefix=api
min=0
max=100
width=5

[histogram_default]
prefix=
min=0
max=200
width=20

Then run statsite, pointing it to that file::

statsite -f /etc/statsite.conf

A full list of configuration options is below.

Configuration Options

Each statsite configuration option is documented below. Statsite configuration options must exist in the statsite section of the INI file:

• tcp_port : Integer, sets the TCP port to listen on. Default 8125. 0 to disable.

• port: Same as above. For compatibility.

• udp_port : Integer, sets the UDP port. Default 8125. 0 to disable.

• udp_rcvbuf : Integer, sets the SO_RCVBUF socket buffer in bytes on the UDP port. Defaults to 0 which does not change the OS default setting.

• bind_address : The address to bind on. Defaults to 0.0.0.0

• parse_stdin: Enables parsing stdin as an input stream. Defaults to 0.

• log_level : The logging level that statsite should use. One of: DEBUG, INFO, WARN, ERROR, or CRITICAL. All logs go to syslog, and also stderr when not daemonizing. Default is DEBUG.

• log_facility : The syslog logging facility that statsite should use. One of: user, daemon, local0, local1, local2, local3, local4, local5, local6, local7. All logs go to syslog.

• flush_interval : How often the metrics should be flushed to the sink in seconds. Defaults to 10 seconds.

• timer_eps : The upper bound on error for timer estimates. Defaults to 1%. Decreasing this value causes more memory utilization per timer.

• set_eps : The upper bound on error for unique set estimates. Defaults to 2%. Decreasing this value causes more memory utilization per set.

• stream_cmd : This is the command that statsite invokes every flush_interval seconds to handle the metrics. It can be any executable. It should read inputs over stdin and exit with status code 0 on success.

• aligned_flush : If set, flushes will be aligned on flush_interval boundaries, eg. for a 15 second flush interval the flushes would be aligned to (0,15,30,45) boundaries of every minute. This means the first flush period might be shorter than the flush interval depending on the start time of statsite.

• input_counter : If set, statsite will count how many commands it received in the flush interval, and the count will be emitted under this name. For example if set to "numStats", then statsite will emit "counter.numStats" with the number of samples it has received.

• daemonize : Should statsite daemonize. Defaults to 0.

• pid_file : When daemonizing, where to put the pid file. Defaults to /var/run/statsite.pid

• binary_stream : Should data be streamed to the stream_cmd in binary form instead of ASCII form. Defaults to 0.

• use_type_prefix : Should prefixes with message type be added to the messages. Does not affect global_prefix. Defaults to 1.

• global_prefix : Prefix that will be added to all messages. Defaults to empty string.

• kv_prefix, gauges_prefix, counts_prefix, sets_prefix, timers_prefix : prefix for each message type. Defaults to respectively: "kv.", "gauges.", "counts.", "sets.", "timers.". Values will be ignored if use_type_prefix set to 0.

• extended_counters : If enabled, the counter output will be extended to include the rate. Defaults to false.

• legacy_extended_counters : If enabled, the meaning of the "count" generated metrics on the counters would be the number of metrics received. If false, it would be the sum of the values. This is done for backwards compatibility. Defaults to true.

• timers_include : Allows you to configure which timer metrics to include through a comma separated list of values. Supported values include count, mean, stdev, sum, sum_sq, lower, upper, rate, median and sample_rate. If this option is not specified then all values except median will be included by default. median will be included if quantiles include 0.5

• prefix_binary_stream : If enabled, the keys streamed to a the stream_cmd when using binary_stream mode are also prefixed. By default, this is false, and keys do not get the prefix.

• quantiles : A comma-separated list of quantiles to calculate for timers. Defaults to 0.5, 0.95, 0.99

In addition to global configurations, statsite supports histograms as well. Histograms are configured one per section, and the INI section must start with the word histogram. These are the recognized options:

• prefix : This is the key prefix to match on. The longest matching prefix is used. If the prefix is blank, it is the default for all keys.

• min : Floating value. The minimum bound on the histogram. Values below this go into a special bucket containing everything less than this value.

• max: Floating value. The maximum bound on the histogram. Values above this go into a special bucket containing everything more than this value.

• width : Floating value. The width of each bucket between the min and max.

Each histogram section must specify all options to be valid.

Protocol

By default, Statsite will listen for TCP and UDP connections. A message looks like the following (where the flag is optional)::

key:value|type[|@flag]

Messages must be terminated by newlines (\n).

Currently supported message types:

• kv - Simple Key/Value.
• g - Gauge, similar to kv but only the last value per key is retained
• ms - Timer.
• h - Alias for timer
• c - Counter.
• s - Unique Set

After the flush interval, the counters and timers of the same key are aggregated and this is sent to the store.

Gauges also support "delta" updates, which are supported by prefixing the value with either a + or a -. This implies you can't explicitly set a gauge to a negative number without first setting it to zero.

Multiple metrics may be batched together in one UDP packet a separated by a newline (\n) character. Care must be taken to keep UDP data size smaller than the network MTU minus 28 bytes for IP/UDP headers. Statsite supports a maximum UDP data length of 1500 bytes.

Examples:

The following is a simple key/value pair, in this case reporting how many queries we've seen in the last second on MySQL::

mysql.queries:1381|kv

The following is a timer, timing the response speed of an API call::

api.session_created:114|ms

The next example increments the "rewards" counter by 1::

rewards:1|c

Here we initialize a gauge and then modify its value::

inventory:100|g
inventory:-5|g
inventory:+2|g

Sets count the unique items, so if statsite gets::

users:abe|s
users:zoe|s
users:bob|s
users:abe|s

Then it will emit a count 3 for the number of uniques it has seen.

Writing Statsite Sinks

Statsite ships with graphite, librato, gmetric, and influxdb sinks, but ANY executable or script can be used as a sink. The sink should read its inputs from stdin, where each metric is in the form::

key|val|timestamp\n

Each metric is separated by a newline. The process should terminate with an exit code of 0 to indicate success.

Here is an example of the simplest possible Python sink:

#!/usr/bin/env python
import sys

lines = sys