Logging

Configure logging levels, outputs, and formats in NATS Server

Logging Overview

NATS Server provides flexible logging capabilities to monitor server operations, debug issues, and audit activity.

Log Levels

NATS supports multiple log levels:

1. Info - Normal operational messages (default)
2. Warning - Warning messages for potential issues
3. Error - Error messages for failures
4. Fatal - Fatal errors that cause server shutdown
5. Debug - Detailed debugging information
6. Trace - Protocol-level tracing

Log Output Configuration

Standard Error (Default)

By default, logs go to stderr:

nats-server

Output:

[1] 2026/03/04 10:15:30.123456 [INF] Starting nats-server
[1] 2026/03/04 10:15:30.123789 [INF]   Version:  2.10.0
[1] 2026/03/04 10:15:30.124012 [INF]   Git:      [abc1234]

File Output

Redirect logs to a file:

log_file: "/var/log/nats-server.log"

Or via command line:

nats-server --log /var/log/nats-server.log

Log File Rotation

Automatic log rotation based on size:

log_file: "/var/log/nats-server.log"
log_size_limit: 1073741824  # 1GB in bytes
max_traced_msg_len: 256

From logger/log.go implementation, when the log file reaches the size limit:

1. Current log renamed to nats-server.log.2026.03.04.10.15.30
2. New log file created
3. Configurable maximum number of archived log files

Disable Timestamps

Remove timestamps from logs:

logtime: false

Or via command line:

nats-server -T=false

Debug Logging

Enable detailed debug output:

debug: true

Or via command line:

nats-server -D
# or
nats-server --debug

Debug logs show:

• Client connections and disconnections
• Subscription operations
• Route establishment
• Account operations
• Authentication attempts

Example debug output:

[1] 2026/03/04 10:15:35.123456 [DBG] 127.0.0.1:52461 - cid:1 - Client connection created
[1] 2026/03/04 10:15:35.123789 [DBG] 127.0.0.1:52461 - cid:1 - Client connection closed: Client Closed

Trace Logging

Enable protocol-level tracing:

trace: true

Or via command line:

nats-server -V
# or
nats-server --trace

Trace logs show raw protocol messages:

[1] 2026/03/04 10:15:35.123456 [TRC] 127.0.0.1:52461 - cid:1 - <<- [PUB test 5]
[1] 2026/03/04 10:15:35.123457 [TRC] 127.0.0.1:52461 - cid:1 - <<- MSG_PAYLOAD: ["hello"]
[1] 2026/03/04 10:15:35.123458 [TRC] 127.0.0.1:52462 - cid:2 - ->> [MSG test 2 5]

Verbose Trace

Trace including system account (from main.go:51):

nats-server -VV

Or debug and verbose trace:

nats-server -DVV

Limit Traced Message Length

Limit message payload length in trace logs:

max_traced_msg_len: 256  # bytes

Or via command line:

nats-server -V --max_traced_msg_len 256

Trace logging significantly impacts performance. Use only for debugging.

Syslog Support

Send logs to syslog or Windows Event Log:

Local Syslog

syslog: true

Or via command line:

nats-server -s
# or
nats-server --syslog

Remote Syslog

Send to remote syslog server:

remote_syslog: "udp://syslog.example.com:514"

Or via command line:

nats-server -r udp://syslog.example.com:514
# or
nats-server --remote_syslog udp://syslog.example.com:514

Syslog Configuration

From logger/syslog.go, NATS supports:

• Unix socket: /dev/log, /var/run/syslog
• UDP: udp://host:port
• TCP: tcp://host:port

Example:

remote_syslog: "tcp://logs.company.com:514"

Log Format

Standard Format

Default log format (from logger/log.go:74-95):

[PID] YYYY/MM/DD HH:MM:SS.microseconds [LEVEL] message

Example:

[12345] 2026/03/04 10:15:30.123456 [INF] Starting nats-server

Components

• [PID] - Process ID (optional, enabled with pid: true)
• YYYY/MM/DD HH:MM:SS.microseconds - Timestamp with microsecond precision
• [LEVEL] - Log level: INF, WRN, ERR, FTL, DBG, TRC
• message - Log message

Colored Output

When outputting to terminal, logs can be colored:

# Colors are automatically enabled for terminal output
nats-server -D

Colors are disabled when logging to file or piping output.

Structured Logging

NATS logs include structured information:

Client Connection Logs

[1] 2026/03/04 10:15:35.123456 [DBG] 127.0.0.1:52461 - cid:1 - Client connection created

Fields:

• IP address and port
• Connection ID (cid)
• Event description

Account Logs

[1] 2026/03/04 10:15:35.123456 [INF] Account "PRODUCTION" created

Authentication Logs

[1] 2026/03/04 10:15:35.123456 [DBG] 127.0.0.1:52461 - cid:1 - User "alice" authenticated

Error Logs

[1] 2026/03/04 10:15:35.123456 [ERR] Authorization violation for subscription "secret.data" by user "bob"

Log Configuration Examples

Production Configuration

log_file: "/var/log/nats/server.log"
log_size_limit: 1073741824  # 1GB
logtime: true
debug: false
trace: false

Development Configuration

logtime: true
debug: true
trace: true
max_traced_msg_len: 1024

High-Volume Production

log_file: "/var/log/nats/server.log"
log_size_limit: 536870912  # 512MB
logtime: true
debug: false
trace: false
remote_syslog: "udp://syslog.company.com:514"

Debugging Issues

log_file: "/tmp/nats-debug.log"
logtime: true
debug: true
trace: true
max_traced_msg_len: 2048

Log Rotation Strategy

Size-Based Rotation

From logger/log.go implementation:

log_file: "/var/log/nats-server.log"
log_size_limit: 104857600  # 100MB

Behavior:

1. When log reaches 100MB, rotate
2. Old log renamed with timestamp
3. New log file created
4. Process continues without interruption

External Rotation (logrotate)

Use system log rotation:

/etc/logrotate.d/nats-server:

/var/log/nats-server.log {
    daily
    rotate 7
    compress
    delaycompress
    notifempty
    missingok
    postrotate
        /usr/bin/killall -SIGUSR1 nats-server
    endscript
}

Reopen log file:

nats-server --signal reopen

Runtime Log Control

Change log levels without restart:

# Enable debug logging
nats-server --signal ldm

# Reload configuration (includes log settings)
nats-server --signal reload

From main.go:39, supported signals:

• ldm - Toggle debug and trace logging
• reopen - Reopen log file
• reload - Reload configuration

Performance Considerations

Log Level Impact

• Info/Warn/Error: Minimal performance impact
• Debug: Low to moderate impact (~5-10% overhead)
• Trace: Significant impact (~20-50% overhead)

Recommendations

1. Production: Use info level only
2. Staging: Enable debug for issues
3. Development: Use debug or trace freely
4. Performance testing: Disable debug and trace

Async Logging

From logger/log.go implementation, file logging is buffered:

• Writes are buffered to reduce I/O
• Automatic flush on rotation
• Minimal blocking of main thread

Monitoring Logs

Log Aggregation

Forward logs to aggregation systems:

remote_syslog: "udp://logstash.company.com:514"

Or use file monitoring:

tail -f /var/log/nats-server.log | your-log-shipper

Alerting

Monitor for critical patterns:

• [ERR] - Error conditions
• [FTL] - Fatal errors
• Authorization violation - Security issues
• slow consumer - Performance issues

Best Practices

1. Use Appropriate Log Levels

# Production
debug: false
trace: false

# Debugging
debug: true
trace: false  # Only when needed

2. Rotate Logs

log_file: "/var/log/nats-server.log"
log_size_limit: 1073741824  # Prevent disk fill

3. Limit Trace Payload

trace: true
max_traced_msg_len: 256  # Prevent huge logs

4. Centralize Logs

remote_syslog: "udp://logs.company.com:514"

5. Monitor Log Growth

# Check log file size
du -h /var/log/nats-server.log

# Monitor log rate
tail -f /var/log/nats-server.log | pv -l > /dev/null

6. Secure Log Files

chmod 640 /var/log/nats-server.log
chown nats:adm /var/log/nats-server.log

Related Topics

• Monitoring Endpoints
• Security Overview