StatsD
Write StatsD lines (Etsy or DogStatsD with tags) and send them over UDP to a local agent, packed in datagrams under a size limit. Counters, gauges, timers, histograms, sets and distributions are checked before sending, and dry_run shows the datagrams. Typical uses: send queue depths or job durations each minute to the Datadog agent, Telegraf or the Prometheus statsd_exporter.
statsd format <json_metrics>
Description
Write StatsD lines (Etsy format), separated by line breaks
Write StatsD lines (Etsy format), separated by line breaks
Parameters
json_metrics: The metrics: a JSON array of {name, type, value, sample_rate, tags, delta, timestamp} (or one object), or StatsD lines already written - String - required
json_metrics: The metrics: a JSON array of {name, type, value, sample_rate, tags, delta, timestamp} (or one object), or StatsD lines already written - String - required
admin
statsd format "[{\"name\": \"orders.processed\", \"type\": \"counter\", \"value\": 3}, {\"name\": \"queue.size\", \"type\": \"gauge\", \"value\": 17}, {\"name\": \"import.duration\", \"type\": \"timer\", \"value\": 245.5}, {\"name\": \"visitors\", \"type\": \"set\", \"value\": \"user-42\"}]"
mentdb
orders.processed:3|c queue.size:17|g import.duration:245.5|ms visitors:user-42|s
A sampled counter, a negative gauge and a change of a gauge
admin
statsd format "[{\"name\": \"api.calls\", \"type\": \"counter\", \"value\": 1, \"sample_rate\": 0.1}, {\"name\": \"temperature\", \"type\": \"gauge\", \"value\": -4.5}, {\"name\": \"workers\", \"type\": \"gauge\", \"value\": -2, \"delta\": true}]"
mentdb
api.calls:1|c|@0.1 temperature:0|g temperature:-4.5|g workers:-2|g
Lines already written are checked
admin
statsd format "orders:3|c queue:17|g|@2"
mentdb
ERROR: Sorry, an error appears (the line 2 is not a StatsD line name:value|type[|@rate][|#tags]: queue:17|g|@2).
A name with a colon
admin
statsd format "[{\"name\": \"orders:paris\", \"type\": \"c\", \"value\": 1}]"
mentdb
ERROR: Sorry, an error appears (the name of the metric 0 holds a character that StatsD does not allow (: | @ # , a space or a control); sanitize true replaces them by _).
statsd format <json_metrics> <json_params>
Description
Write StatsD lines with parameters: flavor (etsy: the original StatsD format; dogstatsd: the Datadog format with tags), prefix (put before every name, ex: mentdb.), tags (common tags of every metric, dogstatsd only: {"env": "prod"} or ["env:prod"]), sanitize (false: true replaces the characters StatsD does not allow by _ instead of an error)
Write StatsD lines with parameters: flavor (etsy: the original StatsD format; dogstatsd: the Datadog format with tags), prefix (put before every name, ex: mentdb.), tags (common tags of every metric, dogstatsd only: {"env": "prod"} or ["env:prod"]), sanitize (false: true replaces the characters StatsD does not allow by _ instead of an error)
Parameters
json_metrics: The metrics: a JSON array of {name, type, value, sample_rate, tags, delta, timestamp} (or one object), or StatsD lines already written - String - required
json_params: The parameters - String - required
json_metrics: The metrics: a JSON array of {name, type, value, sample_rate, tags, delta, timestamp} (or one object), or StatsD lines already written - String - required
json_params: The parameters - String - required
admin
statsd format "[{\"name\": \"orders.processed\", \"type\": \"counter\", \"value\": 3, \"tags\": {\"shop\": \"Paris\"}}, {\"name\": \"payment.duration\", \"type\": \"distribution\", \"value\": 182.5}, {\"name\": \"queue.size\", \"type\": \"gauge\", \"value\": 17, \"timestamp\": \"2026-11-11T10:00:00Z\"}]" "{\"flavor\": \"dogstatsd\", \"prefix\": \"mentdb.\", \"tags\": [\"env:prod\"]}"
mentdb
mentdb.orders.processed:3|c|#shop:Paris,env:prod mentdb.payment.duration:182.5|d|#env:prod mentdb.queue.size:17|g|#env:prod|T1794391200
sanitize replaces the characters that are not allowed
admin
statsd format "[{\"name\": \"orders by shop\", \"type\": \"counter\", \"value\": 1, \"tags\": {\"shop\": \"Saint Denis\"}}]" "{\"flavor\": \"dogstatsd\", \"sanitize\": true}"
mentdb
orders_by_shop:1|c|#shop:Saint_Denis
statsd send <host> <port> <json_metrics>
Description
Send StatsD metrics over UDP. Result: {lines, packets, bytes, max_packet, sent, note}
Send StatsD metrics over UDP. Result: {lines, packets, bytes, max_packet, sent, note}
Parameters
host: The agent, often 127.0.0.1 - String - required
port: The UDP port, often 8125 - String - required
json_metrics: The metrics: a JSON array of {name, type, value, sample_rate, tags, delta, timestamp} (or one object), or StatsD lines already written - String - required
host: The agent, often 127.0.0.1 - String - required
port: The UDP port, often 8125 - String - required
json_metrics: The metrics: a JSON array of {name, type, value, sample_rate, tags, delta, timestamp} (or one object), or StatsD lines already written - String - required
admin
statsd send "127.0.0.1" "18125" "[{\"name\": \"orders.processed\", \"type\": \"counter\", \"value\": 3}, {\"name\": \"queue.size\", \"type\": \"gauge\", \"value\": 17}, {\"name\": \"import.duration\", \"type\": \"timer\", \"value\": 245.5}, {\"name\": \"visitors\", \"type\": \"set\", \"value\": \"user-42\"}]"
mentdb
{"lines": 4, "packets": 1, "bytes": 80, "max_packet": 1432, "sent": true, "note": "UDP has no acknowledgement: the delivery is not confirmed"}
statsd send <host> <port> <json_metrics> <json_params>
Description
Send StatsD metrics with parameters: flavor (etsy: the original StatsD format; dogstatsd: the Datadog format with tags), prefix (put before every name, ex: mentdb.), tags (common tags of every metric, dogstatsd only: {"env": "prod"} or ["env:prod"]), sanitize (false: true replaces the characters StatsD does not allow by _ instead of an error), max_packet (1432: the size of a datagram, 64 to 65000), timeout_ms (5000: the name resolution), dry_run (false: true sends nothing and gives the datagrams)
Send StatsD metrics with parameters: flavor (etsy: the original StatsD format; dogstatsd: the Datadog format with tags), prefix (put before every name, ex: mentdb.), tags (common tags of every metric, dogstatsd only: {"env": "prod"} or ["env:prod"]), sanitize (false: true replaces the characters StatsD does not allow by _ instead of an error), max_packet (1432: the size of a datagram, 64 to 65000), timeout_ms (5000: the name resolution), dry_run (false: true sends nothing and gives the datagrams)
Parameters
host: The agent - String - required
port: The UDP port - String - required
json_metrics: The metrics: a JSON array of {name, type, value, sample_rate, tags, delta, timestamp} (or one object), or StatsD lines already written - String - required
json_params: The parameters - String - required
host: The agent - String - required
port: The UDP port - String - required
json_metrics: The metrics: a JSON array of {name, type, value, sample_rate, tags, delta, timestamp} (or one object), or StatsD lines already written - String - required
json_params: The parameters - String - required
admin
statsd send "127.0.0.1" "18125" "[{\"name\": \"job.step1\", \"type\": \"counter\", \"value\": 1}, {\"name\": \"job.step2\", \"type\": \"counter\", \"value\": 2}, {\"name\": \"job.step3\", \"type\": \"counter\", \"value\": 3}, {\"name\": \"job.step4\", \"type\": \"counter\", \"value\": 4}, {\"name\": \"job.step5\", \"type\": \"counter\", \"value\": 5}, {\"name\": \"job.step6\", \"type\": \"counter\", \"value\": 6}, {\"name\": \"job.step7\", \"type\": \"counter\", \"value\": 7}, {\"name\": \"job.step8\", \"type\": \"counter\", \"value\": 8}, {\"name\": \"job.step9\", \"type\": \"counter\", \"value\": 9}, {\"name\": \"job.step10\", \"type\": \"counter\", \"value\": 10}, {\"name\": \"job.step11\", \"type\": \"counter\", \"value\": 11}, {\"name\": \"job.step12\", \"type\": \"counter\", \"value\": 12}, {\"name\": \"job.step13\", \"type\": \"counter\", \"value\": 13}, {\"name\": \"job.step14\", \"type\": \"counter\", \"value\": 14}, {\"name\": \"job.step15\", \"type\": \"counter\", \"value\": 15}, {\"name\": \"job.step16\", \"type\": \"counter\", \"value\": 16}, {\"name\": \"job.step17\", \"type\": \"counter\", \"value\": 17}, {\"name\": \"job.step18\", \"type\": \"counter\", \"value\": 18}, {\"name\": \"job.step19\", \"type\": \"counter\", \"value\": 19}, {\"name\": \"job.step20\", \"type\": \"counter\", \"value\": 20}, {\"name\": \"job.step21\", \"type\": \"counter\", \"value\": 21}, {\"name\": \"job.step22\", \"type\": \"counter\", \"value\": 22}, {\"name\": \"job.step23\", \"type\": \"counter\", \"value\": 23}, {\"name\": \"job.step24\", \"type\": \"counter\", \"value\": 24}, {\"name\": \"job.step25\", \"type\": \"counter\", \"value\": 25}, {\"name\": \"job.step26\", \"type\": \"counter\", \"value\": 26}, {\"name\": \"job.step27\", \"type\": \"counter\", \"value\": 27}, {\"name\": \"job.step28\", \"type\": \"counter\", \"value\": 28}, {\"name\": \"job.step29\", \"type\": \"counter\", \"value\": 29}, {\"name\": \"job.step30\", \"type\": \"counter\", \"value\": 30}, {\"name\": \"job.step31\", \"type\": \"counter\", \"value\": 31}, {\"name\": \"job.step32\", \"type\": \"counter\", \"value\": 32}, {\"name\": \"job.step33\", \"type\": \"counter\", \"value\": 33}, {\"name\": \"job.step34\", \"type\": \"counter\", \"value\": 34}, {\"name\": \"job.step35\", \"type\": \"counter\", \"value\": 35}, {\"name\": \"job.step36\", \"type\": \"counter\", \"value\": 36}, {\"name\": \"job.step37\", \"type\": \"counter\", \"value\": 37}, {\"name\": \"job.step38\", \"type\": \"counter\", \"value\": 38}, {\"name\": \"job.step39\", \"type\": \"counter\", \"value\": 39}, {\"name\": \"job.step40\", \"type\": \"counter\", \"value\": 40}]" "{\"max_packet\": 100, \"dry_run\": true}"
mentdb
{"lines": 40, "packets": 7, "bytes": 615, "max_packet": 100, "dry_run": true, "payloads": ["job.step1:1|c\ job.step2:2|c\ job.step3:3|c\ job.step4:4|c\ job.step5:5|c\ job.step6:6|c\ job.step7:7|c", "job.step8:8|c\ job.step9:9|c\ job.step10:10|c\ job.step11:11|c\ job.step12:12|c\ job.step13:13|c", "job.step14:14|c\ job.step15:15|c\ job.step16:16|c\ job.step17:17|c\ job.step18:18|c\ job.step19:19|c", "job.step20:20|c\ job.step21:21|c\ job.step22:22|c\ job.step23:23|c\ job.step24:24|c\ job.step25:25|c", "job.step26:26|c\ job.step27:27|c\ job.step28:28|c\ job.step29:29|c\ job.step30:30|c\ job.step31:31|c", "job.step32:32|c\ job.step33:33|c\ job.step34:34|c\ job.step35:35|c\ job.step36:36|c\ job.step37:37|c", "job.step38:38|c\ job.step39:39|c\ job.step40:40|c"]}
DogStatsD to the Datadog agent
admin
statsd send "127.0.0.1" "18125" "[{\"name\": \"orders.processed\", \"type\": \"counter\", \"value\": 3, \"tags\": {\"shop\": \"Paris\"}}]" "{\"flavor\": \"dogstatsd\", \"prefix\": \"mentdb.\", \"tags\": {\"env\": \"prod\"}}"
mentdb
{"lines": 1, "packets": 1, "bytes": 48, "max_packet": 1432, "sent": true, "note": "UDP has no acknowledgement: the delivery is not confirmed"}
A line longer than max_packet
admin
statsd send "127.0.0.1" "18125" "[{\"name\": \"nnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnn\", \"type\": \"counter\", \"value\": 1}]" "{\"max_packet\": 64}"
mentdb
ERROR: Sorry, an error appears (the line nnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnn... is longer than max_packet (64 bytes)).
Used in use cases (1 recipe)
System administrator & DevOps › Send the depth of the work queues to a StatsD or Datadog agent
System administrator & DevOps › Send the depth of the work queues to a StatsD or Datadog agent
