Skip to main content
Ben Nadel at cf.Objective() 2009 (Minneapolis, MN) with: Ryan Vikander and Kashif Khan and John Hiner
Ben Nadel at cf.Objective() 2009 (Minneapolis, MN) with: Ryan Vikander ( @rvikander ) Kashif Khan John Hiner

Adding DataDog / DogStatsD Support To My StatsDGateway ColdFusion Component

Published in Comments (2)

Two years ago, I published StatsDGateway - a StatsD library for ColdFusion. This is a flexible StatsD library that supported UDF (User Datagram Protocol) transports, in-memory transports, buffered transports, and whatever kind of custom transport you might need to create (such as a Standard Output transport). And, in two years, it's been running great. Recently, however, I wanted to learn more about DataDog's tagging extensions for StatsD. So, for the first time in two years, I've released an update for StatsDGateway, adding basic support for DataDog's DogStatsD extensions to the StatsD protocol.

View the StatsDGatway.cfc project on my GitHub account.

The basic StatsD datagram format looks like this:|type|@sample_rate

DataDog's StatsD platform will gladly consume these backward-compatible formats. However, it also accepts a tagging extension that adds a segment to the end of the datagram string:|type|@sample_rate|#tag1:value,tag2

This new "tags" segment is a comma-delimited list of tags that can be either stand-alone booleans or "key:value" pairs. Tags are a way to add dimensions to mentrics so that they can be isolated, aggregated, and compared in your DataDogHQ dashboards.

From the DataDog Documentation: We store one time series per host + metric + tag combination on our backend, thus we cannot support infinitely bounded tags. Please don't include endlessly growing tags in your metrics, like timestamps or user ids. Please limit each metric to 1000 tags.

I'm still trying to wrap my head around the true power of DataDog's tagging extension for StatsD; but, I suspect that it will completely change the way that I think about instrumenting my applications. For example, instead of creating an individual StatsD metric for each route in my blog, I can create a single request metric and then provide the route as a tag on that metric. For example:


Notice that I'm only defining one count metric name, "bennadel.request"; but, I'm providing a tag - "route" - which annotates the metric with the type of request being made by the user. Once this tagged metric starts flowing into DataDogHQ, I can then see a complete breakdown of the traffic coming into my site:

NOTE: I'm using slightly different naming in my actual code, so the following screenshot doesn't exactly line up with the previous explanation.


DataDog tagging extension for statsD supported by StatsDGateway ColdFusion component library for StatsD.  

As you can see, this one metric is now completely broken down in my DataDogHQ dashboard. I can see where the distribution of traffic is going. And, I can filter down to a single tag (not shown in the screenshot) if I want to see how the traffic to that route changes over time. And this is just for a "count". Imagine that this was a timing (histogram) metric - I could see which routes take the longest to render and where my site might benefit from better caching.

Are you beginning to see the possibilities here?

To take advantage of this DataDog StatsD extension, I've added a new client to my StatsDGateway library - DogStatsDClient.cfc. The DogStatsDClient ColdFusion component supports all of the core StatsD methods; plus, it adds the histogram() method and optional tagging arguments to each [relevant] metric method.

With the addition of tagging, most methods now allow for two optional arguments: rate (for sampling) and tags. As such, the method signatures in this client are a bit more flexible than in the core client:

Count Metrics

  • count( key, delta )
  • count( key, delta, rate )
  • count( key, delta, tags )
  • count( key, delta, rate, tags )
  • increment( key )
  • increment( key, delta )
  • increment( key, delta, rate )
  • increment( key, delta, tags )
  • increment( key, delta, rate, tags )
  • decrement( key )
  • decrement( key, delta )
  • decrement( key, delta, rate )
  • decrement( key, delta, tags )
  • decrement( key, delta, rate, tags )

Gauge Metrics

NOTE: DogStatsD does not support sampling on gauges. It will be ignored.

  • gauge( key, value )
  • gauge( key, value, tags )
  • incrementGauge( key, delta )
  • incrementGauge( key, delta, tags )
  • decrementGauge( key, delta )
  • decrementGauge( key, delta, tags )

Timing Metrics

NOTE: DogStatsD implements timings as histograms under the hood.

  • timing( key, duration )
  • timing( key, duration, rate )
  • timing( key, duration, tags )
  • timing( key, duration, rate, tags )

Histogram Metrics

  • histogram( key, value )
  • histogram( key, value, rate )
  • histogram( key, value, tags )
  • histogram( key, value, rate, tags )

Unique Sets Metrics

NOTE: DogStatsD does not support sampling on sets. It will be ignored.

  • unique( group, member )
  • unique( group, member, tags )

The StatsDGateway.cfc provides a special method for creating the DogStatsDClient: StatsDGateway.createDogStatsClient().

DataDog has several other platform-oriented extensions for the StatsD protocol which my library does not yet support. But, I intend to add those shortly. In the meantime, however, I'm going to be noodling on this tagging functionality and how I can squeeze as much value out of it as possible.

Reader Comments

I believe in love. I believe in compassion. I believe in human rights. I believe that we can afford to give more of these gifts to the world around us because it costs us nothing to be decent and kind and understanding. And, I want you to know that when you land on this site, you are accepted for who you are, no matter how you identify, what truths you live, or whatever kind of goofy shit makes you feel alive! Rock on with your bad self!
Ben Nadel