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

Info - Normal operational messages (default)
Warning - Warning messages for potential issues
Error - Error messages for failures
Fatal - Fatal errors that cause server shutdown
Debug - Detailed debugging information
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:

Current log renamed to nats-server.log.2026.03.04.10.15.30
New log file created
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:

When log reaches 100MB, rotate
Old log renamed with timestamp
New log file created
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

Production: Use info level only
Staging: Enable debug for issues
Development: Use debug or trace freely
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

Get Started

Deployment

Architecture

Features

Operations

Configuration

​Logging Overview

​Log Levels

​Log Output Configuration

​Standard Error (Default)

​File Output

​Log File Rotation

​Disable Timestamps

​Debug Logging

​Trace Logging

​Verbose Trace

​Limit Traced Message Length

​Syslog Support

​Local Syslog

​Remote Syslog

​Syslog Configuration

​Log Format

​Standard Format

​Components

​Colored Output

​Structured Logging

​Client Connection Logs

​Account Logs

​Authentication Logs

​Error Logs

​Log Configuration Examples

​Production Configuration

​Development Configuration

​High-Volume Production

​Debugging Issues

​Log Rotation Strategy

​Size-Based Rotation

​External Rotation (logrotate)

​Runtime Log Control

​Performance Considerations

​Log Level Impact

​Recommendations

​Async Logging

​Monitoring Logs

​Log Aggregation

​Alerting

​Best Practices

​1. Use Appropriate Log Levels

​2. Rotate Logs

​3. Limit Trace Payload

​4. Centralize Logs

​5. Monitor Log Growth

​6. Secure Log Files

​Related Topics

Build docs developers (and LLMs) love

Logging Overview

Log Levels

Log Output Configuration

Standard Error (Default)

File Output

Log File Rotation

Disable Timestamps

Debug Logging

Trace Logging

Verbose Trace

Limit Traced Message Length

Syslog Support

Local Syslog

Remote Syslog

Syslog Configuration

Log Format

Standard Format

Components

Colored Output

Structured Logging

Client Connection Logs

Account Logs

Authentication Logs

Error Logs

Log Configuration Examples

Production Configuration

Development Configuration

High-Volume Production

Debugging Issues

Log Rotation Strategy

Size-Based Rotation

External Rotation (logrotate)

Runtime Log Control

Performance Considerations

Log Level Impact

Recommendations

Async Logging

Monitoring Logs

Log Aggregation

Alerting

Best Practices

1. Use Appropriate Log Levels

2. Rotate Logs

3. Limit Trace Payload

4. Centralize Logs

5. Monitor Log Growth

6. Secure Log Files

Related Topics