docker.recipes

StatsD + Graphite

beginner

Simple daemon for stats aggregation with Graphite backend.

Overview

StatsD is a network daemon originally developed by Etsy that listens for statistics like counters, timers, and gauges sent over UDP and sends aggregates to one or more pluggable backend services. It was designed to solve the problem of application metrics collection without blocking application performance, using a fire-and-forget UDP protocol that allows applications to send metrics without waiting for acknowledgment. StatsD aggregates these metrics over configurable flush intervals before forwarding them to backend storage systems. This stack combines StatsD with Graphite, a highly scalable real-time graphing system that stores numeric time-series data and renders graphs on demand. Graphite consists of three components: Carbon (a daemon that listens for time-series data), Whisper (a database library for storing time-series data), and the Graphite web application for rendering graphs and dashboards. StatsD acts as a metrics aggregator that preprocesses and forwards data to Graphite's Carbon daemon, creating an efficient pipeline for collecting, aggregating, and visualizing application metrics. This combination is ideal for development teams and operations engineers who need lightweight metrics collection without the complexity of modern observability platforms. Unlike heavyweight solutions like Prometheus or DataDog, StatsD and Graphite provide a minimalist approach that's perfect for small to medium applications, development environments, or organizations just starting their metrics journey. The stack excels in scenarios where you need quick setup, low resource overhead, and straightforward time-series visualization without advanced features like alerting or distributed tracing.

Key Features

  • UDP-based metrics ingestion on port 8125 for zero-latency application instrumentation
  • Built-in metric aggregation with configurable flush intervals to reduce storage overhead
  • Support for counters, gauges, timers, histograms, and sets metric types
  • Whisper database with configurable retention policies and precision levels
  • Real-time graph rendering with PNG, SVG, and JSON output formats
  • Graphite's flexible metric naming hierarchy using dot notation
  • StatsD administrative interface on port 8126 for runtime statistics and debugging
  • Carbon line protocol support on port 2003 for direct Graphite ingestion

Common Use Cases

  • 1Application performance monitoring for web applications tracking response times and error rates
  • 2Infrastructure monitoring collecting system metrics like CPU, memory, and disk usage
  • 3Development environment metrics collection during testing and debugging phases
  • 4Small-scale production monitoring for startups without enterprise observability budgets
  • 5Custom business metrics tracking like user registrations, orders, or feature usage
  • 6Gaming applications monitoring player statistics, session durations, and in-game events
  • 7IoT device metrics aggregation for sensor data and device health monitoring

Prerequisites

  • Docker Engine 20.10+ and Docker Compose V2 for container orchestration
  • At least 512MB RAM available for Graphite's Carbon cache and Whisper database operations
  • Ports 80, 2003, 2004, 8125, and 8126 available on the host system
  • Basic understanding of time-series data concepts and metric naming conventions
  • Familiarity with UDP networking for troubleshooting StatsD metric ingestion
  • Knowledge of Graphite's retention policies to configure appropriate data storage periods

For development & testing. Review security settings, change default credentials, and test thoroughly before production use. See Terms

docker-compose.yml

docker-compose.yml
1services: 
2  graphite-statsd: 
3    image: graphiteapp/graphite-statsd:latest
4    container_name: graphite-statsd
5    restart: unless-stopped
6    volumes: 
7      - graphite_data:/opt/graphite/storage
8      - statsd_data:/opt/statsd
9    ports: 
10      - "80:80"
11      - "2003:2003"
12      - "2004:2004"
13      - "8125:8125/udp"
14      - "8126:8126"
15    networks: 
16      - statsd-network
17
18volumes: 
19  graphite_data: 
20  statsd_data: 
21
22networks: 
23  statsd-network: 
24    driver: bridge

.env Template

.env
1# StatsD + Graphite default configuration

Usage Notes

  1. 1Docs: https://graphite.readthedocs.io/
  2. 2Graphite dashboard at http://localhost:80 - time series visualization
  3. 3StatsD UDP on port 8125 - send counters/gauges/timers from apps
  4. 4StatsD admin TCP on port 8126 - debug and management
  5. 5Example: echo 'foo.bar:1|c' | nc -u -w0 localhost 8125
  6. 6Carbon on port 2003 for direct Graphite line protocol

Quick Start

terminal
1# 1. Create the compose file
2cat > docker-compose.yml << 'EOF'
3services:
4  graphite-statsd:
5    image: graphiteapp/graphite-statsd:latest
6    container_name: graphite-statsd
7    restart: unless-stopped
8    volumes:
9      - graphite_data:/opt/graphite/storage
10      - statsd_data:/opt/statsd
11    ports:
12      - "80:80"
13      - "2003:2003"
14      - "2004:2004"
15      - "8125:8125/udp"
16      - "8126:8126"
17    networks:
18      - statsd-network
19
20volumes:
21  graphite_data:
22  statsd_data:
23
24networks:
25  statsd-network:
26    driver: bridge
27EOF
28
29# 2. Create the .env file
30cat > .env << 'EOF'
31# StatsD + Graphite default configuration
32EOF
33
34# 3. Start the services
35docker compose up -d
36
37# 4. View logs
38docker compose logs -f

One-Liner

Run this command to download and set up the recipe in one step:

terminal
1curl -fsSL https://docker.recipes/api/recipes/statsd/run | bash

Troubleshooting

  • StatsD metrics not appearing in Graphite: Check UDP firewall rules and verify netcat test with 'echo "test.counter:1|c" | nc -u -w0 localhost 8125'
  • Graphite dashboard shows 'No data' for existing metrics: Verify time range selection matches your data retention policies in storage-schemas.conf
  • High memory usage by Carbon cache: Adjust MAX_CACHE_SIZE and MAX_UPDATES_PER_SECOND in carbon.conf to limit memory consumption
  • StatsD admin interface connection refused on port 8126: Ensure mgmt_address is set to 0.0.0.0 instead of localhost in StatsD config
  • Whisper files growing too large: Review storage-schemas.conf retention patterns and implement storage-aggregation.conf rules for older data
  • Missing metrics after container restart: Verify Docker volumes are properly mounted and Whisper database files persist in /opt/graphite/storage

Community Notes

Loading...
Loading notes...

Download Recipe Kit

Get all files in a ready-to-deploy package

Includes docker-compose.yml, .env template, README, and license

Components

statsdgraphite

Tags

#statsd#graphite#metrics#aggregation#simple

Category

Monitoring & Observability

Related Recipes

Ad Space