Template output data format
Use the template output data format (serializer) to format and output Telegraf metrics using custom Go templates.
Sprig helper functions are also available for enhanced template functionality.
Configuration
[[outputs.file]]
## Files to write to, "stdout" is a specially handled file.
files = ["stdout", "/tmp/metrics.out"]
## Data format to output.
## Each data format has its own unique set of configuration options, read
## more about them here:
## https://github.com/influxdata/telegraf/blob/master/docs/DATA_FORMATS_OUTPUT.md
data_format = "template"
## Go template for formatting a single metric
template = '{{ .Tag "host" }} {{ .Field "available" }}'Configuration options
template: Go template string that defines the output format for a single metric. The template context (the “dot”) is a single metric object with methods to access tags and fields.
Template methods
Within the template, use the following methods to access metric data:
| Method | Description | Example |
|---|---|---|
.Name | Returns the metric name | {{ .Name }} |
.Tag "key" | Returns the value of the specified tag | {{ .Tag "host" }} |
.Field "key" | Returns the value of the specified field | {{ .Field "available" }} |
.Tags | Returns a map of all tags | {{ .Tags }} |
.Fields | Returns a map of all fields | {{ .Fields }} |
.Time | Returns the metric timestamp | {{ .Time }} |
Examples
Basic example
Output host and a field value:
[[outputs.file]]
files = ["stdout"]
data_format = "template"
template = '{{ .Tag "host" }}: {{ .Field "usage_idle" }}'Input metric:
cpu,host=server01 usage_idle=98.5,usage_user=1.2 1640000000000000000Output:
server01: 98.5Multiple fields example
Output multiple fields with formatting:
[[outputs.file]]
files = ["stdout"]
data_format = "template"
template = '{{ .Name }} on {{ .Tag "host" }}: idle={{ .Field "usage_idle" }}, user={{ .Field "usage_user" }}'Output:
cpu on server01: idle=98.5, user=1.2Batch mode
When an output plugin emits multiple metrics in a batch, the template repeats for each metric by default.
To define custom formatting for batches, use batch_template with use_batch_format = true.
In batch mode, the template context (the “dot”) is a slice of metrics instead of a single metric.
Batch configuration
[[outputs.file]]
files = ["stdout"]
data_format = "template"
## Enable batch mode (required for batch_template)
use_batch_format = true
## Template for formatting multiple metrics together
batch_template = '''
{{- range $index, $metric := . -}}
{{- if $index }}, {{ end -}}
{{ $metric.Name }}
{{- end -}}
'''Batch example with Sprig functions
Use Sprig functions for advanced batch formatting:
[[outputs.file]]
files = ["stdout"]
data_format = "template"
use_batch_format = true
batch_template = '''
{{- range $metric := . -}}
{{ $metric.Tag "host" }}: {{ range $metric.Fields | keys | initial -}}
{{ . }}={{ get $metric.Fields . }}, {{ end -}}
{{ $metric.Fields | keys | last }}={{ $metric.Fields | values | last }}
{{ end -}}
'''Sprig functions
The template serializer supports Sprig template functions for string manipulation, math operations, and data transformations.
Common Sprig functions:
| Function | Description | Example |
|---|---|---|
keys | Returns map keys | {{ .Fields | keys }} |
values | Returns map values | {{ .Fields | values }} |
get | Gets value by key | {{ get .Fields "cpu" }} |
initial | All but last element | {{ .Fields | keys | initial }} |
last | Last element | {{ .Fields | keys | last }} |
upper | Uppercase string | {{ .Name | upper }} |
lower | Lowercase string | {{ .Tag "host" | lower }} |
For the complete list of available functions, see the Sprig documentation.
Was this page helpful?
Thank you for your feedback!
Support and feedback
Thank you for being part of our community! We welcome and encourage your feedback and bug reports for Telegraf and this documentation. To find support, use the following resources:
Customers with an annual or support contract can contact InfluxData Support.