> ## Documentation Index
> Fetch the complete documentation index at: https://otel.fyi/llms.txt
> Use this file to discover all available pages before exploring further.

# Nats

> OpenTelemetry receiver for Nats

# Nats Receiver

![Status](https://img.shields.io/badge/status-development-orange)

**Maintainers:** [@suckatrash](https://github.com/suckatrash), [@kalebpace](https://github.com/kalebpace), [@ChrsMark](https://github.com/ChrsMark)

**Source:** [opentelemetry-collector-contrib](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/receiver/natsreceiver)

## Supported Telemetry

![Logs](https://img.shields.io/badge/logs-development-blue) ![Metrics](https://img.shields.io/badge/metrics-development-green) ![Traces](https://img.shields.io/badge/traces-development-orange)

## Overview

Receives traces, metrics, and logs from a [NATS](https://nats.io/) server. The
receiver subscribes to NATS subjects using core NATS (at-most-once) or,
optionally, consumes from a [JetStream](https://docs.nats.io/nats-concepts/jetstream)
stream for durable, acknowledged delivery.

This is the receive-side counterpart to the [NATS exporter](../../exporter/natsexporter).
With default settings, the two components use the same subjects and encoding.

> [!NOTE]
>
> This component is in development. The configuration surface described below is
> stable, but the receiving implementation is being contributed incrementally.

## Delivery semantics

* **Core NATS** (default): at-most-once. There is no acknowledgement or
  redelivery; a payload that fails to decode or that the pipeline rejects is
  logged and dropped. Set `queue_group` to load balance a subject across several
  collector instances instead of each instance receiving every message.
* **JetStream** (`jetstream` set): the receiver consumes from a stream and:
  * **acks** a message once the pipeline accepts it,
  * **naks** it (triggering redelivery) when the pipeline returns an error,
  * **terminates** it (no redelivery) when the payload cannot be decoded, so a
    malformed message is not redelivered forever.

## Configuration

| Field | Default | Description |
| - | - | - |
| `endpoint` | `nats://127.0.0.1:4222` | NATS server URL. |
| `pedantic` | `false` | Enable NATS [pedantic](https://docs.nats.io/reference/reference-protocols/nats-protocol#connect) mode, which makes the server strictly validate subscribed subjects. |
| `tls` | (disabled) | TLS client configuration. See [configtls](https://github.com/open-telemetry/opentelemetry-collector/blob/main/config/configtls/README.md). |
| `jetstream` | (unset) | When set, consume via JetStream instead of core NATS. See [JetStream](#jetstream) below. |
| `logs` | | Per-signal configuration for logs. See [Signal configuration](#signal-configuration). |
| `metrics` | | Per-signal configuration for metrics. |
| `traces` | | Per-signal configuration for traces. |
| `auth` | | Authentication. See [Authentication](#authentication). |

### Signal configuration

Each of `logs`, `metrics`, and `traces` accepts:

| Field | Default | Description |
| - | - | - |
| `subject` | `otel_logs` / `otel_metrics` / `otel_traces` | [NATS subject](https://docs.nats.io/nats-concepts/subjects) to subscribe to, or the consumer filter subject in JetStream mode. Wildcards (`*`, `>`) are allowed. |
| `queue_group` | (unset) | Core NATS only. [Queue group](https://docs.nats.io/nats-concepts/core-nats/queue) to join; messages are load balanced across members. |
| `encoding` | `otlp_proto` | Built-in payload encoding: `otlp_proto` or `otlp_json`. Mutually exclusive with `encoding_extension`. |
| `encoding_extension` | (unset) | Component ID of an [encoding extension](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/extension/encoding) to unmarshal payloads. Mutually exclusive with `encoding`. |
| `stream` | (looked up by `subject`) | JetStream only. Stream to consume from. |
| `durable` | (unset) | JetStream only. Durable consumer name. Set it so progress survives restarts and so several collector instances can share the work; empty creates an ephemeral consumer. |

### JetStream

> [!NOTE]
>
> JetStream consumption is not yet implemented. The behavior described in this
> section is the planned design and is contributed in a follow-up.

When the `jetstream` block is present, each signal consumes from a JetStream
stream with explicit acknowledgement. The receiver does not create or manage
streams; a stream capturing the configured subject must already exist (for
example, one created by the NATS exporter).

| Field | Default | Description |
| - | - | - |
| `domain` | (server default) | JetStream domain, e.g. when consuming through a leaf node from a hub. |
| `ack_wait` | `0` (server default) | How long the server waits for an ack before redelivering a message. |
| `max_deliver` | `0` (server default) | Maximum delivery attempts per message. |

### Authentication

Authentication is configured under an `auth:` block. At most one authentication
method may be configured. See the NATS
[authentication docs](https://docs.nats.io/running-a-nats-service/configuration/securing_nats/auth_intro).

| Block | Fields | Description |
| - | - | - |
| `token` | `token` | Token authentication. |
| `user` | `username`, `password` | Username/password authentication. |
| `nkey` | `public_key`, `seed` | NKey authentication. |
| `nkey_jwt` | `jwt`, `seed` | NKey authentication via JWT. |
| `nkey_user_file` | `user_file` | NKey authentication via a credentials file. |

## Example

```yaml theme={null}
receivers:
  # Minimal: core NATS, default subjects, OTLP protobuf.
  nats:
    endpoint: nats://localhost:4222

  # Core NATS, load balanced across collector instances.
  nats/core:
    endpoint: nats://nats.example.com:4222
    tls:
      insecure: false
      ca_file: /etc/otel/certs/ca.crt
    auth:
      user:
        username: otel
        password: ${env:NATS_PASSWORD}
    logs:
      subject: otel.logs.>
      queue_group: otel-collectors
    traces:
      subject: otel.spans
      queue_group: otel-collectors
      encoding: otlp_json

  # JetStream durable consumer.
  nats/jetstream:
    endpoint: nats://nats.example.com:4222
    jetstream:
      domain: hub
      ack_wait: 30s
      max_deliver: 5
    logs:
      subject: otel.logs.>
      stream: OTEL_LOGS
      durable: otel_logs_consumer

service:
  pipelines:
    logs:
      receivers: [nats]
      exporters: [debug]
```

## Configuration

### Example Configuration

```yaml theme={null}
nats:
  endpoint: nats://localhost:4222

nats/core:
  endpoint: nats://nats.example.com:4222
  pedantic: true
  tls:
    insecure: false
    ca_file: /etc/otel/certs/ca.crt
  auth:
    user:
      username: otel
      password: s3cret
  logs:
    subject: otel.logs.>
    queue_group: otel-collectors
    encoding: otlp_proto
  metrics:
    subject: otel.metrics
    queue_group: otel-collectors
    encoding: otlp_json
  traces:
    subject: otel.spans
    encoding_extension: otlp_encoding/nats

nats/jetstream:
  endpoint: nats://nats.example.com:4222
  jetstream:
    domain: hub
    ack_wait: 30s
    max_deliver: 5
  logs:
    subject: otel.logs.>
    stream: OTEL_LOGS
    durable: otel_logs_consumer
```

***

*Last generated: 2026-11-09*
