Graphite

Last reviewed Sep 13, 2026 · 836 words

Graphite's design is 18 years old and it shows: fixed-size Whisper files, one per metric, a Django web app for rendering, and a plaintext protocol so simple that echo "home.power.watts 214 $(date +%s)" | nc graphite 2003 is a complete client. That simplicity is the reason to still run it in 2026. If your metrics come from collectd, StatsD, a PLC, a script, or anything else that pushes a line over TCP, Graphite accepts it with zero configuration. If you are starting fresh and everything you monitor exposes an HTTP endpoint, Prometheus is the better default and this guide will not argue otherwise.

Push versus pull is the real fork in the road

Prometheus scrapes targets; the server reaches out and every source must be reachable and expose a page. Graphite listens; every source sends when it wants, from behind NAT, from a cron job that runs once a day, from a device that has no web server. A homelab with 20 Docker services on one host wants pull. A garage full of ESP32 sensors, a solar inverter script, and a game server that emits StatsD counters wants push. The monitoring category has both shapes, and most people end up choosing by what their sources can do rather than by which server has nicer features.

The one image that makes it painless

Bare-metal Graphite is three services plus a web server plus StatsD if you want counters. The official all-in-one container collapses that into one:

services:
  graphite:
    image: graphiteapp/graphite-statsd:latest
    ports:
      - "8080:80"        # web UI and render API
      - "2003:2003"      # carbon plaintext
      - "2004:2004"      # carbon pickle
      - "8125:8125/udp"  # statsd
    volumes:
      - ./graphite/conf:/opt/graphite/conf
      - ./graphite/storage:/opt/graphite/storage
    restart: unless-stopped

Send a metric to 2003, wait 60 seconds, and it renders at http://host:8080/render?target=home.power.watts&from=-1h. That render API is why Graphite outlived its own web UI: Grafana has a native Graphite datasource with a function editor, and nobody has used the built-in dashboard by choice in a decade. Plan on Grafana from day one and treat port 8080 as an API.

Retention is decided before the first metric arrives, and changing it hurts

Whisper allocates the entire file when a metric is first seen, based on storage-schemas.conf. The default in the image keeps 1-second points for a day, which is wrong for almost everyone and burns disk. Set the rule before sending data:

[default]
pattern = .*
retentions = 10s:6h,1m:7d,10m:5y

That is 10-second resolution for 6 hours, 1-minute for a week, 10-minute for 5 years, and about 3.3 MB per metric on disk. Change the schema later and existing files keep their old layout until you run whisper-resize.py on each of them, which people learn the hard way when a 40,000-file directory is suddenly the wrong size. The matching storage-aggregation.conf decides whether downsampling averages, sums or takes the max, and counters need sum or the weekly view silently reports one-tenth of reality.

Where the architecture runs out

One Whisper file per metric means one open file per write per interval. Past a few hundred thousand metrics, carbon-cache saturates a disk's IOPS, and the traditional fix is a second layer: carbon-relay for sharding, go-carbon as a faster daemon, carbonapi to fan out queries. All of that works and is documented, and none of it is fun. The modern shortcut is VictoriaMetrics, which accepts the Graphite plaintext protocol on port 2003 with a single flag, stores everything in a compressed columnar format at roughly a tenth of the disk, and answers Graphite-style queries. If you love the protocol and outgrew the storage, that is the migration, and it does not require touching a single collector.

Who still runs it on purpose

Shops with a decade of StatsD instrumentation in their applications. Homelabs where the sources are shell scripts and sensors rather than containers. Anyone who needs the render API's URL-addressable PNG graphs for embedding in a status page or a wiki. And people who want a metrics server they can fully understand in an afternoon, which is an underrated property when the thing pages you at 3 am. The uptime monitoring guide covers the alerting half that Graphite deliberately leaves to Grafana.

What I'd do

If a collector that only speaks plaintext or StatsD is the reason you are here, run the graphite-statsd image, fix storage-schemas.conf before the first write, and dashboard everything in Grafana. It will hold a homelab's worth of metrics for years on a few GB. If nothing forces push, or if you expect more than 100,000 series, skip Graphite and put VictoriaMetrics behind Grafana instead; it speaks Graphite's language and Prometheus's, and it will not need a second layer when you grow.