Package: zrlog
Zirconium Logging (ZrLog)Logging configuration is often complex and Python is missing a few "nice" features that exist in
other languages logging systems. This package hopes to simplify the experience of configuring logging while adding a few
nice features:Loading logging configuration from TOML or YAML (viazirconium) instead of the olderconfigparserformatTRACElevel for very fine-grained output (more so thatDEBUG)NOTICElevel for normal conditions that should always be outputOUTlevel for logging user messagesAUDITlevel for interacting with Python's audit hooksA threaded audit hook that logs most audit messagesThe ability to disable stack trace outputThe ability to set context-specific "extra" variables on all loggers and to provide defaults for these
so that they can be added to all logging messages within that context (e.g. for usernames)Basic Usage# Do this at the start of any run of your codeimportzrlog# Imports logging configuration from TOML and sets up the logging system for you.zrlog.init_logging()# Set a default usernamezrlog.set_default_extra('username','**anonymous**')# logging.getLogger() works as well, this version is a wrapper that (a) makes sure that `zrlog.init_logging()` was# called and (b) provides a better type hint for the logger class.logger=zrlog.get_logger(__name__)Configuration FileBy default, logging configuration comes from a TOML file in up to three places:[HOME_DIRECTORY]/.logging.toml[CURRENT_WORKING_DIRECTORY]/.logging.tomlValue of theZRLOG_CONFIG_FILEenvironment variable. This file may also be a YAML or other formats supported byzirconiumIf you usezirconiumfor your project configuration, it can also be in any configuration file specified by your
project.The logging configuration file is similar to that defined bylogging.config.dictConfig(), with a few extensions. See
the.logging.example.tomlfile for configuration.Performance impactTesting suggests that the impact of replacing the typicalloggingapproach with this module is about 14% slower to
get a logger and 10% slower to make a logging call with extras. However, the time to make a log tostdoutis
still only 0.013 ms (compared to 0.012 ms for the standard logging package), therefore this performance impact is
probably insignificant in most use cases.Log Level RecommendationsLevelUse CasecriticalAn error so severe has occurred that the application may now crash.errorAn error has occurred and may have created unexpected behaviour.warningSomething unexpected happen but it is recoverable, or a problem may occur in the future.noticeSomething expected has happened that needs to be tracked in a production environment (e.g. user login).outSomething expected has happened in a command line environment that the user needs to be notified of.infoSomething expected has happened that does not need tracking but can be useful to confirm normal operation.debugAdditional detail for debugging an issuetraceEven more detail for debugging an issueauditPython auditing output onlyLogging Audit EventsThis package provides a system for turningsys.audit()events into log records using a thread-based queue. This is
necessary because audit events don't play nicely with the logging subsystem, leading to inconsistent errors if the
loggerlog()method is called directly from the audit hook. Audit logging must be enabled specifically by setting
thewith_auditflag:# .logging.toml[logging]with_audit=trueWhile the default level is "AUDIT", you can change this to any of the logging level prefixes by specifying the
audit_level:# .logging.toml[logging]with_audit=trueaudit_level="INFO"One specific event can cause further problems:sys._getframe()is called repeatedly from the logging subsystem in Python
(in 3.8 at least). These audit events are NOT logged by default, but logging of them can be enabled by turning off theomit_logging_framesflag.# .logging.toml[logging]with_audit=trueomit_logging_frames=falseAudit events are logged (by default) at the AUDIT level which is below TRACE; your logger and handler must be set to that level to
see these events:[logging.root]level="AUDIT"handlers=["console"][logging.handlers.console]class="logging.StreamHandler"formatter="brief"level="AUDIT"stream="ext://sys.stdout"Change Logversion 0.3.0Added logger extra handling viaset_logger_extraandset_default_logger_extraAdded theNOTICElevel to correspond with more typical usage.OUTshould be used for user output where it needs
to be logged andNOTICEfor normal conditions that need to be logged even in production.version 0.2.0Updated the audit handling thread to use athreading.Eventto end itself rather than a boolean flag.Added theno_configflag, mostly to be used in test suites to ensure everything still works properly.Several documentation cleanup items