> ## 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 exporter for Nats

# Nats Exporter

![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/exporter/natsexporter)

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

Exports traces, metrics, and logs to a [NATS](https://nats.io/) server. Payloads
are published to NATS subjects using core NATS (fire-and-forget) or, optionally,
[JetStream](https://docs.nats.io/nats-concepts/jetstream) for durable,
acknowledged delivery.

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

## 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 published subjects. Defaults to `false` to mirror the NATS client default. Enabling it is useful here so that a malformed subject produced by an OTTL expression surfaces as an error rather than being silently misrouted. |
| `tls` | (disabled) | TLS client configuration. See [configtls](https://github.com/open-telemetry/opentelemetry-collector/blob/main/config/configtls/README.md). |
| `jetstream` | (unset) | When set, publish 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. |

### Signal configuration

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

| Field | Default | Description |
| - | - | - |
| `subject` | `"otel_logs"` / `"otel_metrics"` / `"otel_traces"` | [OTTL value expression](https://github.com/open-telemetry/opentelemetry-collector-contrib/blob/main/pkg/ottl/README.md) evaluated to produce the [NATS subject](https://docs.nats.io/nats-concepts/subjects). String literals must be quoted. |
| `marshaler` | `otlp_proto` | Built-in payload marshaler: `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 marshal payloads. Mutually exclusive with `marshaler`. |

### JetStream

When the `jetstream` block is present, every payload is published with JetStream
and the publish blocks until the server acknowledges persistence.

By default the exporter ensures a stream exists for the configured subjects,
creating one with lightweight defaults if it is absent: a single stream, `limits`
retention bounded by both `max_age` and `max_bytes`, file storage, and a single
replica. These defaults are sized for a small or edge deployment and are safe to
run on a single-node server; scale them up (notably to three replicas) for a
clustered hub. Set `stream.manage: false` to require a pre-existing stream
instead — appropriate when the exporter holds publish-only credentials or streams
are provisioned externally.

Sharding a high-volume signal across multiple streams is a planned scale-up
option and is not yet configurable.

| Field | Default | Description |
| - | - | - |
| `domain` | (server default) | JetStream domain, e.g. when publishing through a leaf node to a hub. |
| `publish_timeout` | `0` (no exporter deadline) | Maximum time to wait for each publish acknowledgement. |

### 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}
exporters:
  # Minimal: core NATS, default subjects, OTLP protobuf.
  nats:
    endpoint: nats://localhost:4222

  # Full: JetStream durable publishing with auth, TLS, and per-signal subjects.
  nats/full:
    endpoint: nats://nats.example.com:4222
    tls:
      insecure: false
      ca_file: /etc/otel/certs/ca.crt
    auth:
      user:
        username: otel
        password: ${env:NATS_PASSWORD}
    jetstream:
      domain: hub
      publish_timeout: 5s
    logs:
      subject: '"otel.logs." + resource.attributes["service.name"]'
      marshaler: otlp_proto
    metrics:
      subject: '"otel.metrics"'
      marshaler: otlp_json
    traces:
      subject: '"otel.spans"'

service:
  pipelines:
    traces:
      receivers: [otlp]
      exporters: [nats]
```

## Configuration

### Example Configuration

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

nats/full:
  endpoint: nats://nats.example.com:4222
  pedantic: true
  tls:
    insecure: false
    ca_file: /etc/otel/certs/ca.crt
  auth:
    user:
      username: otel
      password: s3cret
  jetstream:
    domain: hub
    publish_timeout: 5s
  logs:
    subject: '"otel.logs"'
    marshaler: otlp_proto
  metrics:
    subject: '"otel.metrics"'
    marshaler: otlp_json
  traces:
    subject: '"otel.spans"'
    encoding_extension: otlp_encoding/nats
```

***

*Last generated: 2026-10-05*