User Guide

http.log

log enables request logging. The request log is also known from some vernaculars as an access log.

Syntax

With no arguments, an access log is written to access.log in the common log format for all requests:

Customize the log file location:

• file is the path to the log file to create (or append to), relative to the current working directory. See Log Destination for more details about how to specify an output location. Default is access.log.

To restrict this log to certain requests or to change the log format:

• path is the base request path to match in order to be logged.
• file is the log file to create (or append to), relative to current working directory.
• format is the log format to use; default is Common Log Format.

Large log files are rolled automatically. You can customize log rolling or other things by opening a block:

• rotate_size is the size in megabytes a log file must reach before rolling it.
• rotate_age is how long in days to keep rotated log files.
• rotate_keep is the maximum number of rotated log files to keep; older rotated log files get pruned.
• rotate_compress is the option to compress rotated log files. gzip is the only format supported.
• ipmask enables masking IP addresses to comply with corporate or legal restrictions. The first argument is a mask for IPv4 addresses, and the second argument is a mask for IPv6 addresses. The IPv6 mask is optional; and if only IPv6 is to be masked, the IPv4 mask can be an empty string token.
• except exempts requests by path from being logged. More than one path can be specified per line (space-separated), if desired, or this subdirective can be used multiple times.

Log Format

You can specify a custom log format with any placeholder values. Log supports both request and response placeholders.

Currently there are two predefined formats.

• {common} (default) {remote} - {user} [{when}] \"{method} {uri} {proto}\" {status} {size}
• {combined} - {common} appended with \"{>Referer}\" \"{>User-Agent}\"

Log Destination

The log destination can be one of a few things:

• a filename relative to the current working directory
• stdout or stderr to write to the console
• syslog to write to the local system log (except on Windows)
• syslog://host[:port] to write via UDP to a local or remote syslog server
• syslog+udp://host[:port] is the same as above
• syslog+tcp://host[:port] to write via TCP to local or remote syslog server

Log Rolling

Logs have the potential to fill the disk. To mitigate this, request logs are rotated ("rolled") automatically according to this default configuration:

You can specify these subdirectives to customize log rolling.

Examples

Log all requests to access.log:

Log all requests to stdout:

Custom log format:

Predefined format:

With rotation:

log requests.log { rotate_size 50 # Rotate after 50 MB rotate_age 90 # Keep rotated files for 90 days rotate_keep 20 # Keep at most 20 log files rotate_compress # Compress rotated log files in gzip format }

To mask (anonymize) IPv4 addresses and IPv6 addresses down to a couple octets:

log requests.log { ipmask 255.255.0.0 ffff:ffff:ffff:ff00:: }