NATS Output Plugin
This plugin writes metrics to subjects of a set of NATS instances in one of the supported data formats.
Introduced in: Telegraf v1.1.0 Tags: messaging OS support: all
Global configuration options
In addition to the plugin-specific configuration settings, plugins support additional global and plugin configuration settings. These settings are used to modify metrics, tags, and field or create aliases and configure ordering, etc. See the CONFIGURATION.md for more details.
Secret-store support
This plugin supports secrets from secret-stores for the username
and
password
option.
See the secret-store documentation for more details on how
to use them.
Configuration
# Send telegraf measurements to NATS
[[outputs.nats]]
## URLs of NATS servers
servers = ["nats://localhost:4222"]
## Optional client name
# name = ""
## Optional credentials
# username = ""
# password = ""
## Optional NATS 2.0 and NATS NGS compatible user credentials
# credentials = "/etc/telegraf/nats.creds"
## NATS subject for producer messages.
## This field can be a static string or a Go template, see README for details.
## Incompatible with `use_batch_format
subject = "telegraf"
## Use Transport Layer Security
# secure = false
## Optional TLS Config
# tls_ca = "/etc/telegraf/ca.pem"
# tls_cert = "/etc/telegraf/cert.pem"
# tls_key = "/etc/telegraf/key.pem"
## Use TLS but skip chain & host verification
# insecure_skip_verify = false
## Use batch serialization instead of per metric. The batch format allows for the
## production of batch output formats and may more efficiently encode and write metrics.
# use_batch_format = false
## 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 = "influx"
## Jetstream specific configuration. If not nil, it will assume Jetstream context.
## Since this is a table, it should be present at the end of the plugin section. Else you can use inline table format.
# [outputs.nats.jetstream]
## Name of the stream, required when using jetstream.
# name = ""
## List of subjects to register on the stream
# subjects = []
## Use asynchronous publishing for higher throughput, but note that it does not guarantee order within batches.
# async_publish = false
## Timeout for wating on acknowledgement on asynchronous publishing
## String with valid units "ns", "us" (or "µs"), "ms", "s", "m", "h".
# async_ack_timeout = "5s"
## Full jetstream create stream config, refer: https://docs.nats.io/nats-concepts/jetstream/streams
# retention = "limits"
# max_consumers = -1
# max_msgs_per_subject = -1
# max_msgs = -1
# max_bytes = -1
# max_age = 0
# max_msg_size = -1
# storage = "file"
# discard = "old"
# num_replicas = 1
# duplicate_window = 120000000000
# sealed = false
# deny_delete = false
# deny_purge = false
# allow_rollup_hdrs = false
# allow_direct = true
# mirror_direct = false
## Disable creating the stream but assume the stream is managed externally
## and already exists. This will make the plugin fail if the steam does not exist.
# disable_stream_creation = false
Subject Configuration
The subject
setting determines where producer messages will be published
in NATS. This can be a static subject (e.g., “telegraf”), or a dynamic
subject template using Go’s text/template syntax.
Dynamic templates allow you to construct subjects based on properties of each metric, such as tags, name and fields. This enables fine-grained routing and filtering across NATS or JetStream subscribers.
This feature is incompatible with use_batch_format
Examples
Routing based on tags and metric name:
subject = '{{ .Tag "region" }}.{{ .Tag "datacenter" }}.{{ .Tag "host" }}.{{ .Name }}'
Routing based on tags, metric name and field name:
subject = 'telegraf.metrics.{{ .Tag "datacenter" }}.{{ .Tag "host" }}.{{ .Name }}.{{ .Field "Value1" }}'
If you’re using JetStream the value of subject determines where messages are published.
When using a dynamic subject template, Telegraf does not automatically register the generated subjects with the JetStream stream.
For dynamic subject
s you must explicitly define matching subjects in
outputs.nats.jetstream.subjects
to ensure your stream can receive and
retain those messages correctly.
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.