Write data with output plugins

Output plugins define where Telegraf delivers collected metrics. Send metrics to InfluxDB or to a variety of other datastores, services, and message queues, including Graphite, OpenTSDB, Datadog, Kafka, MQTT, and NSQ.

• Choose an output plugin
• Configure an output plugin
• How Telegraf writes metrics
• What happens when a write fails
• Send different metrics to different outputs
• Output plugins and data formats

Choose an output plugin

For the complete list, see output plugins in the plugin directory.

Configure an output plugin

Enable an output plugin by adding its table to your TOML configuration file. For example, the following configuration writes to InfluxDB 3:

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

You can configure multiple output plugins, and multiple instances of the same plugin. Each output receives every metric that passes its filters and delivers metrics independently of the other outputs. Output plugins also support common options such as alias, flush_interval, and metric_batch_size. See Common plugin options.

How Telegraf writes metrics

Each output plugin has its own buffer of metrics waiting to be written. Telegraf writes a batch of up to metric_batch_size metrics on every flush_interval, or sooner when a full batch accumulates. Batching amortizes connection and request overhead, so tune the batch size to what your destination handles efficiently.

What happens when a write fails

If a write fails, for example because the destination is unreachable, the metrics in the batch stay in the output’s buffer, and Telegraf retries them on the next flush. The buffer holds up to metric_buffer_limit metrics per output. If the buffer fills while the destination is down, Telegraf drops the oldest metrics to make room for new ones.

To ride out longer outages, you can raise the buffer limit or persist buffers to disk with the agent buffer_strategy setting. See Buffering and delivery.

Some output plugins can also report partial write results. When a destination accepts part of a batch and rejects individual metrics that can’t be written, for example because they can’t be serialized or they violate a service constraint, the plugin marks the written metrics as accepted, drops the rejected metrics, and keeps only the remainder in the buffer for retry.

If the destination is unavailable when Telegraf starts, the startup_error_behavior option controls whether Telegraf fails, ignores the plugin, or retries in the background while buffering metrics.

Send different metrics to different outputs

Output plugins apply metric filters before writing, so each output can receive a different subset of the pipeline’s metrics. For example, the following configuration writes only Kafka consumer metrics to one output and everything else to another:

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

[[outputs.file]]
  files = ["/var/log/telegraf/kafka-metrics.out"]
  namepass = ["kafka_*"]

Output plugins and data formats

Output plugins control where metrics go. Many output plugins also support data formats (serializers) that control how metrics are formatted before writing.

Configure a serializer using the data_format option in your output plugin:

[[outputs.http]]
  url = "http://example.com/metrics"
  data_format = "json"

Some output plugins (like influxdb_v3 or prometheus_client) use a fixed format and don’t support data_format. Others (like file, http, kafka) support multiple serializers.

The following guide shows how to choose and configure a serializer: