Logging Module

Configure logging in Caddy with encoders, writers, filters, and custom log outputs

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

JSON

{
  "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.

JSON

{
  "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

JSON

{
  "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

JSON

{
  "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)

JSON

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

Cookie Filter

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"])

JSON

{
  "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"
                }
              ]
            }
          }
        }
      }
    }
  }
}