[taler-taler-util] branch master updated: add documentation for gnunet_log.py

[gnunet]

This is an automated email from the git hooks/post-receive script.

ttn pushed a commit to branch master
in repository taler-util.

The following commit(s) were added to refs/heads/master by this push:
     new d2e71b0  add documentation for gnunet_log.py
d2e71b0 is described below

commit d2e71b08e062fa198c1ba5634acdb57180744f8c
Author: Thien-Thi Nguyen <ttn@gnuvola.org>
AuthorDate: Thu Feb 10 17:47:39 2022 -0500

    add documentation for gnunet_log.py
---
 doc/doc.org | 82 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 82 insertions(+)

diff --git a/doc/doc.org b/doc/doc.org
index 7834a48..5ad2c5c 100644
--- a/doc/doc.org
+++ b/doc/doc.org
@@ -174,3 +174,85 @@ Lastly, a =SignedAmount= object can flip its sign using a 
unary minus.
 : False
 : >>> (- n).is_positive
 : True
+
+* classes =LogDefinition=, =GnunetLoglevel=
+
+These two classes are deliberately undocumented (until further notice).
+They exist primarily to support the =GnunetLogger= class.
+
+* class =GnunetLogger=
+
+The =GnunetLogger= class wraps the native =logging= module and provides
+two primary entry points: the constructor and the =log= method.
+It supports the usual list of /log levels/:
+=ERROR=, =WARNING=, =INFO=, =DEBUG=.
+
+*** log definition, environment variables
+
+What to log is controlled by a /log definition/, lists of
+which are taken from one or both environment variables when
+the =GnunetLogger= object is initialized:
+
+- =GNUNET_FORCE_LOG=
+- =GNUNET_LOG=
+
+A log definition looks like:
+
+: [component];[file];[function];[from_line[-to_line]];loglevel
+
+The =component=, =file=, =function=, and line information portions
+are optional; the =loglevel= is required.
+No portion may contain the =;= (semicolon) or =/= (slash) character.
+When a portion is omitted, it defaults to /all/ of that item.
+The line information can be a single line number or a range,
+written in =LOW-HIGH= format -- note =-= (hyphen).
+For example, a minimal log definition could be:
+
+: ;;;;ERROR
+
+This example definition matches all components, all files, all
+functions, and all lines, but only the =ERROR= log level.
+
+Multiple log definitions are specified by separating them with a =/=
+(slash) character.
+
+: network;;;ERROR/database;;;DEBUG
+
+The difference between =GNUNET_FORCE_LOG= and =GNUNET_LOG= is that the
+former takes priority over the latter, in case of conflict.
+Also, logging done via =GNUNET_FORCE_LOG= respects environment
+variable =GNUNET_FORCE_LOGFILE=.
+
+*** environment variable =GNUNET_FORCE_LOGFILE=
+
+The filename specified by =GNUNET_FORCE_LOGFILE= can
+have special character sequences replaced (like a template):
+
+- ={}= :: component
+- =[]= :: process id
+- =%Y= :: numeric year
+- =%m= :: numeric month
+- =%d= :: numeric day
+
+For example, if =GNUNET_FORCE_LOGFILE= has value:
+
+: /var/log/[].{}.%Y-%m-%d.error.log
+
+then the expansion might be:
+
+: /var/log/14916.monolith.2022-02-10.error.log
+
+*** constructor
+
+The =GnunetLogger= constructor takes one argument, =component=.
+
+: >>> from taler.util import gnunet_log
+: >>> l = gnunet_log.GnunetLogger ("ui")
+
+*** method =log=
+
+The =log= method takes two arguments, =message= (a string)
+and =message_loglevel= (a property of the =GnunetLogger= class with
+the same name as the string log level).
+
+: >>> l.log ("user clicked button", l.INFO)

-- 
To stop receiving notification emails like this one, please contact
gnunet@gnunet.org.