lib_log_rich
One logging runtime per process fans every event out to the console (Rich), journald, the
Windows Event Log and Graylog, each with its own threshold, after scrubbing secrets and
recording it in a ring buffer you can dump. Configuration is one RuntimeConfig; every field
has a LOG_* environment override, and the environment always wins over code.
Use the Read tool to load the reference file for the area you are working in; this page is the
common path and the traps.
Install
uv add lib_log_rich # or: uv pip install lib_log_rich
uv add "lib_log_rich[journald]" # optional systemd-python bindings; journald works without them
uv add "lib_log_rich[eventlog]" # Windows Event Log: pulls pywin32 on Windows
uv add "lib_log_rich[orjson]" # normal (GIL) Python 3.14+: adds orjson, which a plain install there lacks; below 3.14 orjson is a core dependency
# Free-threaded builds: lib_log_rich supports 3.14t and 3.15t and encodes with stdlib json there; never add
# [orjson] on them (orjson refuses to build free-threaded). lib_log_rich itself does not install on 3.13t.
The correct shape
import lib_log_rich as log
config = log.RuntimeConfig(service="billing", environment="prod")
log.init(config) # once per process; a second init() raises RuntimeError
try:
logger = log.getLogger(__name__)
with log.bind(job_id="nightly", request_id="r-42"):
logger.info("charged %s", "acme", extra={"amount": 12})
finally:
log.shutdown() # drains the queue; inside an event loop: await log.shutdown_async()
attach_std_logging, is_initialised and inspect_runtime live in lib_log_rich.runtime, not
on the package root. The enums settings and results use (ConsoleStream, ConsoleTheme, FormatPreset,
GraylogProtocol, QueuePolicy, DumpFormat, ExportStyle, DropReason, LogLevel) live in lib_log_rich.domain;
ConsoleTheme, DumpFormat, FormatPreset and GraylogProtocol are also importable from lib_log_rich itself.
RuntimeConfig, the LOG_* variables and the CLI also accept their value strings. dump() refuses them for theme and
console_format_preset, and logdemo() for those two plus dump_format_preset (dump() has no such argument): a plain string raises
TypeError: theme must be a member of ConsoleTheme, got 'neon' (dump()'s dump_format and level take strings too). bind() takes only the context
fields (job_id, request_id, user_id, trace_id, ...) plus extra={...} for anything else.
Defaults that bite
| Symptom |
Cause and fix |
| Last lines (or all lines) missing at exit |
The queue is on by default and nothing drains it at exit (no atexit hook). Always shutdown() in finally, or queue_enabled=False for short scripts. |
| A code change to a level has no effect |
A LOG_* variable is set; environment beats keyword arguments. |
Stdlib DEBUG records never arrive |
The stdlib root logger stays at WARNING. Call lib_log_rich.runtime.attach_std_logging() after init(); it lowers the root level to the lowest threshold among enabled sinks. A logger with propagate=False needs attach_std_logging(logger=that_logger). |
api_key, api_token reach the sinks |
Default scrubbing covers only the field names password, secret, token (exact, case-insensitive). Add scrub_patterns={"api_key": r".+"}. Messages are never scrubbed. |
| Forked worker logs nothing |
A forked child inherits a dead queue worker. Use spawn, call init() in each worker, carry context with current_runtime().binder.serialize(). |
| Same line twice under systemd |
systemd copies the service's stderr into the journal. With journald on, set LOG_CONSOLE_STREAM=none, or accept that records at or above console_level appear twice (plain and structured). |
| Graylog enabled, nothing arrives |
An unreachable server drops events (no buffer, one TCP retry). enable_graylog without an endpoint is refused by init(). |
Thresholds: console_level (default INFO), backend_level for journald and the Event Log
(WARNING), graylog_level (WARNING). Level names are case-insensitive.
Deploy
One configuration is safe everywhere: journald is forced off on Windows and the Event Log off
elsewhere. Set per host through the environment, never by editing code:
# /etc/myapp/logging.env, loaded by EnvironmentFile= in myapp.service
LOG_ENVIRONMENT=prod
LOG_ENABLE_JOURNALD=1
LOG_BACKEND_LEVEL=WARNING
LOG_CONSOLE_STREAM=none
LOG_ENABLE_GRAYLOG=1
LOG_GRAYLOG_ENDPOINT=graylog.example.com:12201
LOG_GRAYLOG_TLS=1
LOG_SCRUB_PATTERNS=api_key=.+,authorization=.+
Container: LOG_CONSOLE_STREAM=stdout, LOG_NO_COLOR=1, journald off, Graylog as the central
sink. Windows service: LOG_ENABLE_EVENTLOG=1 plus the eventlog extra (pywin32), and register the event source once
with admin rights (the adapter never does). TLS needs TCP; TLS over UDP is refused when Graylog is enabled with an endpoint
(with Graylog off the combination is accepted).
Check a config without stopping logging
try:
candidate = log.RuntimeConfig(**new_settings) # ValidationError (a ValueError): unknown theme, stream, preset, misspelled field name, ...
log.validate_config(candidate) # init()'s verdict, no runtime touched
except ValueError as exc: # "Invalid runtime settings: console_level: Unknown log level: 'loud'"
logger.error("reload refused: %s", exc)
else:
log.shutdown()
log.init(candidate)
logger = log.getLogger(__name__) # proxies from before shutdown() keep writing to the old runtime
It applies the same LOG_* overrides init() would, read from the current os.environ. There is
no in-place reconfigure: switching means shutdown() then init(). Do that from the main loop, never
inside a signal handler: set a flag in the handler. The same goes for the final shutdown(): let a stop signal set a
flag or raise SystemExit, and let the finally call it.
Reference files
| Topic |
Distilled reference |
Upstream (latest docs) |
| Configuration - every RuntimeConfig field and LOG_* variable, precedence, env parsing, levels, .env loading, validate_config, scrubbing, payload limits, rate limiting, ring buffer size |
configuration.md |
README Runtime Reference, DOTENV.md |
| Sinks and deployment - console streams, presets, colour, journald, Windows Event Log, Graylog/GELF, platform guards, OpenTelemetry status, systemd unit, container, Windows service, production checklist |
sinks-and-deployment.md |
INSTALL.md, INSTALL_JOURNAL.md, CONSOLESTYLES.md |
| Runtime and integration - init/shutdown/flush lifecycle, LoggerProxy, bind context in threads and asyncio, stdlib bridge, queue policies, multiprocessing, streaming console adapters, severity metrics, testing |
runtime-and-integration.md |
QUEUE.md, SUBPROCESSES.md, STREAMINGCONSOLE.md, DIAGNOSTIC.md |
| Dumps and CLI - ring buffer, dump() formats, filters, template placeholders, crash-dump recipe, lib_log_rich CLI, logdemo, stress test |
dumps-and-cli.md |
LOGDUMP.md, CLI.md |
For the installed version's own truth, run lib_log_rich --help and
python -c "import lib_log_rich; help(lib_log_rich.RuntimeConfig)". Where an upstream page and a
reference file here disagree, run the behaviour: the reference files are written against the code.
1---2name: coding-python-logging3description: Use when a Python application or CLI logs through lib_log_rich, or needs structured logging to several sinks at once - Rich console, systemd journald, the Windows Event Log, Graylog/GELF - with context binding, secret scrubbing and ring-buffer dumps; when deploying such an app to a systemd host, a container or a Windows service and setting LOG_* overrides; when stdlib records or the last lines at exit go missing, or a reloaded logging config must be checked without restarting logging.4metadata:5 source: https://skillmd.com/skills/bitranox/coding-python-logging6---78# lib_log_rich910One logging runtime per process fans every event out to the console (Rich), journald, the11Windows Event Log and Graylog, each with its own threshold, after scrubbing secrets and12recording it in a ring buffer you can dump. Configuration is one `RuntimeConfig`; every field13has a `LOG_*` environment override, and **the environment always wins over code**.1415Use the Read tool to load the reference file for the area you are working in; this page is the16common path and the traps.1718## Install1920```bash21uv add lib_log_rich # or: uv pip install lib_log_rich22uv add "lib_log_rich[journald]" # optional systemd-python bindings; journald works without them23uv add "lib_log_rich[eventlog]" # Windows Event Log: pulls pywin32 on Windows24uv add "lib_log_rich[orjson]" # normal (GIL) Python 3.14+: adds orjson, which a plain install there lacks; below 3.14 orjson is a core dependency25# Free-threaded builds: lib_log_rich supports 3.14t and 3.15t and encodes with stdlib json there; never add26# [orjson] on them (orjson refuses to build free-threaded). lib_log_rich itself does not install on 3.13t.27```2829## The correct shape3031```python32import lib_log_rich as log3334config = log.RuntimeConfig(service="billing", environment="prod")35log.init(config) # once per process; a second init() raises RuntimeError36try:37 logger = log.getLogger(__name__)38 with log.bind(job_id="nightly", request_id="r-42"):39 logger.info("charged %s", "acme", extra={"amount": 12})40finally:41 log.shutdown() # drains the queue; inside an event loop: await log.shutdown_async()42```4344`attach_std_logging`, `is_initialised` and `inspect_runtime` live in `lib_log_rich.runtime`, not45on the package root. The enums settings and results use (`ConsoleStream`, `ConsoleTheme`, `FormatPreset`,46`GraylogProtocol`, `QueuePolicy`, `DumpFormat`, `ExportStyle`, `DropReason`, `LogLevel`) live in `lib_log_rich.domain`;47`ConsoleTheme`, `DumpFormat`, `FormatPreset` and `GraylogProtocol` are also importable from `lib_log_rich` itself.48`RuntimeConfig`, the `LOG_*` variables and the CLI also accept their value strings. `dump()` refuses them for `theme` and49`console_format_preset`, and `logdemo()` for those two plus `dump_format_preset` (`dump()` has no such argument): a plain string raises50`TypeError: theme must be a member of ConsoleTheme, got 'neon'` (`dump()`'s `dump_format` and `level` take strings too). `bind()` takes only the context51fields (`job_id`, `request_id`, `user_id`, `trace_id`, ...) plus `extra={...}` for anything else.5253## Defaults that bite5455| Symptom | Cause and fix |56|-------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|57| Last lines (or all lines) missing at exit | The queue is on by default and nothing drains it at exit (no atexit hook). Always `shutdown()` in `finally`, or `queue_enabled=False` for short scripts. |58| A code change to a level has no effect | A `LOG_*` variable is set; environment beats keyword arguments. |59| Stdlib `DEBUG` records never arrive | The stdlib root logger stays at `WARNING`. Call `lib_log_rich.runtime.attach_std_logging()` after `init()`; it lowers the root level to the lowest threshold among enabled sinks. A logger with `propagate=False` needs `attach_std_logging(logger=that_logger)`. |60| `api_key`, `api_token` reach the sinks | Default scrubbing covers only the field names `password`, `secret`, `token` (exact, case-insensitive). Add `scrub_patterns={"api_key": r".+"}`. Messages are never scrubbed. |61| Forked worker logs nothing | A forked child inherits a dead queue worker. Use `spawn`, call `init()` in each worker, carry context with `current_runtime().binder.serialize()`. |62| Same line twice under systemd | systemd copies the service's stderr into the journal. With journald on, set `LOG_CONSOLE_STREAM=none`, or accept that records at or above `console_level` appear twice (plain and structured). |63| Graylog enabled, nothing arrives | An unreachable server drops events (no buffer, one TCP retry). `enable_graylog` without an endpoint is refused by `init()`. |6465Thresholds: `console_level` (default INFO), `backend_level` for journald and the Event Log66(WARNING), `graylog_level` (WARNING). Level names are case-insensitive.6768## Deploy6970One configuration is safe everywhere: journald is forced off on Windows and the Event Log off71elsewhere. Set per host through the environment, never by editing code:7273```ini74# /etc/myapp/logging.env, loaded by EnvironmentFile= in myapp.service75LOG_ENVIRONMENT=prod76LOG_ENABLE_JOURNALD=177LOG_BACKEND_LEVEL=WARNING78LOG_CONSOLE_STREAM=none79LOG_ENABLE_GRAYLOG=180LOG_GRAYLOG_ENDPOINT=graylog.example.com:1220181LOG_GRAYLOG_TLS=182LOG_SCRUB_PATTERNS=api_key=.+,authorization=.+83```8485Container: `LOG_CONSOLE_STREAM=stdout`, `LOG_NO_COLOR=1`, journald off, Graylog as the central86sink. Windows service: `LOG_ENABLE_EVENTLOG=1` plus the `eventlog` extra (`pywin32`), and register the event source once87with admin rights (the adapter never does). TLS needs TCP; TLS over UDP is refused when Graylog is enabled with an endpoint88(with Graylog off the combination is accepted).8990## Check a config without stopping logging9192```python93try:94 candidate = log.RuntimeConfig(**new_settings) # ValidationError (a ValueError): unknown theme, stream, preset, misspelled field name, ...95 log.validate_config(candidate) # init()'s verdict, no runtime touched96except ValueError as exc: # "Invalid runtime settings: console_level: Unknown log level: 'loud'"97 logger.error("reload refused: %s", exc)98else:99 log.shutdown()100 log.init(candidate)101 logger = log.getLogger(__name__) # proxies from before shutdown() keep writing to the old runtime102```103104It applies the same `LOG_*` overrides `init()` would, read from the current `os.environ`. There is105no in-place reconfigure: switching means `shutdown()` then `init()`. Do that from the main loop, never106inside a signal handler: set a flag in the handler. The same goes for the final `shutdown()`: let a stop signal set a107flag or raise `SystemExit`, and let the `finally` call it.108109## Reference files110111| Topic | Distilled reference | Upstream (latest docs) |112|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|113| Configuration - every RuntimeConfig field and LOG_* variable, precedence, env parsing, levels, .env loading, validate_config, scrubbing, payload limits, rate limiting, ring buffer size | configuration.md | [README Runtime Reference](https://github.com/bitranox/lib_log_rich/blob/master/README.md#runtime-reference), [DOTENV.md](https://github.com/bitranox/lib_log_rich/blob/master/DOTENV.md) |114| Sinks and deployment - console streams, presets, colour, journald, Windows Event Log, Graylog/GELF, platform guards, OpenTelemetry status, systemd unit, container, Windows service, production checklist | sinks-and-deployment.md | [INSTALL.md](https://github.com/bitranox/lib_log_rich/blob/master/INSTALL.md), [INSTALL_JOURNAL.md](https://github.com/bitranox/lib_log_rich/blob/master/INSTALL_JOURNAL.md), [CONSOLESTYLES.md](https://github.com/bitranox/lib_log_rich/blob/master/CONSOLESTYLES.md) |115| Runtime and integration - init/shutdown/flush lifecycle, LoggerProxy, bind context in threads and asyncio, stdlib bridge, queue policies, multiprocessing, streaming console adapters, severity metrics, testing | runtime-and-integration.md | [QUEUE.md](https://github.com/bitranox/lib_log_rich/blob/master/QUEUE.md), [SUBPROCESSES.md](https://github.com/bitranox/lib_log_rich/blob/master/SUBPROCESSES.md), [STREAMINGCONSOLE.md](https://github.com/bitranox/lib_log_rich/blob/master/STREAMINGCONSOLE.md), [DIAGNOSTIC.md](https://github.com/bitranox/lib_log_rich/blob/master/DIAGNOSTIC.md) |116| Dumps and CLI - ring buffer, dump() formats, filters, template placeholders, crash-dump recipe, lib_log_rich CLI, logdemo, stress test | dumps-and-cli.md | [LOGDUMP.md](https://github.com/bitranox/lib_log_rich/blob/master/LOGDUMP.md), [CLI.md](https://github.com/bitranox/lib_log_rich/blob/master/CLI.md) |117118For the installed version's own truth, run `lib_log_rich --help` and119`python -c "import lib_log_rich; help(lib_log_rich.RuntimeConfig)"`. Where an upstream page and a120reference file here disagree, run the behaviour: the reference files are written against the code.