Logging

Logging provides:

  1. JGDVLogConfig, which sets up various loggers, using TOML defined specs.

  2. ColourFormatter for adding colour to stdout,

  3. Filters,

  4. A StackFormatter_m mixin, using stackprinter for simplifying the formatting of logging, to print error stack traces a bit nicer.

Toml Specs

[logging]
[logging.stream]
level   = "user"
filter  = []
target  = "stdout"
format  = "{levelname:<8}  : {message}"

[logging.file]
level        = "trace"
filter       = []
target       = "rotate"
format       = "{levelname:<8} : {message:<20} :|: ({module}.{lineno}.{funcName})"
filename_fmt = "doot.log"

[logging.printer]
level        = "NOTSET"
colour       = true
target       = ["stdout", "rotate"]
format       = "{message}"
filename_fmt = "doot_printed.log"

[logging.extra]

# TODO

There are 4 key sorts of Toml specified loggers: 1. The stream logger, for logging messages that escalate to output on stdout or stderr. 2. The file logger, for all messages, which will be written to a file. 3. The printer logger, a replacement for print. ie: It is what the user sees during normal operation, but in a way the logging architecture can control it rather than straight print``ing to ``stdout. 4. extra loggers. These are for customising the logger of any module you want. eg: jgdv.decorators, or sphinx, or networkx.digraph.

The Log Config

The JGDVLogConfig is for taking loaded TOML specs of loggers, and applying them.

from pathlib import Path
from jgdv.structs.chainguard import ChainGuard
from jgdv.logging import JGDVLogConfig

data    = ChainGuard.load(Path("data/specs.toml"))
config  = JGDVLogConfig()
config.setup(data)
config.set_level("DEBUG")

Personal Logging Levels

After reading Nicole Tietz’s The only two log levels you need are info and error, I prefer a different log level hierarchy than the default Python Levels. They are, from highest to lowest:

  1. Error : For when things go really wrong.

  2. User : Things the user should see.

  3. Trace : Landmarks to track program execution paths.

  4. Detail : Actual values for use in debuggging.

and

  1. Bootstrap : For before the logging is fully set up.