ADR-0016: AppLogger formats braces on its own records and never replaces the process record factory
Status: accepted (2026-11-14) · Scope: rn_forge.commons.logging and
every package that logs through AppLogger
Decision
AppLogger brace-formats only the records its own loggers make.
AppLogger.makeRecord builds each record through whatever factory is installed,
then gives that record BraceLogRecord's message rule: %-style when the
message contains %, otherwise str.format. Neither get_logger nor
initialize calls logging.setLogRecordFactory. BraceLogRecord stays public,
for callers who choose to install it themselves.
Consequences
- A consumer's record factory, such as a tracing factory that adds
trace_id, survives importing any pykit package, everyget_loggercall, and repeatedinitializecalls. Its fields reach pykit's records too. - pykit's brace-style messages format whether or not the application calls
initialize. Today, without the global factory, each one that reaches a handler is aTypeErrorand a--- Logging error ---trace. - Records from plain
logging.Loggerinstances keep stdlib%formatting. A brace message sent through a plain logger is not formatted. get_loggerstill registersAppLoggeras the logger class. That is the one process-wide change left, and loggers created afterwards areAppLoggers.- A handler that bypasses
getMessageand appliesrecord.msg % record.argsitself does not see the brace rule.
Influences
Alternatives considered
- Compose on retrieval:
get_loggerwraps the installed factory. It still mutates process state at import time, changes the factory's identity on every call, and needs detection of double wraps. - Install only from
initialize: removes the import-time overwrite, but breaks every pykit brace message in an application that configures logging itself and never callsinitialize. It still replaces the consumer's factory wheneverinitializeruns. - Formatter-level braces: formats braces in pykit's plain, Rich and JSON
formatters. It loses brace support in any handler that calls
getMessagedirectly, and it needs one change per formatter.