NATS

NATS Message Queue

Synopsis

Creates a target that publishes log messages to NATS JetStream subjects with support for batching, authentication, TLS encryption, and automatic retry logic. NATS is a high-performance messaging system for cloud-native applications.

Schema

- name: <string>
  description: <string>
  type: nats
  pipelines: <pipeline[]>
  status: <boolean>
  properties:
    url: <string>
    subject: <string>
    username: <string>
    password: <string>
    timeout: <integer>
    batch_size: <integer>
    max_retries: <integer>
    retry_delay: <integer>
    field_format: <string>
    tls:
      status: <boolean>
      verify: <boolean>
      cert_name: <string>
      key_name: <string>
      min_tls_version: <string>
      max_tls_version: <string>
    interval: <string|numeric>
    cron: <string>
    debug:
      status: <boolean>
      dont_send_logs: <boolean>

Configuration

The following fields are used to define the target:

Field	Required	Default	Description
name	Y		Target name
description	N	-	Optional description
type	Y		Must be nats
pipelines	N	-	Optional post-processor pipelines
status	N	true	Enable/disable the target

Connection

Field	Required	Default	Description
url	Y	-	NATS server URL (e.g., nats://localhost:4222)
subject	Y	-	NATS subject name for message publishing
username	N	-	NATS username for authentication
password	N	-	NATS password for authentication
timeout	N	30	Connection timeout in seconds

Batch Configuration

Field	Required	Default	Description
batch_size	N	1000	Number of messages to batch before publishing (minimum 1)
max_retries	N	3	Maximum retry attempts for failed publish operations
retry_delay	N	1	Delay between retry attempts in seconds

Processing

Field	Required	Default	Description
field_format	N	-	Data normalization format. See applicable Normalization section

TLS Configuration

Field	Required	Default	Description
tls.status	N	false	Enable TLS encryption
tls.verify	N	true	Verify server TLS certificate
tls.cert_name	N*	-	Client certificate filename (PEM format)
tls.key_name	N*	-	Client private key filename (PEM format)
tls.min_tls_version	N	tls1.2	Minimum TLS version: tls1.0, tls1.1, tls1.2, tls1.3
tls.max_tls_version	N	tls1.3	Maximum TLS version: tls1.0, tls1.1, tls1.2, tls1.3

* = Conditionally required. Both cert_name and key_name must be provided together or omitted together.

Scheduler

Field	Required	Default	Description
interval	N	realtime	Execution frequency. See Interval for details
cron	N	-	Cron expression for scheduled execution. See Cron for details

Debug Options

Field	Required	Default	Description
debug.status	N	false	Enable debug logging
debug.dont_send_logs	N	false	Process logs but don't send to target (testing)

Details

The NATS target uses NATS JetStream to publish log messages with guaranteed delivery semantics. Messages are accumulated in batches and published when the batch size is reached. Each message is published with automatic retry logic for handling transient failures.

The target maintains a persistent connection to the NATS server with automatic reconnection capabilities. Connection options include configurable timeouts, maximum reconnect attempts, and authentication.

NATS JetStream provides stream-based messaging with persistence, acknowledgment, and replay capabilities, making it suitable for reliable log delivery in distributed systems.

Prerequisites

1. A running NATS server with JetStream enabled
2. Network connectivity to the NATS server
3. Valid authentication credentials if the server requires authentication
4. TLS certificates if using encrypted connections

note

The NATS target requires JetStream to be enabled on the NATS server. Core NATS messaging without JetStream is not supported.

warning

Both tls.cert_name and tls.key_name must be provided together when using client certificate authentication. Providing only one will result in a configuration error.

Examples

Basic

Minimum configuration for publishing to NATS JetStream:

targets:
  - name: basic_nats
    type: nats
    properties:
      url: "nats://localhost:4222"
      subject: "logs.system"

With Authentication

Configuration with username/password authentication:

targets:
  - name: authenticated_nats
    type: nats
    properties:
      url: "nats://nats.example.com:4222"
      subject: "logs.application"
      username: "logger"
      password: "secure_password"

With TLS

Configuration with TLS encryption and certificate verification:

targets:
  - name: secure_nats
    type: nats
    properties:
      url: "nats://nats.example.com:4222"
      subject: "logs.secure"
      username: "logger"
      password: "secure_password"
      tls:
        status: true
        verify: true
        min_tls_version: "tls1.2"

With Client Certificate

Configuration using mutual TLS with client certificates:

targets:
  - name: mtls_nats
    type: nats
    properties:
      url: "nats://nats.example.com:4222"
      subject: "logs.secure"
      tls:
        status: true
        verify: true
        cert_name: "client.pem"
        key_name: "client-key.pem"
        min_tls_version: "tls1.2"

Custom Batch Size

Configuration with custom batching and retry settings:

targets:
  - name: batch_nats
    type: nats
    properties:
      url: "nats://nats.example.com:4222"
      subject: "logs.highvolume"
      batch_size: 5000
      max_retries: 5
      retry_delay: 2
      timeout: 60

With Normalization

Configuration using field normalization:

targets:
  - name: normalized_nats
    type: nats
    properties:
      url: "nats://nats.example.com:4222"
      subject: "logs.ecs"
      field_format: "ecs"

With Pipeline

Using a pipeline for additional log processing:

targets:
  - name: pipeline_nats
    type: nats
    pipelines:
      - enrich_logs
    properties:
      url: "nats://nats.example.com:4222"
      subject: "logs.enriched"