doc: Add initial logging requirements spec

1 files changed, 123 insertions, 0 deletions

diff --git a/doc/logging.rst b/doc/logging.rst
new file mode 100644
index 0000000..6e25bf5
--- /dev/null
+++ b/doc/logging.rst
@@ -0,0 +1,123 @@
+======================================
+ Logging Requirements for NETCONF APK
+======================================
+:Author:
+  A. Wilcox
+:Copyright:
+  © 2020 Adélie Software in the Public Benefit, Inc.  NCSA license.
+:Status:
+  Draft
+
+
+
+
+Introduction
+============
+
+This document defines the logging requirements for the NETCONF for APK
+Distributions system.
+
+
+Definition of terms
+-------------------
+
+* `NETCONF APK`: The NETCONF for APK Distributions system, including the
+  base server and modules contained in the netconfapk source distribution.
+
+* `controller server`: A system on the network that runs the NSL
+  Controller system, a presently-undocumented AAA and telemetry system.
+
+* `stdout`: The standard output stream as defined by POSIX.
+
+
+Intended audience
+-----------------
+
+This document is primarily intended to be read by the implementors of
+NETCONF APK.  It may additionally be useful for documentation writers to
+inform network administrators who are interacting with NETCONF APK about
+how its logging system functions.
+
+
+
+
+Architecture
+============
+
+The logging system processes messages with three fields: Category, Level,
+and Message.  The message's Category indicates what subsystem is emitting
+the message.  The message's Level indicates the urgency of the message,
+and may be one of the following five values: Critical, Error, Warning,
+Info, and Debug.  The message's Message is the text being logged.
+
+The system has a "catch-all" log, which by default outputs every message
+processed to `stdout`, with the following format:
+
+    <iso-date> : <category> : <level> : <message>
+
+iso-date is defined as an ISO 8601 extended timestamp, of the format:
+
+    YYYY-MM-DDThh:mm:ss
+
+The administrator may configure one or more outputs for each category,
+including defining one or more explicit outputs for the "catch-all" log.
+
+
+
+
+Configuration
+=============
+
+The `netconf.conf` YAML configuration file will be read for a top-level
+`logging` node, which must be a mapping.  Each key will be interpreted
+as the name of a Category.  The `default` key will configure the "catch-
+all" log.  The value must be either a string scalar, or a sequence of
+string scalars.  Each scalar describes an output location for the
+specified logging category.
+
+Output locations can be of one of the following three types:
+
+* `stdout`.  If the scalar is the exact string "stdout", the specified
+  messages will be written to the standard output stream.
+
+* `file:`.  If the scalar starts with the string "file:", and an absolute
+  path follows the "file:" string, the specified messages will be
+  appended to the file at the specified path.
+
+* `url:`.  If the scalar starts with the string "url:", and an HTTPS URL
+  follows the "url:" string, the specified messages will be sent to the
+  URL specified using the POST HTTP verb.  The log message will be the
+  payload, and the Content-Type will be text/plain.
+
+All messages will additionally be sent to a configured Controller Server.
+This cannot be disabled.
+
+
+
+
+Categories
+==========
+
+The following categories are defined for the NETCONF APK system.
+
+
+auth
+----
+
+Messages in this category concern authentication.  This includes both
+successful and failed authentication attempts to the server.
+
+
+operational
+-----------
+
+Messages in this category concern operations carried out.  This includes
+standard operations such as `edit-config` and also RPCs such as
+`system-restart`.
+
+
+config
+------
+
+Messages in this category concern configuration data.  This includes
+reading and writing to any NETCONF datastore.