tractor/ai/tooling-todos/logspec_leaf_module_granularity_route_b.md

# Logging-spec leaf-module granularity — "Route B" (decouple
# logger-*identity* from console-*display*)

Follow-up notes recording the breaking-changes / costs of the
deeper fix that would give the `tractor.log` logging-spec (see
`LogSpec`/`apply_logspec()`) true **per-leaf-MODULE** level
control — deliberately *not* taken (for now) in favour of the
smaller sub-PACKAGE fix already landed.

## Status / what already shipped

The cheap, contained fix is **done**: `get_logger()`'s "strip
#2" (`log.py`, the `pkg_path = subpkg_path` collapse) no longer
eats a real sub-package component. It now strips the trailing
token *only* when it duplicates the caller's leaf-*module*
filename (which the header already shows via `{filename}`).

Result:

- `devx.debug` resolves to `tractor.devx.debug`, **distinct**
  from a bare `devx` -> `tractor.devx` (its parent). So the
  logging-spec can dial sub-package levels at any nesting depth
  (`devx.debug:runtime` ≠ `devx:cancel`).
- The `get_logger(__name__)` cosmetic ("don't repeat the leaf
  module in `{name}` since `{filename}` shows it") is preserved.

What is **still NOT addressable** after that fix:

- **Per-leaf-MODULE** levels. Every module in a (sub-)pkg shares
  that pkg's logger, because `get_logger()` drops the leaf
  module-name from the logger key by design.
- **Top-level lib modules** (eg. `tractor.to_asyncio`,
  `__package__ == 'tractor'`) emit on the *root* `tractor`
  logger, so a `to_asyncio:<lvl>` spec entry hits a phantom
  child -> no-op.

## What "Route B" is

Make the logger's *identity* the **full dotted module path**
(incl. the leaf module + top-level modules), eg.
`tractor.devx.debug._tty_lock` and `tractor.to_asyncio`, and
move the cosmetic leaf-trim out of logger-naming and into the
**formatter's `{name}` rendering**.

Net effect:

- Real per-module `Logger` nodes exist in the hierarchy ->
  the spec can target ANY module; stdlib level-inheritance and
  propagation "just work" top-down.
- Console headers stay clean because the formatter computes a
  trimmed display string (drop the trailing token that equals
  `{filename}`'s stem) instead of the logger doing it.

## Why it's "broad" — breaking changes / costs

The logger *name* is currently load-bearing well beyond
display; changing it ripples:

1. **Every logger name changes.**
   Today (post sub-pkg fix) names collapse to the sub-package;
   Route B = full module path. This touches:
   - handler attachment points + the `getChild()` hierarchy,
   - any `logging.getLogger('tractor.X')` string lookups,
   - any name-based filtering,
   - the dedup / `_strict_debug` warning logic *inside*
     `get_logger()` itself — the `pkg_name in name`,
     `leaf_mod in pkg_path`, "duplicate pkg-name" branches all
     key off the *name shape* and would need re-derivation.

2. **Formatter rewrite.**
   `LOG_FORMAT` uses `{name}` == `record.name` (the full logger
   name). To keep headers clean we must compute a *display*
   name and inject it as a record attr (eg. `record.pkg_ns`)
   via a `logging.Filter` or a `colorlog.ColoredFormatter`
   subclass overriding `.format()`, then point `LOG_FORMAT` at
   that field. The `{filename}` vs `{name}` de-dup intent has
   to be re-implemented per-record rather than per-logger.

3. **Propagation / double-emit surface grows.**
   Full-depth loggers mean more intermediate nodes
   (`...debug._tty_lock` -> `.debug` -> `.devx` -> `tractor`).
   If more than one level carries a handler (spec sub-handlers
   + a root console), records double-emit. The
   `propagate=False` trick we already use for filter-targeted
   sub-loggers (`apply_logspec()`) must be applied carefully
   across a deeper tree — more levels == more places to leak a
   dup.

4. **Level-inheritance semantics shift.**
   Today setting a level on `tractor.devx` gates *all* devx
   emits (they share that logger). Post-Route-B,
   `tractor.devx.debug._tty_lock` is its own `NOTSET` logger
   that *inherits* the effective level from ancestors —
   functionally similar via inheritance, BUT any code that does
   `log.setLevel(...)` / reads `log.level` on a (previously
   collapsed) logger now only affects that exact node. All
   `setLevel`/`.level =` call sites need an audit (eg.
   `get_logger()`'s own `log.level = rlog.level` line).

5. **Downstream contract churn.**
   `modden` / `piker` call `get_logger()` / `get_console_log()`
   and may depend on current names — including
   `modden.runtime.daemon.setup_tractor_logging()` which
   asserts `'tractor' not in name` on spec parts. The header
   `{name}` field is user-visible in everyone's logs + CI
   output. Changing the canonical names is a public-ish
   behavior change -> needs a version note + downstream
   coordination (or a formatter trim that keeps the *displayed*
   string byte-identical to today).

6. **`get_logger()` refactor risk.**
   The fn tangles two concerns: compute logger *identity* and
   compute the *display* string. Route B forces splitting them
   inside a ~300-line fn with multiple `_strict_debug`
   branches, dup-warnings, and the `name=__name__` convenience.
   High chance of subtle regressions without an exhaustive
   name-derivation test matrix.

## Migration / test plan (if pursued)

- Extract a pure helper
  `_mk_logger_name(pkg_name, mod_name, mod_pkg) -> (logger_name,
  display_name)` and cover it with an exhaustive unit matrix:
  auto vs explicit vs `__name__`; package-`__init__` vs leaf
  module; nested vs flat; `pkg_name in name` vs not; top-level
  module (`__package__ == pkg_name`).
- Switch `get_logger()` to use it for *identity*; switch the
  formatter to use `display_name` (via a record attr).
- Re-run the full suite + golden-diff a sample of rendered log
  headers to confirm zero cosmetic churn.
- Coordinate the name change with `modden`/`piker`; bump +
  CHANGES note.

## Cheaper alternative — "Route A" (record-filter)

If per-leaf control is wanted *before* committing to Route B:
keep names collapsed, add a `logging.Filter` on the configured
handler keyed on `record.module` / `record.pathname` that maps
each record's source module -> its spec level. Set the base
logger to the *minimum* level in the spec (so records aren't
pre-dropped by the logger), and let the filter discriminate
up/down within that floor.

- Pros: no name churn, no formatter change, fully contained
  next to `apply_logspec()`.
- Cons: a filter can only discriminate *within* what the logger
  admits -> base must be permissive, so `at_least_level()`
  expensive-work guards over-admit; matching dotted spec names
  to a `pathname` is fiddly; doesn't clean up the hierarchy
  itself.

## Recommendation

- Defer Route B unless true per-module loggers are wanted as a
  first-class feature.
- If per-leaf control is needed soon, prefer **Route A**
  (filter) — lower risk.
- The shipped sub-PACKAGE fix already covers the common ask
  (`devx.debug` vs `devx`).