yaq-yeps/106


Logging for Daemons

Table of Contents

Abstract

This YEP defines a consistent logging format for yaq daemons. This extends to the file storage and access over the RPC.

Motivation

A consistent logging format is desirable for this ecosystem as it allows instant familiarity when using/debugging, external tools can easily be built to filter log messages appropriately, and logs can be stored and reviewed easily.

Specification

Levels

The levels used are those as defined by sd-daemon and syslogv.

emergency  "<0> EMERG"   :  system is unusable
alert      "<1> ALERT"   :  action must be taken immediately
critical   "<2> CRIT"    :  critical conditions
error      "<3> ERR"     :  error conditions
warning    "<4> WARNING" :  warning conditions
notice     "<5> NOTICE"  :  normal but significant condition
info       "<6> INFO"    :  informational
debug      "<7> DEBUG"   :  debug-level messages

Using these levels allows seamless integration with systemd and other daemon management programs.

Format

Individual log entries SHALL be of the format:

{level} : {timestamp} : {name} : {message}

Where {level} is the log level, with the numeric prefix and the abbreviation for readability (e.g. <6> INFO), {timestamp} is a valid ISO-8601 timestamp with at least second precision and timezone specified, {name} is the name of the specific daemon which initiated the log entry (or yaqd_core if it was initiated outside of a daemon) and {message} is an arbitrary message string.

For example:

<4> WARNING : 2020-05-13T23:28:25Z : my-daemon : This is a warning you might want to know about

Configuration

By default, only logs at the INFO level or above are recorded. Individual daemons may set their own log level using the YEP-102 configuration parameter "log_level", set to the string name given by the first column above.

Entry point

This section extends YEP-104. Daemon entry points MUST have the option to override the configuration file. There SHALL be --verbose and the short form -v which indicates debug log level. There SHALL be --log-level and the short form -l which takes the string name given by the first column above.

Storing logs

Because the log format was chosen to work well with external systems, some users may opt to record logs using external tools which read the stderr output. However, an internal implementation of log file storage SHALL be provided. The files MUST be timestamped (ISO-8601 with second precision and offset) and located in the same folder as the YEP 103 state files. The file names MUST begin with the daemon names.

For example:

macOS: `~/Library/Application Support/yaqd-state/<kind>/<name>-<timestamp>.log`
Linux: $XDG_DATA_DIR/yaqd-state/<kind>/<name>-<timestamp>.log
Windows: `C:\Users\<User>\AppData\Local\yaq\yaqd-state\<kind>\<name>-<timestamp>.log`

Accessing logs over RPC

A future version of this YEP will specify the RPC log access.

Discussion

Discussion can be found on the gitlab issue for this YEP.

Copyright

This document is placed in the public domain or under the CC0-1.0-Universal license, whichever is more permissive.


built 2020-05-20 22:19:23                                      CC0: no copyright