Collect data with input plugins

Input plugins collect metrics from systems, services, and third-party APIs. Telegraf gathers metrics from every input you enable and configure in the configuration file and passes them down the data pipeline to your outputs.

• Choose an input plugin
• Configure an input plugin
• Polling and service inputs
• Test an input configuration

Choose an input plugin

Telegraf includes input plugins for operating system metrics, databases, message queues, network services, IoT sensors, and many other sources. For the complete list, see input plugins in the plugin directory.

If no plugin exists for your source, you can still collect the data:

• Run any program and collect its output with the exec or execd plugins.
• Read files with the file or tail plugins.
• Poll or listen for HTTP with the http or http_listener_v2 plugins.
• Run a program in any language as an external plugin.

Configure an input plugin

Enable an input plugin by adding its table to your TOML configuration file. Each plugin’s documentation lists its specific options. For example, the following configuration collects CPU metrics:

[[inputs.cpu]]
  ## Report metrics for each CPU in addition to the total.
  percpu = true
  totalcpu = true

All input plugins also support a set of common options, including a per-plugin interval, name_override, extra tags, and metric filters. You can define multiple instances of the same plugin with different options. See Common plugin options.

Polling and service inputs

Most input plugins poll. On each collection interval, Telegraf calls the plugin to gather current values, such as CPU usage or a database query result.

Service input plugins listen instead of polling. They run continuously and emit metrics as data arrives from sources such as message queues (kafka_consumer, mqtt_consumer), socket listeners, and webhooks. The collection interval doesn’t apply to service inputs.

Test an input configuration

Use the --test flag to gather metrics once, print them as line protocol, and exit:

telegraf --config telegraf.conf --test

Test mode runs inputs, processors, and aggregators, but not outputs, so nothing is written to your destinations.

Service inputs start in test mode, but Telegraf exits after the one-time gather before most service inputs receive any data. Use the --test-wait flag to keep Telegraf running long enough for pushed data to arrive:

telegraf --config telegraf.conf --test --test-wait 10

To run the complete pipeline once, including writing to outputs, use the --once flag instead. For more troubleshooting techniques, see Troubleshoot Telegraf.

Parse incoming data

Input plugins that read raw data, such as files, message queues, and HTTP responses, use a parser to convert that data into Telegraf metrics. The following guides show how to work with common incoming data: