An HTTP-to-Datadog bridge for clients to send stats.
Clients (whether web, iOS, Android, or other) frequently need instrumentation. Datadog serves as a great place to stick these kinds of metrics (counts, aggregates, stats), but it functions best with batched metrics; plus, we don't want to provide API keys to (untrusted) clients. Furthermore, most client-server applications already have some form of authentication, so it doesn't make sense to reinvent the wheel and let clients auth directly with Datadog.
Statsd-bridge is an extremely (EXTREMELY) simple HTTP/WS server that accepts
multiple kinds of Datadog metrics as well as tags and sends them up from the
server side via dd-agent. It provides no real logging or auth or anything
else; it's simply intended to be a passthrough run behind your API gateway so
that client metrics may be aggregated in one central location.
Statsd-bridge supports both bulk metrics via HTTP and streamed metrics via Websockets. It offers one HTTP endpoint:
POST /stats
Content-Type: application/json
Body:
{
count: [
['stat_name', amount],
...
],
gauge: [
['stat_name', value],
...
],
timing: [
['stat_name', milliseconds],
...
],
tags: [
'tag:value',
...
]
}
The only response is a 202 Accepted if the request was well-formatted.
Partial delivery is possible if not all metrics were processable. All fields
are optional. tags should be provided in the Datadog standard format
tag_name:tag_value; usual caveats regarding tag cardinality apply.
A request upgrading to Websockets should instead send metrics line-by-line in the format
operation stat_name value tag1 tag2 ...
Operation should be one of (count, gauge, timing). tags are optional.
All fields should be space separated (this was chosen because spaces are not
valid in stats, values, or tags). If successful, a '1' will be written back to
the client; if unsuccessful, nothing will be sent.
Statsd-bridge is built on iodine, a high-performance webserver for Ruby.
Refer to that project for additional options, but in general the most useful
commands are:
# Set up dependencies
> bundle install
# Run silently with auto-detected best settings on port 3000
> bundle exec iodine
# Run verbosely on port 9090 with 1 process
> bundle exec iodine -p 9090 -w 1 -v
# Set dd-agent host, port, and metrics namespace
> STATSD_HOST=localhost STATSD_PORT=18125 STATSD_NAME=my_stats bundle exec iodine