1 | # StatsD [![Build Status][travis-ci_status_img]][travis-ci_statsd] [![Join the chat at https://gitter.im/statsd/statsd](https://badges.gitter.im/statsd/statsd.svg)](https://gitter.im/statsd/statsd?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge)
|
2 |
|
3 | A network daemon that runs on the [Node.js][node] platform and
|
4 | listens for statistics, like counters and timers, sent over [UDP][udp] or
|
5 | [TCP][tcp] and sends aggregates to one or more pluggable backend services (e.g.,
|
6 | [Graphite][graphite]).
|
7 |
|
8 | ## Key Concepts
|
9 |
|
10 | * *buckets*
|
11 | Each stat is in its own "bucket". They are not predefined anywhere. Buckets
|
12 | can be named anything that will translate to Graphite (periods make folders,
|
13 | etc)
|
14 |
|
15 | * *values*
|
16 | Each stat will have a value. How it is interpreted depends on modifiers. In
|
17 | general values should be integers.
|
18 |
|
19 | * *flush*
|
20 | After the flush interval timeout (defined by `config.flushInterval`,
|
21 | default 10 seconds), stats are aggregated and sent to an upstream backend service.
|
22 |
|
23 |
|
24 | ## Installation and Configuration
|
25 |
|
26 | ### Docker
|
27 | Statsd supports docker in two ways:
|
28 | * The official docker image on [docker hub](https://hub.docker.com/r/statsd/statsd)
|
29 | * Building the image from the bundled [Dockerfile](./Dockerfile)
|
30 |
|
31 | ### Manual installation
|
32 | * Install Node.js (All [`Current` and `LTS` Node.js versions](https://nodejs.org/en/about/releases/) are supported.)
|
33 | * Clone the project
|
34 | * Create a config file from `exampleConfig.js` and put it somewhere
|
35 | * Start the Daemon:
|
36 | `node stats.js /path/to/config`
|
37 |
|
38 | ## Usage
|
39 | The basic line protocol expects metrics to be sent in the format:
|
40 |
|
41 | <metricname>:<value>|<type>
|
42 |
|
43 | So the simplest way to send in metrics from your command line if you have
|
44 | StatsD running with the default UDP server on localhost would be:
|
45 |
|
46 | echo "foo:1|c" | nc -u -w0 127.0.0.1 8125
|
47 |
|
48 | ## More Specific Topics
|
49 | * [Metric Types][docs_metric_types]
|
50 | * [Graphite Integration][docs_graphite]
|
51 | * [Supported Servers][docs_server]
|
52 | * [Supported Backends][docs_backend]
|
53 | * [Admin TCP Interface][docs_admin_interface]
|
54 | * [Server Interface][docs_server_interface]
|
55 | * [Backend Interface][docs_backend_interface]
|
56 | * [Metric Namespacing][docs_namespacing]
|
57 | * [Statsd Cluster Proxy][docs_cluster_proxy]
|
58 |
|
59 | ## Debugging
|
60 | There are additional config variables available for debugging:
|
61 |
|
62 | * `debug` - log exceptions and print out more diagnostic info
|
63 | * `dumpMessages` - print debug info on incoming messages
|
64 |
|
65 | For more information, check the `exampleConfig.js`.
|
66 |
|
67 |
|
68 | ## Tests
|
69 | A test framework has been added using node-unit and some custom code to start
|
70 | and manipulate statsd. Please add tests under test/ for any new features or bug
|
71 | fixes encountered. Testing a live server can be tricky, attempts were made to
|
72 | eliminate race conditions but it may be possible to encounter a stuck state. If
|
73 | doing dev work, a `killall statsd` will kill any stray test servers in the
|
74 | background (don't do this on a production machine!).
|
75 |
|
76 | Tests can be executed with `./run_tests.sh`.
|
77 |
|
78 | ## History
|
79 | statsd was originally written at ([Etsy][etsy]) and released with a [blog post][blog post]
|
80 | about how it works and why we created it.
|
81 |
|
82 | ## Inspiration
|
83 | StatsD was inspired (heavily) by the project (of the same name) at Flickr.
|
84 | Here's a post where Cal Henderson described it in depth:
|
85 | [Counting and timing][counting-timing]
|
86 | Cal re-released the code recently:
|
87 | [Perl StatsD][Flicker-StatsD]
|
88 |
|
89 |
|
90 |
|
91 | [graphite]: http://graphite.readthedocs.org/
|
92 | [etsy]: http://www.etsy.com
|
93 | [blog post]: http://codeascraft.etsy.com/2011/02/15/measure-anything-measure-everything/
|
94 | [node]: http://nodejs.org
|
95 | [nodemods]: http://nodejs.org/api/modules.html
|
96 | [counting-timing]: http://code.flickr.com/blog/2008/10/27/counting-timing/
|
97 | [Flicker-StatsD]: https://github.com/iamcal/Flickr-StatsD
|
98 | [udp]: http://en.wikipedia.org/wiki/User_Datagram_Protocol
|
99 | [tcp]: http://en.wikipedia.org/wiki/Transmission_Control_Protocol
|
100 | [docs_metric_types]: https://github.com/statsd/statsd/blob/master/docs/metric_types.md
|
101 | [docs_graphite]: https://github.com/statsd/statsd/blob/master/docs/graphite.md
|
102 | [docs_server]: https://github.com/statsd/statsd/blob/master/docs/server.md
|
103 | [docs_backend]: https://github.com/statsd/statsd/blob/master/docs/backend.md
|
104 | [docs_admin_interface]: https://github.com/statsd/statsd/blob/master/docs/admin_interface.md
|
105 | [docs_server_interface]: https://github.com/statsd/statsd/blob/master/docs/server_interface.md
|
106 | [docs_backend_interface]: https://github.com/statsd/statsd/blob/master/docs/backend_interface.md
|
107 | [docs_namespacing]: https://github.com/etsy/statsd/blob/master/docs/namespacing.md
|
108 | [docs_cluster_proxy]: https://github.com/etsy/statsd/blob/master/docs/cluster_proxy.md
|
109 | [travis-ci_status_img]: https://travis-ci.org/statsd/statsd.svg?branch=master
|
110 | [travis-ci_statsd]: https://travis-ci.org/statsd/statsd
|