feat: module_levels for per-logger level overrides at setup
add an optional module_levels={logger_name: level} param to setup_logging,
the ergonomic way to quiet noisy dependencies (motor/pymongo/aiohttp -> WARNING)
from the one entry-point call instead of scattering setLevel afterwards.
- exact logger-name match, no discovery; stdlib hierarchy applies so naming a
parent quiets its subtree
- str or int level per entry, same normalization as root level
- bad level for one entry is skipped + warned, never raises (never-crash rule)
- module_levels=None/{} (default) is byte-identical to prior behavior
additive, backwards-compatible -> v0.3.0.
Signed-off-by: disqualifier <dev@disqualifier.me>
This commit is contained in:
@@ -13,7 +13,7 @@ and emit; their records flow into the handlers `log_setup` wired.
|
||||
## Install
|
||||
|
||||
```
|
||||
log_setup @ git+ssh://git@git.rethinkstudios.io/rethink-public/log_setup.git@v0.2.0
|
||||
log_setup @ git+ssh://git@git.rethinkstudios.io/rethink-public/log_setup.git@v0.3.0
|
||||
```
|
||||
|
||||
No dependencies — stdlib only.
|
||||
@@ -89,7 +89,8 @@ logging.getLogger("bot.core").info("ready", extra={"monitor": "heartbeat"})
|
||||
setup_logging(
|
||||
name="run", # base -> run.log (the live file at cwd)
|
||||
log_dir="logs", # rotated/compressed copies live here (created if absent)
|
||||
level="INFO", # root level (str name or logging constant)
|
||||
level="INFO", # root level everything inherits (str name or logging constant)
|
||||
module_levels=None, # {logger_name: level} per-logger overrides (exact name match)
|
||||
rotate="daily", # "daily" | "size" | "on_start" | None
|
||||
backup_count=14, # rotated files to keep (older auto-deleted)
|
||||
max_bytes=10_000_000, # only for rotate="size"
|
||||
@@ -102,6 +103,47 @@ setup_logging(
|
||||
) -> logging.Logger # returns the configured root logger
|
||||
```
|
||||
|
||||
## Quieting noisy dependencies (`module_levels`)
|
||||
|
||||
`level` is the **root default** — every logger inherits it. `module_levels` is an
|
||||
optional `{logger_name: level}` map of **per-logger overrides** applied at setup, the
|
||||
standard "turn down the chatty dependency while my own code stays at INFO" case:
|
||||
|
||||
```python
|
||||
setup_logging(
|
||||
name="run",
|
||||
level="INFO", # our code logs at INFO
|
||||
module_levels={
|
||||
"motor": "WARNING", # quiet the driver
|
||||
"pymongo": "WARNING",
|
||||
"aiohttp": "WARNING", # also quiets aiohttp.client / aiohttp.access (hierarchy)
|
||||
},
|
||||
)
|
||||
```
|
||||
|
||||
- **Exact-name match — names are NOT discovered.** It calls
|
||||
`logging.getLogger(name).setLevel(level)` for exactly the name you give. There's no
|
||||
smart find of noisy modules; you name the loggers. A typo (`"moter"`) silently
|
||||
configures a logger nothing uses — no error, no effect. Get the names right.
|
||||
- **Hierarchy applies** (the one "smart" part, and it's just stdlib): naming a **parent**
|
||||
quiets its whole subtree. `"aiohttp"` also quiets `aiohttp.client`, `aiohttp.access`,
|
||||
etc. — the way to catch sub-loggers without listing each.
|
||||
- **str or int** per entry (`"WARNING"` or `logging.WARNING`) — same normalization as the
|
||||
root `level`.
|
||||
- **Never crashes:** a bad level for one entry is **skipped with a warning**; the other
|
||||
entries and the rest of setup still apply. Consistent with the never-crash-over-logging
|
||||
rule.
|
||||
- `None`/`{}` (default) → no overrides; existing callers are unaffected.
|
||||
|
||||
Common noisy library logger names: `motor`, `pymongo`, `aiohttp` (parent quiets
|
||||
`aiohttp.client`/`aiohttp.access`), `discord` / `discord.*`, `asyncio`, `urllib3`. Check
|
||||
a lib's *actual* logger name — some log under a name different from their package.
|
||||
|
||||
This already works without the lib (`logging.getLogger("motor").setLevel(WARNING)` after
|
||||
setup does the same via stdlib hierarchy). The param's value is ergonomic: it keeps the
|
||||
overrides in the **one** `setup_logging` call at the entry point instead of scattering
|
||||
`setLevel` calls afterward — which is the whole point of `log_setup`.
|
||||
|
||||
## Async-friendly (`queue=True`)
|
||||
|
||||
For async-heavy apps, `queue=True` routes records through a stdlib `QueueHandler` to a
|
||||
|
||||
Reference in New Issue
Block a user