JetStream Options

Configure JetStream for persistent messaging, streaming, and advanced message patterns

Overview

JetStream is NATS’s built-in persistence layer providing streaming, message replay, and exactly-once delivery semantics. These options control JetStream’s behavior, storage limits, and performance characteristics.

Command Line Flags

-js, --jetstream · boolean · default: "false"

Enable JetStream functionality.

nats-server -js

-sd, --store_dir · string

Directory for JetStream storage files. If not specified, a temporary directory will be used.

nats-server -js -sd /var/lib/nats/jetstream

Configuration File Options

Enabling JetStream

jetstream · boolean · default: "false"

Enable JetStream in the configuration file.

jetstream {
  # JetStream enabled
}

Storage Configuration

jetstream.store_dir · string

Path to directory where JetStream will store data.

jetstream {
  store_dir: "/var/lib/nats/jetstream"
}

The directory will be created if it doesn’t exist. Ensure the NATS server has write permissions.

jetstream.max_memory_store · integer

Maximum memory storage in bytes for memory-based streams. Default is 75% of available memory.

jetstream {
  max_memory_store: 1073741824  # 1 GB
}

jetstream.max_file_store · integer

Maximum file storage in bytes for file-based streams. Default is calculated based on available disk space.

jetstream {
  max_file_store: 10737418240  # 10 GB
}

Domain Configuration

jetstream.domain · string

JetStream domain name for multi-tenancy and organizational separation.

jetstream {
  domain: "production"
}

Domains allow logical separation of JetStream resources across the same NATS infrastructure.

Sync and Performance

jetstream.sync_interval · duration · default: "2m"

Interval for syncing data to disk (fsync). More frequent syncs increase durability but reduce performance.

jetstream {
  sync_interval: "30s"
}

jetstream.sync_always · boolean · default: "false"

Sync to disk after every write. Maximizes durability but significantly impacts performance.

jetstream {
  sync_always: true
}

Only enable for critical data where maximum durability is required.

jetstream.compress_ok · boolean · default: "false"

Allow compression of stored data.

jetstream {
  compress_ok: true
}

jetstream.unique_tag · string

Unique tag for this JetStream instance. Useful for identifying specific servers in clusters.

jetstream {
  unique_tag: "datacenter-1-rack-3-server-5"
}

Advanced Limits

jetstream.max_outstanding_catchup · integer

Maximum bytes for catching up consumers in clustered JetStream.

jetstream {
  max_outstanding_catchup: 33554432  # 32 MB
}

jetstream.limits · object

Server-wide limits for JetStream operations.

jetstream {
  limits {
    max_ha_assets: 100
    max_request_batch: 256
  }
}

Configuration Examples

Basic JetStream Setup

port: 4222
server_name: "nats-js-01"

# Enable JetStream
jetstream {
  store_dir: "/var/lib/nats/jetstream"
  max_memory_store: 1073741824    # 1 GB
  max_file_store: 10737418240     # 10 GB
}

JetStream with Custom Sync

port: 4222
server_name: "nats-js-sync"

jetstream {
  store_dir: "/mnt/ssd/nats/jetstream"
  max_memory_store: 2147483648    # 2 GB
  max_file_store: 53687091200     # 50 GB
  
  # Sync every 30 seconds for better durability
  sync_interval: "30s"
}

High Durability Configuration

port: 4222
server_name: "nats-js-durable"

jetstream {
  store_dir: "/data/nats/jetstream"
  max_memory_store: 536870912     # 512 MB
  max_file_store: 107374182400    # 100 GB
  
  # Maximum durability - sync every write
  sync_always: true
}

Multi-Domain Setup

port: 4222
server_name: "nats-js-domain"

jetstream {
  store_dir: "/var/lib/nats/jetstream"
  domain: "production"
  max_memory_store: 1073741824    # 1 GB
  max_file_store: 10737418240     # 10 GB
}

Clustered JetStream

port: 4222
server_name: "nats-js-cluster-01"

# Cluster configuration
cluster {
  name: "js-cluster"
  listen: "0.0.0.0:6222"
  routes: [
    "nats://nats-js-cluster-02:6222",
    "nats://nats-js-cluster-03:6222"
  ]
}

# JetStream with cluster-aware settings
jetstream {
  store_dir: "/var/lib/nats/jetstream"
  max_memory_store: 2147483648     # 2 GB
  max_file_store: 21474836480      # 20 GB
  unique_tag: "cluster-01"
  
  # Cluster-specific limits
  limits {
    max_ha_assets: 500
  }
}

Performance Optimized

port: 4222
server_name: "nats-js-perf"

jetstream {
  # Use fast SSD storage
  store_dir: "/mnt/nvme/nats/jetstream"
  
  max_memory_store: 4294967296     # 4 GB
  max_file_store: 107374182400     # 100 GB
  
  # Longer sync interval for higher throughput
  sync_interval: "5m"
  
  # Enable compression to save space
  compress_ok: true
}

Storage Types

JetStream supports two storage types per stream:

File Storage

Persistent storage on disk. Suitable for:

• Long-term message retention
• Large message volumes
• Durability requirements
• Message replay over extended periods

# Create file-based stream
nats stream add ORDERS --storage file --subjects "orders.*"

Memory Storage

In-memory storage. Suitable for:

• High-performance requirements
• Temporary data
• Lower latency needs
• Smaller message volumes

# Create memory-based stream
nats stream add EVENTS --storage memory --subjects "events.*"

Monitoring JetStream

Server Status

Check JetStream status via monitoring endpoint:

curl http://localhost:8222/jsz

Account Statistics

View account-level JetStream usage:

curl http://localhost:8222/jsz?acc=account_name

Storage Usage

Monitor storage consumption:

nats server info

Best Practices

1. Storage Location: Use fast SSDs for store_dir to improve performance
2. Capacity Planning: Monitor storage usage and set appropriate max_file_store limits
3. Memory Limits: Set max_memory_store to prevent OOM errors
4. Sync Strategy: Balance sync_interval between durability and performance needs
5. Clustering: Use odd numbers of servers (3, 5) for JetStream clusters
6. Backup: Regularly backup the store_dir directory
7. Domains: Use domains to organize multi-tenant deployments
8. Monitoring: Monitor JetStream metrics via /jsz endpoint
9. Disk Space: Ensure sufficient disk space (2-3x max_file_store)
10. Permissions: Verify NATS process has read/write access to store_dir

Limits and Quotas

JetStream enforces several limits:

• Max Memory: Total memory for memory-backed streams
• Max Storage: Total disk space for file-backed streams
• Max Streams: Number of streams per account (configurable)
• Max Consumers: Number of consumers per stream (configurable)
• Max Message Size: Individual message size limit

Configure account-level limits:

accounts {
  APP: {
    jetstream: {
      max_memory: 1073741824      # 1 GB
      max_file: 10737418240       # 10 GB
      max_streams: 100
      max_consumers: 1000
    }
  }
}

Troubleshooting

Storage Issues

# Check disk space
df -h /var/lib/nats/jetstream

# Verify permissions
ls -la /var/lib/nats/jetstream

Performance Issues

• Increase sync_interval for higher throughput
• Use SSDs for store_dir
• Consider memory-backed streams for hot data
• Enable compression for large messages

Cluster Issues

• Verify all cluster members have JetStream enabled
• Check that store_dir is unique per server
• Monitor /jsz for cluster state
• Ensure cluster connectivity via /routez

Related Configuration

Server Options

Core server configuration

Cluster Options

Cluster JetStream for HA

TLS Options

Secure JetStream with TLS