Serialize outgoing data

A serializer converts Telegraf metrics into the format your destination expects. Serializers are the output-side counterpart of parsers.

• Choose a serializer
• Serialize to InfluxDB line protocol
• Serialize to JSON
• Serialize to Prometheus format

Choose a serializer

Output plugins that write generic payloads, such as file, http, kafka, and mqtt, support the data_format option, which selects one of the output data formats.

Output plugins that write to a specific service, such as influxdb_v3 and prometheus_client, use a fixed format and don’t support data_format.

The examples below serialize the following metric:

cpu,cpu=cpu0,host=node1 usage_idle=92.4,usage_user=4.2 1709572232000000000

Serialize to InfluxDB line protocol

The influx serializer produces InfluxDB line protocol. This is the default format for most generic outputs, and the recommended format unless your destination requires another:

[[outputs.file]]
  files = ["stdout"]
  data_format = "influx"

Output:

cpu,cpu=cpu0,host=node1 usage_idle=92.4,usage_user=4.2 1709572232000000000

Line protocol serialization is direct, with a few limitations. Float fields that are NaN or Inf are skipped, and tags with an empty key or value are skipped.

Serialize to JSON

The json serializer converts each metric into a JSON document:

[[outputs.file]]
  files = ["stdout"]
  data_format = "json"

  ## Timestamp resolution: truncated to the nearest power of 10
  ## below the specified units.
  json_timestamp_units = "1s"

Output:

{
    "fields": {
        "usage_idle": 92.4,
        "usage_user": 4.2
    },
    "name": "cpu",
    "tags": {
        "cpu": "cpu0",
        "host": "node1"
    },
    "timestamp": 1709572232
}

When an output plugin sends multiple metrics at once, the serializer can use a batch form instead, with all metrics collected in a top-level metrics array. Whether batch form is used depends on the output plugin.

To reshape the JSON beyond the standard form, the serializer supports JSONata transformations through the json_transformation option. For examples, including flattening metrics and combining batched metrics, see the JSON output data format.

Serialize to Prometheus format

The prometheus serializer converts metrics into the Prometheus text exposition format:

[[outputs.file]]
  files = ["stdout"]
  use_batch_format = true
  data_format = "prometheus"

Output:

# HELP cpu_usage_idle Telegraf collected metric
# TYPE cpu_usage_idle gauge
cpu_usage_idle{cpu="cpu0",host="node1"} 92.4
# HELP cpu_usage_user Telegraf collected metric
# TYPE cpu_usage_user gauge
cpu_usage_user{cpu="cpu0",host="node1"} 4.2

The serializer maps Telegraf metrics to Prometheus conventions:

• Metric names join the measurement name and field key, for example cpu_usage_idle.
• Tags become labels.
• A metric is created for each integer, float, boolean, and unsigned field. Boolean values convert to 1.0 for true and 0.0 for false.
• String fields are ignored unless prometheus_string_as_label = true, which outputs them as labels.

Next steps

• For all serializers and their options, see output data formats.
• To understand how outputs batch and buffer metrics, see Write data with output plugins.