Skip to content
Tutorials Center
My learning

Topics

Lesson 15 of 39 ยท Writing Data

Collecting Metrics with Telegraf

Learn Telegraf, the plugin-driven agent for InfluxDB: inputs, processors, aggregators, outputs, a minimal configuration, testing it and running it as a service.

Writing your own collector for CPU, memory, disks, Docker, MQTT sensors, Nginx and a hundred other sources would be a lot of repetitive work. Telegraf is InfluxData's open-source agent that already does it. It is a single binary driven by a configuration file with four kinds of plugins: inputs collect data, processors change it, aggregators summarise it and outputs write it, most often to InfluxDB.

This chapter's last lesson shows how Telegraf fits into the picture and how to configure it. Later chapters on integrations return to specific inputs (Docker, MQTT, SNMP and more).

Telegraf and InfluxDB are separate programs that cannot run on this site. The TOML configuration and commands below are read-only examples. The runnable blocks are JavaScript stand-ins for the agent's pipeline, so you can see how the plugin chain behaves.

The pipeline

flowchart LR
  I1["inputs.cpu"] --> P["processors<br/>(rename, tag, convert)"]
  I2["inputs.mem"] --> P
  I3["inputs.docker"] --> P
  P --> A["aggregators<br/>(mean, min, max)"]
  P --> O1["outputs.influxdb_v2"]
  A --> O1
  P --> O2["outputs.file"]

Telegraf gathers metrics every interval, passes them through optional plugins and sends them to every configured output.

Each metric that Telegraf produces already has the InfluxDB data model: a measurement name, tags, fields and a timestamp. That is why it fits so naturally.

A minimal configuration

Telegraf reads a TOML file. Generate a starting point with the program itself:

Terminal
telegraf config --section-filter agent:inputs:outputs \
  --input-filter cpu:mem:disk --output-filter influxdb_v2 > telegraf.conf

A small working file looks like this:

TOML
[agent]
  interval = "10s"            # how often inputs gather
  flush_interval = "10s"      # how often outputs write
  metric_batch_size = 1000    # points per write
  metric_buffer_limit = 10000 # points kept while the output is down
  round_interval = true
  omit_hostname = false       # adds the host tag

[[outputs.influxdb_v2]]
  urls = ["http://localhost:8086"]
  token = "${INFLUX_TOKEN}"   # environment variable substitution
  organization = "my-org"
  bucket = "metrics"

[[inputs.cpu]]
  percpu = true
  totalcpu = true
  collect_cpu_time = false

[[inputs.mem]]

[[inputs.disk]]
  ignore_fs = ["tmpfs", "devtmpfs", "overlay"]

Points to notice:

  • [[inputs.x]] with double brackets means "a list of plugin instances"; you may declare the same plugin several times with different options.
  • The agent adds a host tag to everything by default.
  • ${INFLUX_TOKEN} reads an environment variable; keep secrets out of the file.
  • For InfluxDB 3 you can still use the same output, because 3 accepts the 2.x write API, or use the dedicated outputs.influxdb_v3 where available in your Telegraf version.

Testing and running

Terminal
telegraf --config telegraf.conf --test           # gather once, print line protocol, write nothing
telegraf --config telegraf.conf --test --input-filter cpu
telegraf --config telegraf.conf                  # run for real
telegraf --config /etc/telegraf/telegraf.conf --config-directory /etc/telegraf/telegraf.d

--test is your best friend: it prints what would be written, for example cpu,cpu=cpu0,host=web-01 usage_user=3.2,usage_system=1.1,... 1772359200000000000. Check names, tags and units there before anything is stored. The packages install a service, so on Linux you manage it with systemctl enable --now telegraf.

Processors and aggregators

Processors adjust metrics in flight. Common ones:

Plugin Purpose
processors.rename Rename measurements, tags or fields
processors.override Set or replace tags
processors.converter Convert tags to fields or fields to other types
processors.regex Rewrite values with regular expressions
processors.dedup Drop unchanged repeated values
processors.starlark Custom logic in a Python-like language

Aggregators (aggregators.basicstats, aggregators.minmax, aggregators.final, aggregators.histogram) emit summaries over a period instead of every raw point.

TOML
[[processors.override]]
  [processors.override.tags]
    environment = "production"
    datacenter = "eu-west"

[[aggregators.basicstats]]
  period = "1m"
  drop_original = false
  stats = ["mean", "max"]

Stand-in: a tiny Telegraf pipeline

This block imitates the flow: two fake inputs produce metrics, a processor adds a tag and the output prints line protocol. It is a toy, but it makes the configuration concepts concrete.

JS Inputs, a processor and an output (stand-in)

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Stand-in: Telegraf-style stats aggregation

An aggregator turns many raw points into a few summary points. Here is the same idea as basicstats over one minute, with SQLite:

SQL A one-minute aggregator in SQL (SQLite stand-in)

Press Run (or Ctrl + Enter) to see the result here.

Operating Telegraf

  • One agent per host is the usual pattern; for devices that cannot run it, point a central Telegraf at them (SNMP, HTTP, MQTT).
  • Keep the interval consistent across inputs so graphs line up, and set a precision that matches it.
  • Watch buffer limits: if the output is down longer than metric_buffer_limit allows, the oldest metrics are dropped. Enable Telegraf's inputs.internal to chart its own health.
  • Use --config-directory to split a big config into one file per concern, and deploy it with configuration management.
  • Restrict the token to write access for one bucket (Buckets, Organizations and Tokens).

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which four kinds of plugins does Telegraf have?

    Inputs collect, processors change, aggregators summarise and outputs write.
  2. 2. What does telegraf --test do?

    It is a dry run that prints line protocol so you can check names, tags and units.
  3. 3. How should the InfluxDB token appear in telegraf.conf?

    Environment substitution keeps secrets out of configuration files.
  4. 4. What happens when the output is down longer than the buffer allows?

    metric_buffer_limit caps the memory used; beyond it the oldest metrics are discarded.

Summary

  • Telegraf is a plugin-based agent: inputs, processors, aggregators and outputs defined in a TOML file.
  • Its metrics already use the InfluxDB model, and outputs.influxdb_v2 (or a v3 output) writes them in batches.
  • Use --test before going live, environment variables for secrets and write-only tokens for the output.
  • Aggregators and processors shape data before it reaches the database, saving storage and cardinality.

Next: Flux Basics