Logging Module

The logging module provides comprehensive structured logging capabilities for Caddy. By default, all logs at INFO level and higher are written to standard error in a human-readable format.

Overview

Caddy’s logging system is:

Zero-allocation - High performance in terms of memory and CPU time
Structured - Built on top of Uber’s Zap logging library
Flexible - Multiple logs with different outputs and filters
Filterable - Filter by level and module/logger names

Configuration

Basic Logging Structure

{
  "logging": {
    "sink": {
      "writer": {
        "output": "stderr"
      }
    },
    "logs": {
      "default": {
        "level": "INFO",
        "writer": {
          "output": "file",
          "filename": "/var/log/caddy/access.log"
        },
        "encoder": {
          "format": "json"
        }
      }
    }
  }
}

Log Encoders

Encoders determine how log entries are formatted.

Console Encoder

Module ID: caddy.logging.encoders.console Encodes log entries in a human-readable format.

message_key

string

The key name for the log message. Default: msg

level_key

string

The key name for the log level. Default: level

time_key

string

The key name for the timestamp. Default: ts

name_key

string

The key name for the logger name. Default: logger

caller_key

string

The key name for the caller information. Default: caller

stacktrace_key

string

The key name for stack traces. Default: stacktrace

line_ending

string

The character(s) to use for line endings. Default: \n

time_format

string

Time format for timestamps. Options:

unix_seconds_float - Unix timestamp as float (default)
unix_milli_float - Unix timestamp in milliseconds as float
unix_nano - Unix timestamp in nanoseconds
iso8601 - ISO8601 format
rfc3339 - RFC3339 format
rfc3339_nano - RFC3339 with nanoseconds
wall - Wall clock time (2006/01/02 15:04:05)
wall_milli - Wall clock with milliseconds
wall_nano - Wall clock with nanoseconds
common_log - Common log format (02/Jan/2006:15:04:05 -0700)
Custom Go time layout string

time_local

boolean

Use local timezone instead of UTC. Default: false

duration_format

string

Format for durations:

s, second, seconds - Seconds (default)
ns, nano, nanos - Nanoseconds
ms, milli, millis - Milliseconds
string - String representation

level_format

string

Format for log levels:

lower - lowercase (default)
upper - UPPERCASE
color - Color-coded (console only)

JSON Encoder

Module ID: caddy.logging.encoders.json Encodes log entries as JSON. Accepts the same configuration parameters as the console encoder.

{
  "encoder": {
    "format": "json",
    "time_format": "rfc3339",
    "level_format": "lower"
  }
}

Log Writers

Writers determine where log output is sent.

File Writer

Module ID: caddy.logging.writers.file Writes logs to files with automatic rotation.

filename

string

required

Path to the log file

mode

string

File permissions mode (octal). Default: 0600

dir_mode

string

Directory permissions mode. Options:

Octal string (e.g., 0755)
inherit - Copy nearest parent directory permissions
from_file - Derive from file mode (e.g., 0644 → 0755)

Default: 0700

roll

boolean

Enable log rotation. Default: true

roll_size_mb

integer

Maximum log file size in megabytes before rotation. Default: 100

roll_interval

duration

Time interval for log rotation (e.g., 24h, 1h30m)

roll_minutes

array of integers

Minutes of each hour to rotate logs. Example: [0, 30] rotates at xx:00 and xx:30

roll_at

array of strings

Times of day to rotate logs. Example: ["00:00", "12:00"] rotates at midnight and noon

roll_compression

string

Compression algorithm for rotated files:

gzip (default)
zstd
none

roll_local_time

boolean

Use local time in rotated filenames. Default: false

roll_keep

integer

Maximum number of rolled log files to keep. Default: 10

roll_keep_days

integer

Maximum number of days to keep rolled log files. Default: 90

backup_time_format

string

Go time format for rotated filenames. Default: 2006-01-02T15-04-05.000

{
  "writer": {
    "output": "file",
    "filename": "/var/log/caddy/access.log",
    "roll_size_mb": 100,
    "roll_keep": 20,
    "roll_keep_days": 90,
    "roll_compression": "gzip"
  }
}

Network Writer

Module ID: caddy.logging.writers.net Writes logs to a network socket. If the connection fails, logs are dumped to stderr.

address

string

required

Network address to connect to (e.g., localhost:514, syslog.example.com:514)

dial_timeout

duration

Timeout for connecting to the socket

soft_start

boolean

Allow connection errors when first opening the writer. Logs will go to stderr until connection succeeds. Default: false

{
  "writer": {
    "output": "net",
    "address": "localhost:514",
    "dial_timeout": "5s",
    "soft_start": true
  }
}

Standard Writers

Standard output writers are built-in and require no configuration.

stdout - caddy.logging.writers.stdout - Writes to standard output
stderr - caddy.logging.writers.stderr - Writes to standard error (default)
discard - caddy.logging.writers.discard - Discards all logs

Log Filters

Filters manipulate or redact log fields.

Delete Filter

Module ID: caddy.logging.encoders.filter.delete Deletes a log field entirely.

Hash Filter

Module ID: caddy.logging.encoders.filter.hash Replaces field value with first 4 bytes of SHA-256 hash.

Replace Filter

Module ID: caddy.logging.encoders.filter.replace

value

string

required

Replacement value

IP Mask Filter

Module ID: caddy.logging.encoders.filter.ip_mask Masks IP addresses to protect privacy.

ipv4_cidr

integer

IPv4 CIDR subnet size for masking (e.g., 16 masks last two octets)

ipv6_cidr

integer

IPv6 CIDR subnet size for masking

Query Filter

Module ID: caddy.logging.encoders.filter.query Filters query parameters from URLs.

actions

array of objects

List of actions to apply to query parameters:

type: replace, hash, or delete
parameter: Query parameter name
value: Replacement value (for replace type)

{
  "filter": "query",
  "actions": [
    {
      "type": "delete",
      "parameter": "token"
    },
    {
      "type": "replace",
      "parameter": "api_key",
      "value": "REDACTED"
    }
  ]
}

Module ID: caddy.logging.encoders.filter.cookie Filters cookies from HTTP headers.

actions

array of objects

List of actions to apply to cookies:

type: replace, hash, or delete
name: Cookie name
value: Replacement value (for replace type)

Regexp Filter

Module ID: caddy.logging.encoders.filter.regexp Replaces content matching a regular expression.

regexp

string

required

Regular expression pattern

value

string

Replacement value

Rename Filter

Module ID: caddy.logging.encoders.filter.rename

name

string

required

New field name

Log Levels

Available log levels (from lowest to highest priority):

DEBUG - Detailed debugging information
INFO - General informational messages (default)
WARN - Warning messages
ERROR - Error messages
PANIC - Panic-level messages
FATAL - Fatal messages (causes program termination)

Custom Logs

Define multiple logs with different configurations:

include

array of strings

Logger names to include (e.g., ["admin.api", "http.handlers"])

exclude

array of strings

Logger names to exclude (e.g., ["http.log.access"])

{
  "logging": {
    "logs": {
      "default": {
        "level": "INFO",
        "exclude": ["http.log.access"]
      },
      "access": {
        "writer": {
          "output": "file",
          "filename": "/var/log/caddy/access.log"
        },
        "encoder": {
          "format": "json"
        },
        "include": ["http.log.access"]
      }
    }
  }
}

Sampling

Enable log sampling to improve performance on high-load servers:

interval

duration

Sampling window duration. Default: 1s

first

integer

Number of entries to log within each interval. Default: 100

thereafter

integer

After first entries, keep 1 in this many entries. Default: 100

{
  "sampling": {
    "interval": "1s",
    "first": 100,
    "thereafter": 100
  }
}

Examples

Production JSON Logging

{
  "logging": {
    "logs": {
      "default": {
        "level": "INFO",
        "writer": {
          "output": "file",
          "filename": "/var/log/caddy/caddy.log",
          "roll_size_mb": 100,
          "roll_keep": 10
        },
        "encoder": {
          "format": "json",
          "time_format": "rfc3339"
        }
      }
    }
  }
}

Redact Sensitive Data

{
  "logging": {
    "logs": {
      "default": {
        "encoder": {
          "format": "filter",
          "wrap": {
            "format": "json"
          },
          "fields": {
            "request>headers>Authorization": {
              "filter": "delete"
            },
            "request>headers>Cookie": {
              "filter": "cookie",
              "actions": [
                {
                  "type": "hash",
                  "name": "session_id"
                }
              ]
            }
          }
        }
      }
    }
  }
}

HTTP

TLS

Other Modules

Logging Module

Overview

Configuration

Basic Logging Structure

Log Encoders

Console Encoder

JSON Encoder

Log Writers

File Writer

Network Writer

Standard Writers

Log Filters

Delete Filter

Hash Filter

Replace Filter

IP Mask Filter

Query Filter

Regexp Filter

Rename Filter

Log Levels

Custom Logs

Sampling

Examples

Production JSON Logging

Redact Sensitive Data

Build docs developers (and LLMs) love

HTTP

TLS

Other Modules

​Overview

​Configuration

​Basic Logging Structure

​Log Encoders

​Console Encoder

​JSON Encoder

​Log Writers

​File Writer

​Network Writer

​Standard Writers

​Log Filters

​Delete Filter

​Hash Filter

​Replace Filter

​IP Mask Filter

​Query Filter

​Cookie Filter

​Regexp Filter

​Rename Filter

​Log Levels

​Custom Logs

​Sampling

​Examples

​Production JSON Logging

​Redact Sensitive Data

Build docs developers (and LLMs) love

Overview

Configuration

Basic Logging Structure

Log Encoders

Console Encoder

JSON Encoder

Log Writers

File Writer

Network Writer

Standard Writers

Log Filters

Delete Filter

Hash Filter

Replace Filter

IP Mask Filter

Query Filter

Cookie Filter

Regexp Filter

Rename Filter

Log Levels

Custom Logs

Sampling

Examples

Production JSON Logging

Redact Sensitive Data