---
title: NATS
slug: telemetry-pipeline/teCq-nats
docTags: 
createdAt: 2025-04-21T00:52:38.551Z
---

## 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. 

:::BlockQuote
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** 

:::BlockQuote
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.