Skip to main content

​
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

Server Options

Core server configuration

Cluster Options

Cluster JetStream for HA

TLS Options

Secure JetStream with TLS

Build docs developers (and LLMs) love

Get started for freeTalk to us