Logging Options

Configure NATS server logging, debugging, and tracing

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:port

Examples:

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

Level	Description	Enabled By
ERR	Error messages	Always
WRN	Warning messages	Always
INF	Informational messages	Always
DBG	Debug messages	-D or --debug
TRC	Protocol 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.

Related Options

• Server Options - Core server configuration
• Signals - Log rotation and reload signals