Skip to main content
Logging options control how NATS server outputs operational information, debug messages, and protocol traces.

​
Command Syntax

nats-server [logging-options]

​
Logging Options Reference

​
-l, --log
string
File to redirect log output. By default, logs are written to stdout.Examples:
# Log to file
nats-server -l /var/log/nats-server.log

# Log to file with rotation
nats-server -l /var/log/nats.log --log_size_limit 100MB
The log file can be rotated using the reopen signal. See Signals for details.
​
-T, --logtime
boolean
default:"true"
Timestamp log entries. Enabled by default.Examples:
# Timestamps enabled (default)
nats-server -T

# Disable timestamps
nats-server -T=false
With timestamps:
[1] 2024-03-04 10:15:23.123456 [INF] Starting nats-server
Without timestamps:
[1] [INF] Starting nats-server
​
-s, --syslog
boolean
Log to syslog or Windows event log. Routes log output to the system’s logging facility.Examples:
# Log to local syslog
nats-server -s

# On Linux, logs appear in /var/log/syslog or /var/log/messages
# On macOS, logs appear in system log (viewable with Console.app)
# On Windows, logs appear in Event Viewer
​
-r, --remote_syslog
string
Syslog server address. Send logs to a remote syslog server.Format: udp://hostname:portExamples:
# Default remote syslog
nats-server -r udp://localhost:514

# Custom remote syslog server
nats-server -r udp://syslog.example.com:514

# Remote syslog on custom port
nats-server -r udp://10.0.1.5:5140
​
-D, --debug
boolean
Enable debugging output. Provides detailed information about server operations.Examples:
# Enable debug logging
nats-server -D

# Debug with log file
nats-server -D -l debug.log
Debug output includes:
  • Client connections and disconnections
  • Subscription details
  • Route and gateway connections
  • Internal server state changes
​
-V, --trace
boolean
Trace the raw protocol. Shows the actual NATS protocol messages exchanged with clients (excluding system account).Examples:
# Enable protocol tracing
nats-server -V

# Trace with debug
nats-server -DV
Trace output example:
[2] 2024-03-04 10:15:23.456789 [TRC] 192.168.1.5:54321 - cid:1 - <<- [PUB foo 5]
[2] 2024-03-04 10:15:23.456790 [TRC] 192.168.1.5:54321 - cid:1 - <<- MSG_PAYLOAD: ["hello"]
Trace logging can generate significant output and impact performance. Use only for debugging.
​
-VV
boolean
Verbose trace. Traces system account as well. Includes all protocol messages including system account traffic.Examples:
# Verbose trace
nats-server -VV

# Debug with verbose trace
nats-server -DVV
Use this when debugging system account issues or JetStream internals.
​
-DV
boolean
Debug and trace. Convenient combination of debug and trace flags.Examples:
# Debug and trace
nats-server -DV

# Equivalent to
nats-server -D -V
​
-DVV
boolean
Debug and verbose trace. Combination of debug and verbose trace flags.Examples:
# Debug and verbose trace
nats-server -DVV

# Equivalent to
nats-server -D -VV
​
--log_size_limit
string
default:"auto"
Logfile size limit. When the log file reaches this size, it is automatically rotated.Format: Number with optional unit (B, KB, MB, GB)Examples:
# Limit to 100 megabytes
nats-server -l nats.log --log_size_limit 100MB

# Limit to 1 gigabyte
nats-server -l nats.log --log_size_limit 1GB

# Limit to 50 megabytes
nats-server -l nats.log --log_size_limit 52428800
When the limit is reached, the current log file is renamed with a timestamp suffix and a new log file is created.
​
--max_traced_msg_len
number
default:"unlimited"
Maximum printable length for traced messages. Limits the payload size shown in trace output.Examples:
# Limit traced payload to 1KB
nats-server -V --max_traced_msg_len 1024

# Limit to 100 bytes
nats-server -V --max_traced_msg_len 100
Useful when tracing messages with large payloads to prevent log file bloat.Output example with limit:
[TRC] - cid:1 - <<- MSG_PAYLOAD: ["very long message content..."] (truncated, 5000 bytes total)

​
Complete Examples

​
Development Debugging

# Debug with trace to stdout
nats-server -DV

​
Production Logging

# Log to file with rotation
nats-server \
  -l /var/log/nats-server.log \
  --log_size_limit 100MB

​
Remote Syslog

# Send logs to centralized syslog server
nats-server -r udp://syslog.internal.com:514

​
Protocol Debugging

# Trace protocol with limited message length
nats-server -V --max_traced_msg_len 256 -l trace.log

​
Full Debug Mode

# Debug, verbose trace, and log to file
nats-server -DVV -l debug.log --log_size_limit 50MB

​
Production with Info Logging

# Standard logging with timestamps
nats-server \
  -c /etc/nats/nats-server.conf \
  -l /var/log/nats-server.log \
  -T \
  --log_size_limit 100MB

​
Log Levels

NATS server uses the following log levels:
LevelDescriptionEnabled By
ERRError messagesAlways
WRNWarning messagesAlways
INFInformational messagesAlways
DBGDebug messages-D or --debug
TRCProtocol trace-V or --trace

​
Log Rotation

Logs can be rotated in two ways:
  1. Automatic rotation - When --log_size_limit is reached
  2. Manual rotation - Send reopen signal to the server
# Trigger log rotation
nats-server --signal reopen=/var/run/nats-server.pid
See Signals for more details.

Build docs developers (and LLMs) love

Get started for freeTalk to us