Guide · Open source
How to use Telegraf: install, configure and send metrics
Updated · written with AI from the project's own documentation and checked against our catalogue data
Telegraf is an open-source agent written in Go that collects, processes, aggregates and writes metrics, logs and other arbitrary data. This guide explains how it works, how its TOML configuration is structured, and where to find the install steps and plugins you need. After reading it, you will understand the collect-and-write model well enough to set up your first configuration.
Telegrafinfluxdata/telegraf · ★ 17.9k · MIT Install options & downloads Quick start
- 1Get Telegraf. Follow the install guide for a binary, Docker image or package, or clone the repository with git.
- 2Pick your inputs. Choose the plugins that match your data sources, such as CPU, Memory or Modbus.
- 3Pick an output. Choose the output plugin for your destination, such as a time-series database.
- 4Write the TOML file. List your chosen inputs and outputs with their settings in a TOML configuration.
- 5Run the agent. Pass the configuration file to Telegraf so it collects and flushes data on its intervals.
- 6Check plugin READMEs. Read each plugin's README for configuration details and troubleshooting notes.
What Telegraf does and how it works
Telegraf runs as a background agent. It gathers data from sources such as system statistics, log files, message queues and industrial devices, then processes it and writes it to destinations such as databases.
Telegraf uses a plugin model. Input plugins collect data, and output plugins send it on. The README describes a suite of over 300 plugins.
- Inputs collect data at each collection interval.
- Outputs send data at each flush interval.
- Telegraf needs a destination; it is a collector, not a dashboard.
Install Telegraf
The README points to the install guide for binary builds, Docker images, RPM and DEB packages, and other builds. It also lists a git clone of the repository. The README describes Telegraf as compiling into a standalone static binary without external dependencies.
For full installation options, read the install guide at docs/INSTALL_GUIDE.md in the repository.
- Binary builds, Docker images, RPM and DEB packages are covered in the install guide.
- The source is available by cloning the repository.
git clone https://github.com/influxdata/telegrafWrite a TOML configuration file
Telegraf is configured with a TOML file. You list the plugins and settings you want to use, then pass that file to Telegraf. The README describes TOML as providing an unambiguous setup experience.
The configuration reference is in docs/CONFIGURATION.md, and each plugin has its own README under the plugins directory with details on configuring and troubleshooting it.
- Define each input plugin you want to collect from.
- Define the output plugin that will receive the data.
- Check each plugin's README for its specific settings.
Run Telegraf with your configuration
Pass your TOML configuration to the Telegraf binary. The agent then collects data from inputs at each interval and sends it to outputs at each flush interval.
For a basic walkthrough, follow the quick start document at docs/QUICK_START.md.
- Use the quick start guide for a first working run.
- Use the FAQ at docs/FAQ.md for common questions.
Choose plugins for your data sources
Plugins cover devices (OPC UA, Modbus), logs (File, Tail, Directory Monitor), messaging (AMQP, Kafka, MQTT), monitoring (OpenTelemetry, Prometheus), networking (Cisco TelemetryMDT, gNMI), system monitoring (CPU, Memory, Disk, Network, SMART, Docker, Nvidia SMI), and universal sources (Exec, HTTP, HTTP Listener, SNMP, SQL).
Windows users have Event Log, Management Instrumentation and Performance Counters plugins.
- If a plugin you need is not in the set, the README implies you would need to write code.
- The README notes user-defined code can be integrated.
What people use it for
- Monitoring CPU, memory, disk and network on servers using system plugins.
- Collecting data from industrial devices over OPC UA or Modbus.
- Tailing log files and sending them into a metrics store.
- Consuming messages from Kafka, AMQP or MQTT and writing them to a database.
- Scraping Prometheus endpoints or collecting SNMP data from network equipment.
Frequently asked questions
Is Telegraf free?
Telegraf is released under the MIT licence, as stated in the README. The licence file is at LICENSE in the repository.
What are the requirements to install Telegraf?
The README lists no prerequisites and describes Telegraf as a standalone static binary without external dependencies. Check the install guide for the build that suits your system.
How do I install Telegraf?
The README points to the install guide for binaries, Docker images, RPM and DEB packages. You can also clone the repository with git clone https://github.com/influxdata/telegraf.
How is Telegraf configured?
You configure Telegraf by editing a TOML file that lists the plugins and settings to use. Then you pass that file to Telegraf when you run it.
What are alternatives to Telegraf?
Comparable projects named in the analysis are Prometheus, Fluent Bit, Vector and Logstash. Each has different strengths, so compare them against your data sources and destinations.
Does Telegraf need a database to work?
Yes. Telegraf is a collector that writes data to destinations such as databases, so you need an output to send data to. It is not a hosted dashboard.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Telegraf suits engineers who want one agent to collect many kinds of data, including system stats, logs, message queues and industrial devices, and send it to a time-series store. It is a poor fit for people who want a hosted dashboard with no setup, or for non-technical users who do not want to edit TOML files. If you need a plugin that is not in the 300+ set, expect to write code.
Install options & downloads