Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Plugin for sending application metrics to statsd
Groovy Shell CSS Java Gosu JavaScript
branch: master

Merge pull request #7 from cdre/master

Oh I get it.  It's a Schrödinger joke.  Good one.
latest commit e7e576b103
@charliek authored

README.md

Build Status

Grails Statsd Plugin

This project allows for easy publication of metrics to StatsD from a grails application.

What is StatsD

StatsD is a NodeJS daemon that listens for messages on a UDP port. It parses the messages, extracts metrics data, and periodically flushes the data to graphite. While it is not that complex it allows for powerful visualization of metrics over time. For more information about StatsD see this blog post written by Etsy its creator.

Installation

For now you will need to make a local plugin, but eventually it should be as easy as:

grails install-plugin statsd

Out of the box, the plugin expects that StatsD is running on localhost:8125. You can modify this (as well as any other pool config options) by adding a stanza like this to your grails-app/conf/Config.groovy file:

grails {
    statsd {
        poolConfig {
            // apache pool specific tweaks here. 
            // See [the javadoc][genericobjectpool] for details.
        }
        port = 8125
        host = "localhost"
    }
}

The poolConfig section will let you tweak any of the setter values made available by Apache Commons GenericObjectPool.

Plugin Usage

StatsdService Bean

def statsdService

The statdService bean is the only service exposed by this plugin that you should need, and it contains the methods that are supported by the StatsD server. Currently this includes counters and timers.

Counters are used to count the number of times something happens and report on it. This is done through the increment and decrement methods within the service. These methods take the metric to count as the first parameter, an optional magnitude as a second parameter, and an optional sample rate as a third parameter.

def statsdService

statsdService.increment('this.happened')
statsdService.increment('this.happened twice', 2)
statsdService.increment('this.happened tres times', 3, 0.8)

statsdService.decrement('this.happened')
statsdService.decrement('this.happened twice', 2)
statsdService.decrement('this.happened tres times', 3, 0.8)

Timers are used to record how long something took. Generally you will probably want to use the closure method to call timers, but there is also functions to specify times directly if desired. Timers also take in a metric name, and can have a second sampling rate parameter.

def allBooks = service.withTimer('dbquery.books') {
    Books.list()
}

There is not very much code in the service so if you have questions please dig in.

Statsd Annotations

In addition to the service you can also use annotations to push out metrics.

The following are available as annotations:

AnnotationDescription
@StatsdCounterUsed to add to a counter when a method is called
@StatsdTimerUsed to add a timer to the method that is called
Something went wrong with that request. Please try again.