yaq-yeps/106

Logging for Daemons

YEP:	106
Title:	Logging for Daemons
Authors:	Kyle Sunden
Status:	accepted
Tags:	standard
Post-History:	2020-05-13, 2020-08-14, 2021-02-22

Abstract ¶

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

Table of Contents ¶

Abstract
Table of Contents
Motivation
Specification
Copyright

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 extended timestamp %Y-%m-%dT%H:%M:%S%z 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 ¶

Logging behavior may be configured by the YEP-102 configuration file. Configuration options are:

log_level, default "info"
log_to_file, default false

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.

Daemons SHALL use the log level specified by the entry point, even if log_level is also specified by the configuration.

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 file names MUST begin with the daemon names, followed by a dash -. The files names MUST end with a timestamp (ISO-8601 basic, %Y%m%dT%H%M%S%z), followed by the file extension .log. Files will be located in the operating system's user log directory. Patterns for each supported operating system follow:

macOS: ~/Library/Logs/yaqd-<kind>/<name>-<timestamp>.log
Linux: ~/.cache/yaqd-<kind>/log/<name>-<timestamp>.log
Windows: C:\Users\<User>\AppData\Local\yaq\yaqd-<kind>\Logs\<name>-<timestamp>.log

Daemons SHALL only write log-files when the YEP-102 config option log_to_file is set to true.

Accessing logs over RPC ¶

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

Copyright ¶

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