Skip to content

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, every get_logger call, and repeated initialize calls. 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 a TypeError and a --- Logging error --- trace.
  • Records from plain logging.Logger instances keep stdlib % formatting. A brace message sent through a plain logger is not formatted.
  • get_logger still registers AppLogger as the logger class. That is the one process-wide change left, and loggers created afterwards are AppLoggers.
  • A handler that bypasses getMessage and applies record.msg % record.args itself does not see the brace rule.

Influences

  • S22.4.1 implements this decision.
  • S22.4.5 recorded the reproductions.

Alternatives considered

  • Compose on retrieval: get_logger wraps 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 calls initialize. It still replaces the consumer's factory whenever initialize runs.
  • Formatter-level braces: formats braces in pykit's plain, Rich and JSON formatters. It loses brace support in any handler that calls getMessage directly, and it needs one change per formatter.