Get started with Telegraf

After you install Telegraf, use this guide to collect your first metrics:

1. Create a configuration file
2. Start Telegraf
3. Read the output
4. Write metrics to InfluxDB
5. Go deeper

Create a configuration file

Telegraf requires a configuration file that enables at least one input plugin to collect data and one output plugin to write data. This example collects CPU and memory metrics and writes them to standard output.

Use the telegraf config command to generate the configuration file:

telegraf --input-filter cpu:mem --output-filter file config > telegraf.conf

The generated file enables the following plugins:

• The cpu and mem input plugins, which collect CPU and memory usage from the local system.
• The file output plugin, which writes metrics to standard output by default.

For the configuration file structure and default file locations, see Telegraf configuration file.

For an overview of how to configure a plugin, watch the following video:

Start Telegraf

Start Telegraf and point it at the configuration file:

telegraf --config telegraf.conf

Telegraf prints startup information, including the loaded configuration file and plugins, and then prints metrics as it collects them.

If you installed Telegraf as a service, start it with your service manager instead. For example, on Linux systems with systemd:

sudo systemctl start telegraf

To try a configuration without starting the full pipeline, run Telegraf with the --test flag. Telegraf collects metrics once, prints them to standard output, and exits:

telegraf --config telegraf.conf --test

Read the output

By default, Telegraf writes metrics as InfluxDB line protocol:

cpu,cpu=cpu-total,host=myhost usage_idle=95.8,usage_user=2.1 1717000000000000000
mem,host=myhost used_percent=64.2 1717000000000000000

Each line is one metric with a measurement name (cpu, mem), tags that identify the source (cpu, host), fields that hold the measured values (usage_idle, used_percent), and a timestamp. To learn how Telegraf models data, see Telegraf metrics.

Write metrics to InfluxDB

To write metrics to InfluxDB instead of standard output, replace the [[outputs.file]] table in your configuration file with the influxdb_v3 output plugin:

[[outputs.influxdb_v3]]
  urls = ["http://localhost:8181"]
  token = "
AUTH_TOKEN
"
  database = "
DATABASE_NAME
"

Replace the following:

• AUTH_TOKEN: your InfluxDB authorization token
• DATABASE_NAME: the name of the database to write your data into

Then restart Telegraf to apply the change.

For other InfluxDB versions, use the influxdb (1.x) or influxdb_v2 (2.x and Cloud) output plugin.

Go deeper

• Learn the metric model and data pipeline in How Telegraf works.
• Explore agent settings, metric filtering, and more in Configure Telegraf.
• Browse the Plugin directory to collect from and write to your systems.
• Parse and serialize other formats with data formats.
• Managing a fleet of Telegraf agents? Use Telegraf Controller to centrally manage configurations and monitor agents.