log

Enables and configures HTTP request logging (also known as access logs).

Syntax

log {
	output <writer_module> ...
	format <encoder_module> ...
	level  <level>
}

• output configures a where to write the logs to. See Output modules below. Default: stderr
• format describes how to encode, or format, the logs. See Format modules below. Default console
• level is the minimum entry level to log. Default: INFO

Output modules

The output subdirective lets you customize where logs get written. It appears within a log block.

stderr

Standard error (console, default).

output stderr

stdout

Standard output (console).

output stdout

discard

No output.

output discard

file

A file. By default, log files are rotated ("rolled") to prevent disk space exhaustion.

output file <filename> {
	roll_disabled
	roll_size     <size>
	roll_keep     <num>
	roll_keep_for <days>
}

• <filename> is the path to the log file.
• roll_disabled disables log rolling. This can lead to disk space depletion, so only use this if your log files are maintained some other way.
• roll_size is the size at which to roll the log file. The current implementation supports megabyte resolution; fractional values are rounded up to the next whole megabyte. For example, 1.1MiB is rounded up to 2MiB. Default: 100MiB
• roll_keep is how many log files to keep before deleting the oldest ones. Default: 10
• roll_keep_for is how long to keep rolled files as a duration string. The current implementation supports day resolution; fractional values are rounded up to the next whole day. For example, 36h (1.5 days) is rounded up to 48h (2 days). Default: 2160h (90 days)

net

A network socket.

output net <address>

• <address> is the address to write logs to.

Format modules

The format subdirective lets you customize how logs get encoded (formatted). It appears within a log block.

In addition to the syntax for each individual encoder, these common properties can be set on most encoders:

format <encoder_module> {
	message_key <key>
	level_key   <key>
	time_key    <key>
	name_key    <key>
	caller_key  <key>
	stacktrace_key <key>
	line_ending  <char>
	time_format  <format>
	level_format <format>
}

• message_key The key for the message field of the log entry. Default: message
• level_key The key for the level field of the log entry. Default: level
• time_key The key for the time field of the log entry. Default: time
• name_key The key for the name field of the log entry (i.e. the name of the logger itself). Default: name
• caller_key The key for the caller field of the log entry.
• stacktrace_key The key for the stacktrace field of the log entry.
• line_ending The line endings to use.
• time_format The format for timestamps.
• level_format The format for levels.

console

The console encoder formats the log entry for human readability while preserving some structure.

format console

json

Formats each log entry as a JSON object.

format json

logfmt

Formats each log entry as logfmt.

format logfmt

single_field

Writes only a single field from the structure log entry. Useful if one of the fields has all the information you need.

format single_field <field_name>

• <field_name> is the name of the field whose value to use as the log entry.

Examples

Enable access logging (to the console):

log

Write logs to a file (with log rolling, which is enabled by default):

log {
	output file /var/log/access.log
}

Customize log rolling:

log {
	output file /var/log/access.log {
		roll_size 1gb
		roll_keep 5
		roll_keep_for 720h
	}
}

Use common log format (deprecated, but can be useful for older setups):

log {
	format single_field common_log
}