statsd

This is a simple statsd module for Play! Framework. It pulls in a configuration from conf/application.conf and provides a singleton object Statsd with methods for counter and timing calls to statsd.

Sample application

There is a barebones sample application in sample/sample-statsd/. To run it:

$ play build-module  # you can just hit enter at the prompt
$ cd sample/sample-statsd
$ play run

With current settings, it should give a warning about statsd not being configured. Add the properties described below to conf/application.conf to test it further.

Getting started

To install:

$ cd path/to/play/modules
$ git clone git@github.com:dyross/play-statsd.git
$ cd play-statsd
$ play build-module  # just hit enter at prompt (if there is an error about scala, enter "play install scala" and retry)
$ cd path/to/your/app
$ vi conf/application.conf  # and add following line...
module.statsd=${play.path}/modules/play-statsd

Configuration

The following are configuration flags that belong in conf/application.conf:

statsd.enabled: Should be true to use this module. Can be false for testing.
statsd.prefix: The prefix for all stats sent by this app. They will appear in a folder of the same name on graphite.
statsd.host: The hostname of the statsd server.
statsd.port: The port for the statsd server.

If there are any configuration problems (missing or unparseable settings), there will be a warning the first time the module is used but will not cause an error in your app.

Usage

To use this module, first add this import:

import play.modules.statsd.Statsd

Now you can call it like this:

Statsd.increment("my.stat")  // Increment my.stat by 1
Statsd.increment("my.bigger.stat", value = 100)  // Increment my.bigger.stat by 100
Statsd.increment("my.frequent.stat", samplingRate = 0.1)  // Increment my.frequent.stat 10% of the time
Statsd.timing("my.operation", 100)  // my.operation took 100 ms
Statsd.timing("my.frequent.operation", 10, 0.5)  // my operation took 50 ms. Send this stat 50% of the time
Statsd.time("my.operation.i.dont.want.to.time.myself") {
  // do some stuff...
} // This will get timed automatically.

Any errors will be logged, but will not cause the app to fail.