# StatsD + Graphite

> Simple daemon for stats aggregation with Graphite backend.

- Category: Monitoring & Observability
- Difficulty: beginner
- Components: statsd, graphite
- Tags: statsd, graphite, metrics, aggregation, simple
- Source: https://docker.recipes/monitoring/statsd

## 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.

## 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

## Use cases

- Application performance monitoring for web applications tracking response times and error rates
- Infrastructure monitoring collecting system metrics like CPU, memory, and disk usage
- Development environment metrics collection during testing and debugging phases
- Small-scale production monitoring for startups without enterprise observability budgets
- Custom business metrics tracking like user registrations, orders, or feature usage
- Gaming applications monitoring player statistics, session durations, and in-game events
- IoT 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

## docker-compose.yml

```yaml
services:
  graphite-statsd:
    image: graphiteapp/graphite-statsd:latest
    container_name: graphite-statsd
    restart: unless-stopped
    volumes:
      - graphite_data:/opt/graphite/storage
      - statsd_data:/opt/statsd
    ports:
      - "80:80"
      - "2003:2003"
      - "2004:2004"
      - "8125:8125/udp"
      - "8126:8126"
    networks:
      - statsd-network

volumes:
  graphite_data:
  statsd_data:

networks:
  statsd-network:
    driver: bridge
```

## .env

```bash
# StatsD + Graphite default configuration
```

## Usage notes

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

## 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

