Telegraf

Last reviewed Aug 26, 2026 · 812 words

If your metrics end up in InfluxDB, run Telegraf; the two were built together and nothing else feeds it as naturally. If they end up in Prometheus, you probably want the exporters Prometheus was built around instead, and Telegraf is the exception you reach for when a single agent has to speak to several backends at once or scrape something no exporter covers. That is the whole decision in two sentences. The rest is about not letting a 300-plugin agent turn into a 3,000-line config file.

Why one agent instead of a dozen exporters

Telegraf's model is inputs, processors, aggregators and outputs, all declared in one TOML file, all compiled into one static Go binary that idles at around 64 MB. The input catalogue is the reason people keep it: CPU, memory, disk and network on the host, the Docker socket for per-container stats, SNMP for switches and UPSes, MQTT for sensors, PostgreSQL and MySQL internals, Nginx and Caddy status endpoints, ping, HTTP response checks, a exec plugin that runs any script and parses its output, and hundreds more. The Datadog agent is the closest proprietary comparison, and Telegraf covers most of that surface for free.

On the output side it writes to InfluxDB v1, v2 and v3, exposes a Prometheus scrape endpoint with outputs.prometheus_client, and can push to Kafka, MQTT, Graphite, OpenTelemetry, a file, or a plain HTTP endpoint. That fan-out is where it earns its place on a mixed stack: one agent on the host, metrics arriving in both InfluxDB for long retention and Prometheus for alerting, no duplicate collection.

A config that does something useful in 20 lines

[agent]
  interval = "15s"
  flush_interval = "15s"

[[inputs.cpu]]
  percpu = false
  totalcpu = true
[[inputs.mem]]
[[inputs.disk]]
  ignore_fs = ["tmpfs", "devtmpfs", "overlay", "squashfs"]
[[inputs.net]]
[[inputs.docker]]
  endpoint = "unix:///var/run/docker.sock"

[[outputs.influxdb_v2]]
  urls = ["http://influxdb:8086"]
  token = "$INFLUX_TOKEN"
  organization = "home"
  bucket = "telegraf"

Install from InfluxData's apt or yum repository, or use the telegraf Docker image with this file mounted at /etc/telegraf/telegraf.conf and the Docker socket mounted for the container input. Before starting it as a service, telegraf --test --config telegraf.conf runs every input once and prints the metrics it would send, which catches a typo in 2 seconds instead of after an hour of empty dashboards. Environment variables in the config are expanded, so secrets stay out of the file.

A 15-second interval is a sensible default for a homelab. At 10 hosts that is a few hundred series and trivial storage. Every plugin you add multiplies it, so add the Docker input knowing each container contributes dozens of fields.

The verbosity trap and how to avoid it

The catalogue's con is "configuration can get verbose", and the mechanism is that telegraf config generates a sample file with every plugin commented out, around 10,000 lines, and people start from it. Do not. Start from an empty file and add the blocks you need. Then split the file: Telegraf reads every .conf in /etc/telegraf/telegraf.d/, so inputs-host.conf, inputs-docker.conf and outputs.conf stay readable and can be dropped in per host with Ansible. Tag everything at the agent level with [global_tags] (host, site, role) so dashboards can filter without per-plugin repetition.

The other common mistake is collecting a metric because a plugin exists. SNMP against a managed switch can return thousands of OIDs per poll; pick the interfaces you care about. The point of an agent with 300 inputs is that you can use 8 of them.

Where it fits next to Grafana and the exporters

Telegraf has no UI and no storage. It is the collector; Grafana is the screen, and the Grafana versus Prometheus explainer covers why that split exists. For a pure Prometheus shop, node-exporter is lighter, needs zero config and is what every community dashboard expects, so use it for hosts and bring in Telegraf only for the things it covers uniquely, typically SNMP, MQTT sensors and scripted checks. If you are choosing the stack from scratch for a homelab and want long retention with the least configuration, Telegraf into InfluxDB into Grafana is the shortest path, and the monitoring category lays out the alternatives.

What I'd do

One Telegraf per host, Docker image or apt package, config split across telegraf.d/ with global tags, the five host inputs plus Docker, writing to InfluxDB v2 with a 90-day bucket. Add outputs.prometheus_client the day Prometheus alerting becomes worth it, and leave node-exporter to the hosts that never need anything beyond CPU and disk. Run --test before every restart. Kept small, it is the least dramatic piece of software on the network, which for an agent is the highest praise there is.