README
¶
dogstatsd-local
A local DogStatsD protocol inspector for debugging metrics, service checks, and events
[!TIP] Full documentation available here
dogstatsd-local
Features
- All DogStatsD message types — metrics (count, gauge, set, timer, histogram, distribution), service checks, events
- Multiple output formats — pretty, json, short, raw
- Metric forwarding — proxy datagrams to an upstream DogStatsD server while inspecting locally
- Catppuccin colors — pretty format adapts to your terminal's light/dark theme
Installation
Go
go install github.com/mroyme/dogstatsd-local/cmd/dogstatsd-local@latest
Docker
docker run -it -e "TERM=$TERM" -p 8125:8125/udp mroyme/dogstatsd-local
Prebuilt Binaries
Download from the releases page for Linux, macOS, and Windows (x86-64 and ARM64).
Quick Start
# Start listening on port 8125 (default)
dogstatsd-local
# Send a metric
printf "page.views:1|c|#env:dev" | nc -u -w1 localhost 8125
# Send a service check
printf "_sc|Redis connection|2|#env:dev|m:Timeout" | nc -u -w1 localhost 8125
# Send an event
printf "_e{21,21}:An exception occurred|Cannot parse CSV file|t:warning|#err_type:bad_file" | nc -u -w1 localhost 8125
Flags
| Flag | Default | Description |
|---|---|---|
-host |
0.0.0.0 |
Bind address |
-port |
8125 |
UDP listen port |
-out |
pretty |
Output format: pretty, json, short, raw |
-forward |
(disabled) | Forward datagrams to an upstream DogStatsD server |
-tags |
(empty) | Extra tags to append, comma-delimited |
-max-name-width |
50 |
Max name length for pretty format |
-max-value-width |
15 |
Max value length for pretty format |
-debug |
false |
Enable debug logging |
Output Formats
Pretty
Colorized, human-readable with Catppuccin-themed colors:
COUNT page | views 1.00 env:dev
CRIT Redis connection Timeout env:dev
WARN An exception occurred Cannot parse CSV file err_type:bad_file
JSON
Machine-readable, one JSON object per line. Pipe through jq for pretty printing:
{
"namespace": "page",
"name": "views",
"path": "page.views",
"value": 1,
"sample_rate": 1,
"tags": ["env:dev"]
}
Short
Compact human-readable:
metric:count|page.views|1.00 env:dev
service_check:Redis connection|CRIT|msg:Timeout env:dev
event:title|text|priority:normal|alert:info
Raw
Passthrough of the original datagram:
page.views:1|c|#env:dev
Forwarding
Run as a middleware between your app and the Datadog agent:
Application → dogstatsd-local (8126) → Datadog agent (8125)
dogstatsd-local -port 8126 -forward 127.0.0.1:8125
All datagrams are forwarded as-is — no modification, no data loss.
Documentation
Full documentation is available at mroyme.github.io/dogstatsd-local.
Acknowledgments
Started as a fork of jonmorehouse/dogstatsd-local, which was no longer receiving updates. Since then, this project has diverged significantly — adding service check and event support, multiple output formats, Catppuccin-themed colors, metric forwarding, and more.
Directories