SPEC.md

Specifications

This document describes the specifications of log formats.

First of all, a log is structured as key-value pairs.

Strings are UTF-8 strings.

Any formatted log cannot be longer than 1 MiB (1^20 bytes).

Standard keys

These keys are defined as standard.

Key	Type	Mandatory	Description
topic	string	yes	Typically the program name.
logged_at	string	yes	RFC3339 time in microsecond precision.
severity	string	yes	One of "critical", "error", "warning", "info", "debug".
utsname	string	yes	Hostname.
message	string	yes	Log message.
secret	bool	no	true if the log contains secrets.
type	string	no	Type of logs. See the next section.
request_id	string	no	UUID for request tracking.
response_time	float64	no	Seconds elapsed.
remote_ipaddr	string	no	Remote IP address.
url	string	no	Request URI.
protocol	string	no	Protocol such as "HTTP/1.1" or "SOCKS5".
http_method	string	no	HTTP method such as "GET" or "POST".
http_host	string	no	HTTP Host header value.
http_status_code	int	no	HTTP status code such as 200 or 404.
http_referer	string	no	HTTP Referer header value.
http_user_agent	string	no	HTTP User-Agent header value.
request_size	int	no	Request size in bytes.
response_size	int	no	Response size in bytes.

Log types

Following is the current list of log types:

• "access"

  HTTP server access log.

• "exec"

  Command execution results.

• "http"

  HTTP client request log.

Optional keys

Keys other than standard ones can appear in logs.

Such keys must match this regexp: ^[a-z][a-z0-9_]*$

Values may be any type. Formatters should format values appropriately.

Formatters

plain

"plain" is implemented by PlainFormat.

A plain log looks like:

"2010-01-23T11:22:33.012345Z $utsname $topic $severity $msg [key1=value1 ...]"

where $key is the value of key.

logfmt

"logfmt" is implemented by Logfmt.

Logfmt conforms to https://gist.github.com/kr/0e8d5ee4b954ce604bb2 .

JSON

"json" is implemented by JSONFormat.

JSONFormat conforms to JSON Lines.