> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/nats-io/nats-server/llms.txt
> Use this file to discover all available pages before exploring further.

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

```bash theme={null}
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:

```hocon theme={null}
log_file: "/var/log/nats-server.log"
```

Or via command line:

```bash theme={null}
nats-server --log /var/log/nats-server.log
```

### Log File Rotation

Automatic log rotation based on size:

```hocon theme={null}
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:

```hocon theme={null}
logtime: false
```

Or via command line:

```bash theme={null}
nats-server -T=false
```

## Debug Logging

Enable detailed debug output:

```hocon theme={null}
debug: true
```

Or via command line:

```bash theme={null}
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:

```hocon theme={null}
trace: true
```

Or via command line:

```bash theme={null}
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):

```bash theme={null}
nats-server -VV
```

Or debug and verbose trace:

```bash theme={null}
nats-server -DVV
```

### Limit Traced Message Length

Limit message payload length in trace logs:

```hocon theme={null}
max_traced_msg_len: 256  # bytes
```

Or via command line:

```bash theme={null}
nats-server -V --max_traced_msg_len 256
```

<Warning>
  Trace logging significantly impacts performance. Use only for debugging.
</Warning>

## Syslog Support

Send logs to syslog or Windows Event Log:

### Local Syslog

```hocon theme={null}
syslog: true
```

Or via command line:

```bash theme={null}
nats-server -s
# or
nats-server --syslog
```

### Remote Syslog

Send to remote syslog server:

```hocon theme={null}
remote_syslog: "udp://syslog.example.com:514"
```

Or via command line:

```bash theme={null}
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:**

```hocon theme={null}
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:

```bash theme={null}
# Colors are automatically enabled for terminal output
nats-server -D
```

<Info>
  Colors are disabled when logging to file or piping output.
</Info>

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

```hocon theme={null}
log_file: "/var/log/nats/server.log"
log_size_limit: 1073741824  # 1GB
logtime: true
debug: false
trace: false
```

### Development Configuration

```hocon theme={null}
logtime: true
debug: true
trace: true
max_traced_msg_len: 1024
```

### High-Volume Production

```hocon theme={null}
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

```hocon theme={null}
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:

```hocon theme={null}
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:

```bash theme={null}
nats-server --signal reopen
```

## Runtime Log Control

Change log levels without restart:

```bash theme={null}
# 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:

```hocon theme={null}
remote_syslog: "udp://logstash.company.com:514"
```

Or use file monitoring:

```bash theme={null}
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

```hocon theme={null}
# Production
debug: false
trace: false

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

### 2. Rotate Logs

```hocon theme={null}
log_file: "/var/log/nats-server.log"
log_size_limit: 1073741824  # Prevent disk fill
```

### 3. Limit Trace Payload

```hocon theme={null}
trace: true
max_traced_msg_len: 256  # Prevent huge logs
```

### 4. Centralize Logs

```hocon theme={null}
remote_syslog: "udp://logs.company.com:514"
```

### 5. Monitor Log Growth

```bash theme={null}
# 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

```bash theme={null}
chmod 640 /var/log/nats-server.log
chown nats:adm /var/log/nats-server.log
```

## Related Topics

* [Monitoring Endpoints](/operations/monitoring-endpoints)
* [Security Overview](/operations/security)