Logging

• Config File
  • Console Logger
  • File Logger
  • Local Socket Logger
  • Differences from JSON
• Log Filters
• Log Formatters

Logging in psinode can be configured at startup in the server's configuration file (found in <DATABASE>/config) or through the HTTP API while the server is running.

Config File

Each logger has a section in the config file called [logger.<NAME>]. The name of the logger is only significant to identify the logger.

[logger.stderr]
type   = console
filter = Severity >= info
format = [{TimeStamp}] [{Severity}]: {Message}

Each logger should have the following properties

Console logger

The console logger writes to the server's stderr. It does not use any additional configuration. There should not be more than one console logger.

File logger

The file logger writes to a named file and optionally provides log rotation and deletion. Multiple file loggers are supported as long as they do not write to the same files.

filename and target can contain patterns which will be used to generate multiple file names. The pattern should result in a unique name or old log files may be overwritten. The paths are relative to the server's root directory.

Both rotation and log deletion trigger when any condition is reached.

When log files are deleted, the oldest logs will be deleted first. All files that match the target pattern are assumed to be log files and are subject to deletion.

Example:

[logger.file]
type         = file
filter       = Severity >= info
format       = [{TimeStamp}]: {Message}
filename     = psibase.log
target       = psibase-%Y%m%d-%N.log
rotationTime = 00:00:00Z
rotationSize = 16 MiB
maxFiles     = 128
maxSize      = 1 GiB

Local socket logger

The socket type local writes to a local datagram socket. Each log record is sent in a single message. With an appropriate format, it can be used to communicate with logging daemons on most unix systems.

Example:

[logger.syslog]
type   = local
filter = Severity >= info
format = {Syslog:glibc}{Message}
path   = /dev/log

Differences from JSON

The config file format is intended to allow manual editing and is therefore more permissive than the JSON format used by the HTTP API, which is designed as a machine-to-machine interface.

• rotationSize and maxSize can specify units, such as KiB, MiB, GiB, etc. The JSON format requires a Number in bytes only.
• A per-channel format is split into multiple properties instead of fields of a subobject. This is a consequence of the flat structure of the INI format.
• TODO: currently rotationTime is pretty human-unfriendly

Log Filters

Every logger has an associated filter. Filters determine whether to output any particular log record.

FILTER      ::= OR-FILTER
OR-FILTER   ::= AND-FILTER ( "or" AND-FILTER ) *
AND-FILTER  ::= ATTR-FILTER ( "and" ATTR-FILTER ) *
ATTR-FILTER ::= "not" ATTR-FILTER
ATTR-FILTER ::= "(" OR-FILTER ")"
ATTR-FILTER ::= ATTR-NAME
ATTR-FILTER ::= ATTR-NAME ATTR-OP ATTR-VALUE
ATTR-NAME   ::= alphanumeric chars
ATTR-VALUE  ::= chars that are neither whitespace nor any of "&|:{}()
ATTR-VALUE  ::= double-quoted string

Examples:

• Everything except debug messages: Severity >= info
• Everything about a specific peer: PeerId = 42
• Warnings, errors, and blocks: Severity >= warning or Channel = block

Log Formatters

Formatters specify how a log record is formatted. The following replacements are performed on the template string:

• {attribute}: If attribute is defined, expands to its textual representation. If attribute is not defined, expands to the empty string.
• {attribute:format-spec}: If attribute is defined, expands to the textual representation specified by format-spec. If attribute is not defined, expands to the empty string.
• {?filter:subformat}: If filter is true, expands subformat. Otherwise, expands to the empty string.
• {?:subformat}: If every attribute in subformat is defined, expands subformat. Otherwise, expands to the empty string.
• {{: Replaced with {
• }}: Replaced with } only outside of any expansion

Examples:

• [{TimeStamp}] [{Severity}]: {Message}
• [{Timestamp}] [{Severity}]{?: [{RemoteEndpoint}]}: {Message}{?: {BlockId}}

Formatters have several attributes beyond those available for filters including several compound formats.

Syslog

The Syslog format creates a syslog header. It should be prepended to the desired message format with no space.

The format-spec for Syslog may contain the following options:

• format: one of bsd (equivalent to rfc3164), rfc3164, rfc5424, glibc. Default is bsd.
• facility: A syslog facility number or keyword. Default is local0.

If both a format and facility are specified, they should be separated by a ;.

Examples:

• {Syslog:local1;rfc5424}
• {Syslog:glibc}: Suitable for writing to /dev/log on linux systems.