Logging

NetBird uses structured logging with configurable levels and outputs across all components.

Log Levels

NetBird supports the following log levels (from most to least verbose):

Level	Description	Use Case
`trace`	Most detailed, includes fine-grained information	Deep debugging, protocol analysis
`debug`	Detailed debugging information	Development, troubleshooting
`info`	Informational messages about normal operations	Default production level
`warn`	Warning conditions that should be investigated	Potential issues
`error`	Error conditions that don’t stop execution	Application errors
`fatal`	Fatal errors that cause program exit	Critical failures
`panic`	Panic level, highest severity	System failures

The default log level is info for production use.

Client Logging

Log File Locations

Client logs are written to different locations based on the platform:

Linux

/var/log/netbird/client.log

Rotated logs:

/var/log/netbird/client.log.1
/var/log/netbird/client.log.2

Windows

C:\ProgramData\Netbird\client.log

Alternatively, view logs in Event Viewer under Application logs.

macOS

/var/log/netbird/client.log

Or view via Console.app:

open -a Console

FreeBSD

/var/db/netbird/client.log

Configure Client Log Level

Set Log Level via Command Line

# Permanent configuration (add to service)
netbird up --log-level debug

# Temporary for current session only
netbird debug log level debug

Available Log Levels

netbird debug log level trace   # Most verbose
netbird debug log level debug
netbird debug log level info    # Default
netbird debug log level warn
netbird debug log level error
netbird debug log level fatal
netbird debug log level panic   # Least verbose

trace level generates extensive logs and should only be used temporarily for troubleshooting.

Set Log Level via Environment Variable

# Linux/macOS
export NB_LOG_LEVEL=debug
netbird up

# Windows (PowerShell)
$env:NB_LOG_LEVEL="debug"
netbird up

Log Output Destinations

NetBird supports multiple log outputs simultaneously:

File Logging (Default)

netbird up --log-file /var/log/netbird/client.log

Console/Stdout

netbird up --log-file console

Useful for Docker containers and systemd with journal:

# View with journalctl
journalctl -u netbird -f

Syslog

netbird up --log-file syslog

Logs are sent to the system syslog daemon.

Multiple Outputs

# Write to both file and console
netbird up --log-file /var/log/netbird/client.log --log-file console

# Via environment variable
export NB_LOG_FILE="/var/log/netbird/client.log,console"

Temporary Debug Logging

Run with trace logging for a specific duration, then automatically create a debug bundle:

# Run with trace logging for 5 minutes
netbird debug for 5m

# Run with trace logging for 30 seconds
netbird debug for 30s

This command:

Sets log level to trace
Enables sync response persistence
Runs for the specified duration
Creates a debug bundle with logs
Restores original log level

Server Logging

Management Server

Configure Log Level

netbird-mgmt --log-level debug --log-file console

Docker Compose Configuration

services:
  management:
    image: netbirdio/management:latest
    command:
      - "--log-level"
      - "info"
      - "--log-file"
      - "console"

View Management Server Logs

# Docker
docker logs netbird-management -f

# Docker Compose
docker compose logs management -f

# With timestamps
docker compose logs --timestamps management

Signal Server

# Set log level
signal --log-level debug --log-file console

# View logs
docker compose logs signal -f

Relay Server

# Configure via environment variable
export NB_LOG_LEVEL=debug
relay

# Docker Compose
services:
  relay:
    image: netbirdio/relay:latest
    environment:
      - NB_LOG_LEVEL=debug

Log Rotation

Docker Compose Log Rotation

Configure in your docker-compose.yml:

x-default: &default
  restart: unless-stopped
  logging:
    driver: json-file
    options:
      max-size: "500m"
      max-file: "2"

services:
  management:
    <<: *default
    image: netbirdio/management:latest

Linux System Log Rotation

Create /etc/logrotate.d/netbird:

/var/log/netbird/*.log {
    daily
    rotate 7
    compress
    delaycompress
    missingok
    notifempty
    create 0640 root root
    sharedscripts
    postrotate
        systemctl reload netbird 2>/dev/null || true
    endscript
}

Structured Logging

NetBird uses structured logging with contextual fields:

Log Format

{
  "time": "2026-03-04T10:30:45Z",
  "level": "info",
  "msg": "peer connected",
  "peer_id": "abc123",
  "account_id": "xyz789",
  "request_id": "req-456"
}

HTTP Request Tracing

All HTTP requests include a unique request ID:

INFO[2026-03-04T10:30:45Z] HTTP request req-abc123: GET /api/peers
INFO[2026-03-04T10:30:45Z] HTTP response req-abc123: status 200

Common Log Patterns

Successful Peer Connection

INFO peer connected: peer=peer-a.netbird.cloud
INFO connection established: type=P2P local=10.0.0.1:51820 remote=192.168.1.100:51820

NAT Traversal Failure

WARN direct connection failed, falling back to relay
INFO connection established: type=Relayed relay=relay.netbird.io:443

Authentication Issues

ERROR failed to authenticate with management server: token expired
INFO attempting to refresh token

Anonymized Logging

Enable anonymization to hide sensitive information:

# Anonymize IPs and domains
netbird status --anonymize
netbird debug bundle --anonymize

# Apply to all commands
export NB_ANONYMIZE=true

Anonymized output:

Peer: peer-a (wg-*****.netbird.cloud)
NetBird IP: 100.**.*.***

Anonymization applies to status output and debug bundles, not to server-side logs.

Log Analysis

Search Logs

# Find all errors
grep "level=error" /var/log/netbird/client.log

# Find specific peer
grep "peer-a.netbird.cloud" /var/log/netbird/client.log

# Connection events
grep "connection established" /var/log/netbird/client.log

Docker Logs

# Filter by level
docker compose logs management | grep "level=error"

# Last 100 lines
docker compose logs --tail=100 management

# Since timestamp
docker compose logs --since="2026-03-04T10:00:00" management

Centralized Logging

Sending to External Systems

Loki (Grafana)

services:
  management:
    logging:
      driver: loki
      options:
        loki-url: "http://loki:3100/loki/api/v1/push"
        loki-retries: "5"
        loki-batch-size: "400"

Fluentd

services:
  management:
    logging:
      driver: fluentd
      options:
        fluentd-address: "localhost:24224"
        tag: "netbird.management"

Syslog

services:
  management:
    logging:
      driver: syslog
      options:
        syslog-address: "tcp://192.168.1.100:514"
        tag: "netbird-management"

Troubleshooting Logging Issues

Check log file permissions

ls -la /var/log/netbird/
# Should be writable by netbird process

Verify log directory exists

mkdir -p /var/log/netbird
chown netbird:netbird /var/log/netbird

Check disk space

df -h /var/log

Test with console output

netbird up --log-file console

Get Started

Architecture

Deployment

Client Setup

Network Management

Security

Operations

Log Levels

Client Logging

Log File Locations

Configure Client Log Level

Set Log Level via Command Line

Available Log Levels

Set Log Level via Environment Variable

Log Output Destinations

Temporary Debug Logging

Server Logging

Management Server

Configure Log Level

Docker Compose Configuration

View Management Server Logs

Signal Server

Relay Server

Log Rotation

Docker Compose Log Rotation

Linux System Log Rotation

Structured Logging

Log Format

HTTP Request Tracing

Common Log Patterns

Anonymized Logging

Log Analysis

Search Logs

Docker Logs

Centralized Logging

Sending to External Systems

Troubleshooting Logging Issues

​Log Levels

​Client Logging

​Log File Locations

​Configure Client Log Level

​Set Log Level via Command Line

​Available Log Levels

​Set Log Level via Environment Variable

​Log Output Destinations

​Temporary Debug Logging

​Server Logging

​Management Server

​Configure Log Level

​Docker Compose Configuration

​View Management Server Logs

​Signal Server

​Relay Server

​Log Rotation

​Docker Compose Log Rotation

​Linux System Log Rotation

​Structured Logging

​Log Format

​HTTP Request Tracing

​Common Log Patterns

​Anonymized Logging

​Log Analysis

​Search Logs

​Docker Logs

​Centralized Logging

​Sending to External Systems

​Troubleshooting Logging Issues

Log Levels

Client Logging

Log File Locations

Configure Client Log Level

Set Log Level via Command Line

Available Log Levels

Set Log Level via Environment Variable

Log Output Destinations

Temporary Debug Logging

Server Logging

Management Server

Configure Log Level

Docker Compose Configuration

View Management Server Logs

Signal Server

Relay Server

Log Rotation

Docker Compose Log Rotation

Linux System Log Rotation

Structured Logging

Log Format

HTTP Request Tracing

Common Log Patterns

Anonymized Logging

Log Analysis

Search Logs

Docker Logs

Centralized Logging

Sending to External Systems

Troubleshooting Logging Issues