statsd / statsd

Daemon for easy but powerful stats aggregation

StatsD

A network daemon that runs on the Node.js platform and listens for statistics, like counters and timers, sent over UDP or TCP and sends aggregates to one or more pluggable backend services (e.g., Graphite).

Key Concepts

• buckets

  Each stat is in its own "bucket". They are not predefined anywhere. Buckets can be named anything that will translate to Graphite (periods make folders, etc)

• values

  Each stat will have a value. How it is interpreted depends on modifiers. In general values should be integers.

• flush

  After the flush interval timeout (defined by config.flushInterval, default 10 seconds), stats are aggregated and sent to an upstream backend service.

Installation and Configuration

Docker

StatsD supports docker in three ways:

• The official container image on GitHub Container Registry
• The official container image on DockerHub
• Building the image from the bundled Dockerfile

Manual installation

• Install Node.js (All Current and LTS Node.js versions are supported.)
• Clone the project
• Create a config file from exampleConfig.js and put it somewhere
• Start the Daemon: node stats.js /path/to/config

Usage

The basic line protocol expects metrics to be sent in the format:

<metricname>:<value>|<type>

So the simplest way to send in metrics from your command line if you have StatsD running with the default UDP server on localhost would be:

echo "foo:1|c" | nc -u -w0 127.0.0.1 8125

More Specific Topics

• Metric Types
• Graphite Integration
• Supported Servers
• Supported Backends
• Admin TCP Interface
• Server Interface
• Backend Interface
• Metric Namespacing
• StatsD Cluster Proxy

Debugging

There are additional config variables available for debugging:

• debug - log exceptions and print out more diagnostic info
• dumpMessages - print debug info on incoming messages

For more information, check the exampleConfig.js.

Tests

A test framework has been added using node-unit and some custom code to start and manipulate StatsD. Please add tests under test/ for any new features or bug fixes encountered. Testing a live server can be tricky, attempts were made to eliminate race conditions but it may be possible to encounter a stuck state. If doing dev work, a killall statsd will kill any stray test servers in the background (don't do this on a production machine!).

Tests can be executed with ./run_tests.sh.

History

StatsD was originally written at Etsy and released with a blog post about how it works and why we created it.

Inspiration

StatsD was inspired (heavily) by the project of the same name at Flickr. Here's a post where Cal Henderson described it in depth: Counting and timing. Cal re-released the code recently: Perl StatsD

statsd's Issues

Data doesn't seem to be graphing correctly...

I doubt this is relevant to the statsd daemon as much as carbon/graphite - but I figure there is a high concentration of users who are using this stack here, so I'd post it here to see if anyone is having the same problem.

I'm writing to several incrementers with statsd, and when i try to visualize/graph those incrementers, the graph is only showing a fraction of the amount of data I expect to see.

As an example, if I graph the integral values for a metric (named "processed") for the time period of today (midnight this am to midnight tonight, 8/17/11) the top value is currently about 225. However, if I grep the carbon updates.log file on my server, for today, there are around 4800 records saying carbon received updates for this value.

Am I missing something here? Should carbon be under-reporting this data so much? am I doing something wrong? I'm using the PHP statsd client, and calling statsd::increment('entries'); to increment the metric. Has anyone experienced this same problem?

Thanks!

Perl Etsy::StatsD

Small errors in POD :

diff --git a/perl/lib/Etsy/StatsD.pm b/perl/lib/Etsy/StatsD.pm
index 96433e3..b13390c 100644
--- a/perl/lib/Etsy/StatsD.pm
+++ b/perl/lib/Etsy/StatsD.pm
@@ -56,7 +56,7 @@ sub increment {
$self->update($stats, 1, $sample_rate);
}

-=item increment(STATS, SAMPLE_RATE)
+=item decrement(STATS, SAMPLE_RATE)

Decrement one of more stats counters.

@@ -67,7 +67,7 @@ sub decrement {
$self->update($stats, -1, $sample_rate);
}

-=item increment(STATS, DELTA, SAMPLE_RATE)
+=item update(STATS, DELTA, SAMPLE_RATE)

Link to the Graphite site in README?

There are several projects with that name, and it's not clear to someone who drops by which one you mean.

"reset to 0 on flush" behavior of counter is not clear

nothing about the word 'counter' suggests anything about automatic resetting to 0 on each flush.
This is very confusing for newcomers. When I hear the word "counter" I actually think of something like a gauge that keeps incrementing, like rx/tx packet counters. I think I'm not the only one

I suggest to rename the "counter" metric to "bucket"

configurable key patterns

in my architecture, I run statsd on each server, and they all send to a central graphite server, so it makes sense that each statsd prepands the hostname (in reverse) to the key.

I have made the key sent by statsd configurable.

this is available in my repo (omry/statsd), if you are interested I`ll create a pull request.

this is implemented by adding a few more configuration.
here is my example config.

/*

Required Variables:

  graphiteHost:     hostname or IP of Graphite server
  graphitePort:     port of Graphite server
  port:             StatsD listening port [default: 8125]

Optional Variables:

  debug:            debug flag [default: false]
  debugInterval:    interval to print debug information [ms, default: 10000]
  dumpMessages:     log all incoming messages
  flushInterval:    interval (in ms) to flush to Graphite
  percentThreshold: for time information, calculate the Nth percentile
                    [%, default: 90]
patterns:
  all patterns are optional (default values are reasonable).
  patterns may contain special variables which are replaced by actual data:
    ${hostname} : will be replaced by the reversed hostname, if the hostname is www.example.com, the ${hostname} variable will be replaced by com.example.www
    ${key}      : key provided by client library

  stats_pattern:        pattern used when creating user data keys, for example servers.${hostname}.${key}
  stats_timers_pattern: pattern used when creating timer keys, for example "servers.${hostname}.timers.${key}"
  statsd_pattern:       pattern used when creating keys used for statsd statistics, for example "servers.${hostname}.statsd.${key}"
  stats_count_pattern:  pattern used when creting keys used for stats counters, for example servers.${hostname}.stats_count.${key}

*/

{
  graphitePort          : 2003
, graphiteHost : "carbon"
, port : 8125
, stats_pattern         : "servers.${hostname}.${key}"
, stats_timers_pattern  : "servers.${hostname}.timers.${key}"
, statsd_pattern        : "servers.${hostname}.statsd.${key}"
, stats_count_pattern   : "servers.${hostname}.stats_count.${key}"
}

Add interface to delete unused metrics

If I write a gauge called: foo.bar.gauge, but stop using it, StatsD will continue to push the last known value into Graphite on every flush interval. I should be able to, through a simple interface, delete a metric from StatsD. This is the clean way to avoid having to restart StatsD in order to clear out the local memory.

telnet to 8126 doesn't seem to work

I have a statsd server running correctly but when I telnet and attempt to type "stats" my keystrokes are interleaved with error messages like so:

ERROR
taERROR
tERROR
sERROR
ERROR

repeater does not work on ipv4 interfaces

This was changed in this commit: 86bbcba

My infrastructure is all ipv4, so all of these packets fail to reach their intended destination.

I was thinking of some ways that this could be made configurable, but without changing the current configuration.

{
  ... other config
  "repeater": {
    "protocol": "ipv6",
    "hosts": [
      { "host": "", "port": 8125}
    ]
  }
}

Any complaints or comments before I submit a pull request?

add message to delete keys

Right now, removing a key requires restarting statsd. This is lame.

different counts, documentation?

So there are 3 different counts:

stats.mystat
stats.timers.mystat.count
stats_counts.mystat

What the difference between all of them? Quick look at the source code suggests the first two are "occurrences per second" and the latter is "occurrences per minute", but I'm not so well versed in Javascript or what Graphite expects to be sent.

Is that right? Can someone update the readme to explain the differences between different counts?

Thanks.

How do i start statsd on windows. am lost on the part of cloning and starting it

Hi guys am new to this statsd. how do i start it. please give me instructions

Bad line:1

When i run simple example(both latest version of node and statsd):

./statsd-client.sh 'my_metric:100|g'
13 Aug 20:24:26 - DEBUG: my_metric:100|g
13 Aug 20:24:26 - DEBUG:
13 Aug 20:24:26 - DEBUG: Bad line: 1

Anybody can explain this behavior?
Thanks.

Cluster gauges?

I'm looking for the best way to do gauges if my app is clustered.

I could either report a gauge per cluster node and aggregate using carbon or a graph, or I could add a statsd feature for cluster gauges where statsd would aggregate the values from all cluster nodes into a single value before reporting to graphite.

If anyone is doing either of these, can you please comment?

Thanks!

Gauges should be unset upon flush.

Currently, gauges will continue sending the last value on flush.

This is not ideal, because it may mask an error. Also, if the keep-last;value behavior is desired, graphite can provide it, with the keepLast() function.

process.compile should not be used.

Hey there, I followed the script for installed statsd here:

https://gist.github.com/987556 (I had to tweak a couple locations for graphite)

And when I get to the final step: "node stats.js local.js", I get this error:

23 May 15:30:07 - reading config file: local.js
(node) process.compile should not be used. Use require('vm').runInThisContext instead.

If it helps, "node -v" returns: "v0.5.0-pre"

in the #node.js irc room, Someone commented that the syntax simply needed to be changed, and referenced:

http://nodejs.org/docs/v0.4.8/api/vm.html#vm.runInThisContext

I simply don't know enough about node.js yet to get this working.... Hope that helps!

"timing" has nothing to do with timing

the metric type "timing" has a misleading choice of a name, because it doesn't have anything to do with timings per se (although timings may be a common, or even the most common use of it).

fundamentally, this metric takes multiple numbers in a short time interval, and calculates the avg/percentile/min/max. that's it.

let's try to devise a better name.
here's a suggestion: analyzer (or interval-analyzer but the fact that it operates on a time interval is fairly obvious as statsd is an aggregator, and can be explained in the metric type's documentation)

Perl client: lost connection

I have tried to use Etsy::StatsD, but I lose data. What I suspect is that when statsd is restarted, the connection is lost.

mean_90 and upper_90 unclear

It's unclear from the documentation what the meaning of the two metrics mean_90 and upper_90 are on timers.

The percentile threshold can be a single value, or a list of values, and will generate the following list of stats for each threshold:

stats.timers.$KEY.mean_$PCT
stats.timers.$KEY.upper_$PCT

Is this the mean of the upper 90th percentile? What is upper_90 and how does it differ from plain old upper? Where is the mean metric then?

Looking through the code also does not elucidate.

Improve documentation

The README is not very clear at the moment. There is too much going on in there. It takes too much time to find anything.

Here's what I would like to have in the README:

• brief description of what StatsD does
• link to further documentation
• how to install it
• brief usage overview
• how to submit bugs
• how to submit patches

Anything more complicated than that should be moved to documentation of some sorts. Either in form of a wiki or a separate documentation folder. Not 100% sure on that yet. Suggestions are highly welcome.

Support for optional metadata in the monitoring patterns

Add ability to append random monitoring metadata to the end of the pattern, i.e. gorets:1|c|some_monitoring_data=1,more_data=3

This does not have to be processed by StatsD, but can be just proxied to the backand.

disappearing counting stats

I'm seeing an interesting issue where I'll increment a stat, and it's value will be 0.1, (which I can verify with rawData=True from graphite) but then on the next flush, it's gone. It's almost as if the nodejs timer isn't quite precise enough and the timestamp is reused.

Installation location of statsd

This isn't an issue but rather a question on what you've found to work best:

• statsd installed locally so the webservers are doing local UDP calls to statsd, then statsd is doing remote TCP calls to graphite
• statsd installed locally with graphite so the webservers are doing remote UDP calls to statsd, then statsd is doing local TCP calls to graphite
• statsd installed on a separate server than both the webservers and the graphite server (remote UDP and remote TCP calls)

Thanks.

Documentation on building a debian package

I have no idea what I'm doing so it would be nice to see how to build statsd as a debian package.

Need to know which node.js version to target/maintain compatibility with

We're developing some patches and features for statsd and would like to know what version of node to target. The driver of this is consideration of using a syslog package which only works on 0.6.x or above.

What version of node.js is Etsy looking to develop for, or has concerns in maintaining compatibility for? We don't want to develop 0.6.x-only features if backwards compatibility to 0.5.x or even below is a concern. On the other hand, if 0.5.x isn't a concern than many new packages or features are at our disposal.

Are the majority of statsd users on 0.6.x or otherwise? We'd appreciate both Etsy and community feedback on this. Note that our fork has a package.json which specifies 0.6.1. An official package.json would programmatically solve this.

statsd cannot run on MacOSX

I installed node.js using homebrew .

$ brew info nodejs
node: stable 0.8.2, HEAD
http://nodejs.org/
/usr/local/Cellar/node/0.8.2 (79 files, 11M) *
https://github.com/mxcl/homebrew/commits/master/Library/Formula/node.rb

here is my config :

$ cat hello.js :
{
  graphitePort: 2003
, graphiteHost: "localhost"
, port: 8125
, debug: true 
}

but when I run :

$ node stats.js hello.js 

module.js:340
    throw err;
          ^
Error: Cannot find module './config'
    at Function.Module._resolveFilename (module.js:338:15)
    at Function.Module._load (module.js:280:25)
    at Module.require (module.js:362:17)
    at require (module.js:378:17)
    at Object.<anonymous> (/Users/hello/Developer/git/statsd/stats.js:4:14)
    at Module._compile (module.js:449:26)
    at Object.Module._extensions..js (module.js:467:10)
    at Module.load (module.js:356:32)
    at Function.Module._load (module.js:312:12)
    at Module.runMain (module.js:492:10)

I can work fine on my CentOS , anyone has any suggestion ?

What's the correct way to store bytes info?

Thanks for this project is a great tool,

I just developed this bundle for Symfony2/PHP
https://github.com/liuggio/StatsDClientBundle
when installed it automatically send some info on the production env.,
but I need to create graph about memory peak, so the question is
what's the correct way to store bytes info?

thanks.

config.js file watching broken on OSX

commit: 19814bd appears to break OSX . The API call appears incorrect. Could be down to the version of node.js I'm using, but fs.watch takes function( event, filename_) [filename_ not present in OSX incidentally] not function( curr, prev ) as fs.watchFile does.

This means I see the following errors:

/Users/ciaran/Documents/Development/statsd/lib/config.js:25
    if (curr.ino != prev.ino) { self.updateConfig(); }
                        ^
TypeError: Cannot read property 'ino' of null
    at FSWatcher.Configurator (/Users/ciaran/Documents/Development/statsd/lib/config.js:25:25)
    at FSWatcher.EventEmitter.emit (events.js:96:17)
    at FSEvent._handle.onchange (fs.js:826:12)

Now, I would provide a patch to fix it, but since the commit that introduces the changes gives no hints as to what was being fixed, I can't make sure that it remains fixed.

If I had to guess I'd say this is broken for everyone, but on Windows & Linux the second argument (filename) does actually exist so prev.ino resolves to undefined, rather than trying to find .ino on undefined as in my case (OSX)

Broken link in Wiki

In the wiki, the link to the ruby server is no longer https://github.com/fetep/ruby-statsd but https://github.com/fetep/ruby-statsdserver

Incorrect Graphite Schema in Readme

The schema specified in the Readme only applies to stats., not stats_count. or statsd.*. If using the schema provided in the Readme, graphite will just use the default 60s bucket and drop all of the stats but the last sent in the 60 seconds. The correct schema is:

[stats]
pattern = ^stats.*
retentions = 10:2160,60:10080,600:262974

separate flush_stats code from the backend

I think we should consider separating the flush_stats code from the backend into a different location. If there are going to be multiple backends, then there should only be one place that handles all of the metrics. This way there is less duplication of the code and it makes testing the actual metrics creation a bit easier. Also, these are really two different ideas, the graphite backend should be responsible for sending data to graphite and the console backend should be responsible for sending data to the console, but they should be sending the same data.

This allows makes it easier to change how the metrics are actual created and open's up the door for better testing both in tests and in a local(console) mode.

For example, if I want to add median to all timers, it would currently be hard to test this in a local mode and my tests would involve a graphite backend. If someone had a fork of statsd with a different backend, then they would also have to re-implement all of my code on their new backend.

License for StatsdClient.java

I've contributed some code on github: jalkanen/speed4j#19 and have used the StatsdClient.java file located in the examples directory. The maintainer of the project requires that all contributions are Apache License 2.0 compatible. I was wondering if I could slap on the Apache 2.0 license on the StatsdClient.java code? Thanks!

unit tests fail randomly

praj-mba:statsd-fork praj$ ./run_tests.sh 

graphite_tests
✔ send_well_formed_posts
✔ timers_are_valid
stderr: 
stderr: undefined:1
stderr: 
stderr: 
stderr: SyntaxError: Unexpected end of input
    at /Users/praj/src/statsd-fork/config.js:17:38
    at [object Object].<anonymous> (fs.js:115:5)
    at [object Object].emit (events.js:64:17)
    at afterRead (fs.js:1111:12)
    at Object.wrapper [as oncomplete] (fs.js:254:17)
node server unexpectedly quit with code: 1

FAILURES: Undone tests (or their setups/teardowns): 
- counts_are_valid

To fix this, make sure all tests call test.done()
praj-mba:statsd-fork praj$ ./run_tests.sh 

graphite_tests
✔ send_well_formed_posts
✔ timers_are_valid
✔ counts_are_valid

OK: 9 assertions (1778ms)

samplerate support all metrics, not just counters

our use case: tracking php memory usage means,percentile, etc of php pagerequests by using the timing metric. obviously this caused a whole lot of requests (thousands per second), making statsd memory usage go through the roof.

the README suggests samplerate is only accepted for counters. and statsd.js only has explicit code for samplerate support for counters.
I think this can be extended (note that sample client libs such as https://github.com/etsy/statsd/blob/master/examples/php-example.php have explicit support for sampling all metric types, although it's not fully implemented in statsd.js or even documented in the readme), so you can already send any metric sampled in your client.

here's what needs/can be done in statsd.js (in addition to updating the readme):

• timers: can easily be modified for correct samplerate support: only the "sum", "count" fields needs to be multiplied by 1/sampleRate. mean/upper/stddev/lower and their percentile-variants will stay correct (assuming decent sampling) (if #162 gets merged, the freqs also need to be multiplied by 1/sampleRate)
• gauge: no code needs a change, when statsd receives sampled gauge metrics, things will keep working just fine
• sets: multiply count by 1/sampleRate.

Running tests: Cannot find module 'temp'

Hello,

just deployed a fresh install of statsd on ubuntu and want to test it with the provided tests scripts.
After installing nodeunit, when I launch "./run_tests.sh", I get the following error stack:

module.js:340
throw err;
^
Error: Cannot find module 'temp'
at Function.Module._resolveFilename (module.js:338:15)
at Function.Module._load (module.js:280:25)
at Module.require (module.js:362:17)
at require (module.js:378:17)
at Object. (/opt/statsd/test/graphite_tests.js:3:20)
at Module._compile (module.js:449:26)
at Object.Module._extensions..js (module.js:467:10)
at Module.load (module.js:356:32)
at Function.Module._load (module.js:312:12)
at Module.require (module.js:362:17)

StatsD blows up when graphite goes away.

There is no error handling (other than a raise) when StatsD can't connect (TCP) to graphite.

Should be a trivial fix, just haven't gotten around to it yet

Missing data in timers with unnecessary precision

Just wanted to suggest something for the documentation: If you send millisecond values with decimal points, flush values may occaisionally contain NaN, which seems to cause gaps in all timing stats (except for .count). Maybe specify that those values must be integer (ms) to keep this problem from happening to others.

php: timing doesn't work in RU locale

when php use not EN locale (RU for example), simple casting float to string may looks like
13,434321
1212,00
12'212'000.33
and udp request send strings like this
12,2323|ms
and statsd can't correctly parse such strings

Clear gauges after flush...?

I realize that gauges were designed to be sticky: statsd continues to write the last known value for every flush interval. #62

Is there a reason why you'd want to do this from statsd instead of using Graphite's builtin "Keep Last Value" function? If you do it from statsd, then there is no way to differentiate between receiving no new data and getting the same value over and over. If you're worried about values not propagating to higher retention levels, you can always set the xFilesFactor in storage-aggregation.conf like so:

[stats_gauges]
pattern = ^stats\.gauges.*
xFilesFactor = 0

Personally I think I'm going to patch my local version of statsd to clear gauges after every flush... Thoughts?

Push metric name sanitization to backends

Opening this as a general RFC.

Currently the main StatsD daemon performs a set of regex replacements to sanitize metric names:

        var key = bits.shift()
                      .replace(/\s+/g, '_')
                      .replace(/\//g, '-')
                      .replace(/[^a-zA-Z_\-0-9\.]/g, '');

These regular expressions are largely based on the acceptable name formats that Graphite (being the only backend) was able to handle. Now that we have a pluggable backend system, I'm proposing that we make this task a function of each backend to handle as is appropriate for its acceptable metric name character set.

One advantage of pushing this down to the backend level would be that different backends could handle the special characters as optional control sequences. For example, in the case of the Librato backend we would like a way to specify a custom source parameter on a stat by stat basis. One thought would be to use a prefix character, like (/), to separate the source name from the metric name:

db1.acme.com/gorets:1c

The Librato backend would split the source out based on the (/) character, while backends like Graphite would simply turn that into a metric named "db1.acme.com.gorets", like it does today.

statsd opens and closes a lot of graphite connections in a loop upon startup

I'm running statsd and graphite/carbon on mac os x lion.

I configured statsd as follows:

{
graphitePort: 2003
, graphiteHost: "127.0.0.1"
, port: 8125
, flushInterval: 10
}

As soon as I turn statsd on, I see it opening and closing connections to graphite in a loop, without any activity being sent to graphite.

This makes my laptop fan whirr and keeps cpu usage up.

This is from the current git head on master, 11049a2

SyntaxError: Unexpected token : on running stats.js

config.js is just a copy of the exampleConfig.js

Command: node stats.js config.js

Output:
/code/statsd/config.js:55
, graphiteHost: "graphite.host.com"
^
SyntaxError: Unexpected token :
at Module._compile (module.js:437:25)
at Object.Module._extensions..js (module.js:467:10)
at Module.load (module.js:356:32)
at Function.Module._load (module.js:312:12)
at Module.require (module.js:362:17)
at require (module.js:378:17)
at Object. (/code/statsd/stats.js:4:14)
at Module._compile (module.js:449:26)
at Object.Module._extensions..js (module.js:467:10)
at Module.load (module.js:356:32)

Increase test coverage for main StatsD

So far we have integration tests for the main flush to graphite functionality. However we don't really have a good way to unit test single functionalities in the main stats.js file. This probably also means that we should split up some functionality like the TCP stats interface into proper modules.

Error starting statsd

When I try & start statsd, I get the following error:

https://gist.github.com/999180

I've recreated the problem on both OSX & Ubuntu, initially I thought it was just OSX related, but this morning I did a fresh install of nodejs, statsd & graphite on Ubuntu and get the same problem.

I tried asking on the nodejs IRC channel & didn't get anywhere, but I'm going to try again.

Raising this issue for visibility in case anyone else has the same problem as me.

Can't use the console backend?

I am trying to get a statsd instance running locally to try out, and I am having trouble getting the console backend to work. Here is my config file:

{
  port: 8125
, backends: ["console"]
, debug: true
}

I start statsd by running node stats.js path/to/config.js, and I see the following error:

/Users/jergason/code/statsd/stats.js:33
  var ret = backendmod.init(startup_time, config, backendEvents);
                       ^
TypeError: Object #<Object> has no method 'init'
    at loadBackend (/Users/jergason/itv/statsd/stats.js:33:24)
    at /Users/jergason/itv/statsd/stats.js:278:9
    at exports.configFile (/Users/jergason/itv/statsd/config.js:36:5)
    at EventEmitter.emit (events.js:88:17)
    at Configurator.updateConfig (/Users/jergason/itv/statsd/config.js:18:12)
    at fs.readFile (fs.js:176:14)
    at Object.oncomplete (fs.js:297:15)

It looks like the actual nodejs console module is being required, not the console backend. How do I get around this?

There should be real gauge support.

People running servers commonly have reason to be interested in gauge-type statistics like, oh, "bytes free on this hard disk". Instead of doing something like the coffee-pot hack (where the scale sends in the weight in grams as "timing" data in "milliseconds") and having statsd turn it into five series (80% of which will be extraneous), statsd should have explicit gauge support.

A command-line client?

I've submitted some stats from the command-line thusly:

echo "some.stat:`something_that_outputs_a_number`|g" | netcat -u -w1 statsd.example.com 8125

... but I can't quite figure out how to send the data without waiting one second (the -w1 to netcat).

And wouldn't it be obvious to have a command-line client for doing ad-hoc mintoring of large batch-jobs and the like? (I considered rolling a CLI into node-statsd-client, but that requires Node.js, which isn't quite common to have installed.)

E.g. some variation of:

statsd-client [--gauge|--timer|--counter] [hostname] [--port 8125] <metric_name> <value|->

The hostname and port could be taken from the environment and the type could possibly be rolled into the metric_name.

Not obvious that sampling for gauges and timers is client-side only

StatsD only deals with sampling data for counters but the README wasn't clear on this, so #138 has been raised to sort that out.

However, most (if not all) of the example clients "support" sampling for both gauges and timers too. For examples, see the Java, Ruby or Erlang clients. Each client applies the sampling internally and appends a |@...f field to the stat line, but that's then ignored by StatsD.

Do we need to find some way to make it obvious that should a client implement sampling for gauges and timers, then this is a client-side only feature, and has no effect once the data line reaches StatsD for processing, as it does for counters?

python_example is broken - incomplete class name change

The class name was changed from Statsd to StatsdClient but the references within the methods have not been updated to reflect this change.

class StatsdClient(object):
...

@staticmethod
def decrement(stats, sample_rate=1):
    """
    Decrements one or more stats counters
    >>> Statsd.decrement('some.int')
    """
    Statsd.update_stats(stats, -1, sample_rate)

Copying exampleConfig.js to config.js overwrites required files

From experience introducing several people to statsd, most people's first instinct is copy the exampleConfig.js file to config.js. However, the file config.js is used for some statsd config. This is confusing, since you can accidentally overwrite the config.js file when create your own config file.

Ideally, the existing config.js file would be renamed or moved so people won't overwrite it.

Error starting statsd

Hi,

I'm getting the following error

node stats.js config.js

23 May 20:08:59 - reading config file: dConfig.js
23 May 20:08:59 - server is up
23 May 20:08:59 - Loading backend: ./backends/graphite
23 May 20:09:09 - Counters:
{}
Timers:
{}
Gauges:
{}

/root/statsd/stats.js:44
backendEvents.once('flush', function clear_metrics(ts, metrics) {
^
TypeError: Object # has no method 'once'
at Timer.flushMetrics as callback
at node.js:773:9