NATS
NATS Source
The NATS source enables reading observability data from subjects in a NATS messaging system. It is commonly used to ingest telemetry data published by applications, agents, or pipelines that rely on NATS as a transport layer.
This source operates in an aggregator role and supports logs, metrics, and traces. Message delivery follows a best-effort model and does not support acknowledgements.
Configuration Overview
The NATS source connects to a NATS server, subscribes to one or more subjects, and decodes incoming messages into telemetry events. It supports multiple authentication mechanisms, flexible decoding strategies, optional framing, and JetStream integration.
Connection Settings
Required Fields
- url (string) The NATS server URL to connect to. If no port is specified, the default NATS port (4222) is used.
- connection_name (string) A logical name assigned to the NATS connection for identification and observability.
- subject (string) The NATS subject from which messages are consumed.
Optional Fields
- queue (string) The NATS queue group to join, enabling load-balanced consumption.
- subject_key_field (string, default: subject) The field name used to store the NATS subject in the event.
- subscriber_capacity (unsigned integer, default: 65536) Buffer capacity of the underlying NATS subscriber. When exceeded, incoming messages may be dropped.
Authentication (auth)
Defines how the source authenticates with the NATS server. The authentication strategy is selected using auth.strategy.
Supported Strategies
- credentials_file (JWT-based authentication)
- nkey (NKey authentication)
- token (Token-based authentication)
- user_password (Username and password authentication)
Strategy-Specific Fields
- credentials_file.path Path to the NATS credentials file.
- nkey.nkey Public NKey (conceptually equivalent to a username).
- nkey.seed Private seed (conceptually equivalent to a private key).
- token.value Authentication token.
- user_password.user Username.
- user_password.password Password.
TLS client certificate authentication is configured separately under tls.
Decoding Configuration (decoding)
Controls how raw message bytes are converted into events. Some decoders can automatically determine the output type (logs, metrics, or traces).
Codec Selection
- decoding.codec (string, default: bytes)
Supported codecs include:
- bytes
- json
- avro
- gelf
- influxdb
- syslog
- protobuf
- otlp
- native
- native_json
- vrl
Certain codecs (such as native, native_json, and otlp) can emit logs, metrics, and traces directly.
OTLP Decoding
When using the otlp codec, the decoder automatically detects the OTLP signal type.
- decoding.signal_types (list of strings) Signal types to attempt parsing, in priority order. Defaults to logs, metrics, traces.
Codec-Specific Options
Each codec may define additional options, such as:
- lossy decoding (for JSON, GELF, InfluxDB, Syslog, Native JSON) Controls whether invalid UTF-8 sequences are replaced or cause failures.
- schema and descriptor configuration (for Avro and Protobuf)
- VRL decoding Executes a VRL program to transform raw bytes into structured events.
Framing Configuration (framing)
Defines how individual messages are separated from the raw byte stream before decoding.
Supported Framing Methods
- bytes
- character_delimited
- newline_delimited
- length_delimited
- varint_length_delimited
- octet_counting
- chunked_gelf
Each framing method supports optional limits to protect against malformed or unbounded data, such as maximum frame length or timeout settings.
JetStream Integration (jetstream)
Enables consumption from NATS JetStream using a pull-based durable consumer.
Required Fields
- jetstream.stream Name of the JetStream stream.
- jetstream.consumer Name of the durable consumer.
Optional Fields
- batch_config.batch Maximum number of messages per pull request.
- batch_config.max_bytes Maximum total byte size per batch.
JetStream defaults are aligned with the async-nats client behavior.
TLS Configuration (tls)
Configures TLS for connections to the NATS server.
Supported Options
- enabled
- crt_file
- key_file
- key_pass
- ca_file
- alpn_protocols
- verify_certificate
- verify_hostname
- server_name
Disabling certificate or hostname verification is strongly discouraged unless the security implications are fully understood.
Output
The default output stream of the NATS source is exposed using the component’s ID and can be connected to downstream transforms and sinks.
Event Types
- Logs
- Metrics
- Traces
Log Event Fields
- message (string) Raw payload from the NATS message.
- subject (string) NATS subject the message was received from.
- source_type (string) Always set to nats.