Dogstatsd Local

A local implementation of the dogstatsd protocol from Datadog

Up-to-date fork of jonmorehouse/dogstatsd-local

Why?

Datadog is great for production application metric aggregation. This project was inspired by the need to inspect and debug metrics before sending them to datadog.

dogstatsd-local is a small program which understands the dogstatsd and statsd protocols. It listens on a local UDP server and writes metrics, events and service checks per the dogstatsd protocol to stdout in user configurable formats.

This can be helpful for debugging metrics themselves, and to prevent polluting datadog with noisy metrics from a development environment. dogstatsd-local can also be used to pipe metrics as json to other processes for further processing.

Usage

Install with Go

$ go install github.com/mroyme/dogstatsd-local/cmd/dogstatsd-local@latest

Build Manually

Run the following command in the source directory.

$ go build -o bin/dogstatsd-local ./cmd/dogstatsd-local/main.go

Once compiled, the dogstatsd-local binary can be run directly:

$ ./bin/dogstatsd-local -port=8126

Prebuilt Binaries

Pre-built binaries for Linux, Mac and Windows are available for x86-64 and AArch64. Check out the releases page.

Docker

$ docker run -it -e "TERM=$TERM" -p 8125:8125/udp mroyme/dogstatsd-local

Sample Formats

Pretty

'Pretty' is the default format. When writing a metric such as:

$ printf "namespace.metric:1|c|#test" | nc -cu  localhost 8125

Running dogstatsd-local with the -out raw flag will output the plain udp packet:

$ docker run -it -e "TERM=$TERM" -p 8125:8125/udp mroyme/dogstatsd-local -out pretty
COUNTER    namespace | metric                                1.00            test

The output will be colored if your shell supports colors. If colors aren't displayed properly, ensure that TERM is set correctly in your environment.

Pretty supports the following extra flags:

• -max-name-width (integer): Maximum length of name. Change if name is truncated (default 50)
• -max-value-width (integer): Maximum length of value. Change if value is truncated (default 50)

Raw (no formatting)

When writing a metric such as:

$ printf "namespace.metric:1|c|#test" | nc -cu  localhost 8125

Running dogstatsd-local with the -out raw flag will output the plain udp packet:

$ docker run -it -e "TERM=$TERM" -p 8125:8125/udp mroyme/dogstatsd-local -out raw
2017/12/03 23:11:31 namespace.metric.name:1|c|@1.00|#tag1

Short

When writing a metric such as:

$ printf "namespace.metric:1|c|#test" | nc -cu  localhost 8125

Running dogstatsd-local with the -out short flag will output a short, albeit still human-readable metric:

$ docker run -it -e "TERM=$TERM" -p 8125:8125/udp mroyme/dogstatsd-local -out short
metric:counter|namespace.metric|1.00  test

JSON

When writing a metric such as:

$ printf "namespace.metric:1|c|#test|extra" | nc -cu  localhost 8125

Running dogstatsd-local with the -out json flag will output json:

$ docker run -it -e "TERM=$TERM" -p 8125:8125/udp mroyme/dogstatsd-local -out json | jq .
{"namespace":"namespace","name":"metric","path":"namespace.metric","value":1,"extras":["extra"],"sample_rate":1,"tags":["test"]}

dogstatsd-local can be piped to any process that understands json via stdin. For example, to pretty print JSON with jq:

$ docker run -it -e "TERM=$TERM" -p 8125:8125/udp mroyme/dogstatsd-local -out json | jq .
{
  "namespace": "namespace",
  "name": "metric",
  "path": "namespace.metric",
  "value": 1,
  "extras": [
    "extra"
  ],
  "sample_rate": 1,
  "tags": [
    "test"
  ]
}

TODO

• support datadog service checks
• support datadog events
• support interval aggregation of percentiles