README.md

StatsD client for Ruby apps

This is a ruby client for statsd (http://github.com/etsy/statsd). It provides a lightweight way to track and measure metrics in your application.

We call out to statsd by sending data over a UDP socket. UDP sockets are fast, but unreliable, there is no guarantee that your data will ever arrive at it's location. In other words, fire and forget. This is perfect for this use case because it means your code doesn't get bogged down trying to log statistics. We send data to statsd several times per request and haven't noticed a performance hit.

The fact that all of your stats data may not make it into statsd is no issue. Graphite (the graph database that statsd is built on) will only show you trends in your data. Internally it only keeps enough data to satisfy the levels of granularity we specify. As well as satisfying it's requirement as a fixed size database. We can throw as much data at it as we want it and it will do it's best to show us the trends over time and get rid of the fluff.

StatsD.increment

Lets you increment a key in statsd to keep a count of something. If the specified key doesn't exist it will create it for you.

# increments default to +1StatsD.increment('GoogleBase.insert')
# you can also specify how much to increment the key byStatsD.increment('GoogleBase.insert', 10)
# you can also specify a sample rate, so only 1/10 of events# actually get to statsd. Useful for very high volume dataStatsD.increment('GoogleBase.insert', 1, 0.1)

Again it's more common to use the metaprogramming methods.

Metaprogramming Methods

As mentioned, it's most common to use the provided metaprogramming methods. This lets you define all of your instrumentation in one file and not litter your code with instrumentation details. You should enable a class for instrumentation by extending it with the StatsD::Instrument class.

GoogleBase.extendStatsD::Instrument

Then use the methods provided below to instrument methods in your class.

statsd_count

This will increment the given key even if the method doesn't finish (ie. raises).

GoogleBase.statsd_count :insert, 'GoogleBase.insert'

Note how I used the 'GoogleBase.insert' key above when measuring this method, and I reused here when counting the method calls. StatsD automatically separates these two kinds of stats into namespaces so there won't be a key collision here.

statsd_count_if

This will only increment the given key if the method executes successfully.

GoogleBase.statsd_count_if :insert, 'GoogleBase.insert'

So now, if GoogleBase#insert raises an exception or returns false (ie. result == false), we won't increment the key. If you want to define what success means for a given method you can pass a block that takes the result of the method.

In the above example we will only increment the key in statsd if the result of the block returns true. So the method is returning a Net::HTTP response and we're checking the status code.

statsd_count_success

Similar to statsd_count_if, except this will increment one key in the case of success and another key in the case of failure.

GoogleBase.statsd_count_success :insert, 'GoogleBase.insert'

So if this method fails execution (raises or returns false) we'll increment the failure key ('GoogleBase.insert.failure'), otherwise we'll increment the success key ('GoogleBase.insert.success'). Notice that we're modifying the given key before sending it to statsd.

Instrumenting Class Methods

You can instrument class methods, just like instance methods, using the metaprogramming methods. You simply have to configure the instrumentation on the singleton class of the Class you want to instrument.