xtr-logging 1.0.0__py3-none-any.whl

xtr_logging/__init__.py

@@ -0,0 +1,161 @@
+"""Channels, handlers, processors and formatters, behind one logger interface.
+
+Code logs through :class:`LoggerInterface`. A :class:`Logger` is one channel:
+it turns each call into an immutable :class:`LogRecord`, runs its processors,
+and offers the record to a stack of handlers, which format it and write it
+somewhere — stopping where a handler does not let it bubble.
+
+:class:`LoggingConfig` describes channels, handlers and processors as data,
+and :class:`LoggerFactory` builds loggers from it. The
+per-type specs live in :mod:`xtr_logging.config`; the standard-library bridge
+in :mod:`xtr_logging.bridge.stdlib`.
+
+The contract itself — :class:`LoggerInterface`, :class:`Level`,
+:class:`NullLogger` and what else a caller needs to log — lives in
+``xtr-logging-contracts``, so a library can depend on it without depending on
+any of this. It is re-exported here, never redefined: ``xtr_logging.X`` and
+``xtr_logging_contracts.X`` are the same object, which is what lets a container
+register a logger under the interface and have a library that never imported
+this package receive it.
+"""
+
+from importlib.metadata import PackageNotFoundError, version
+
+from .config import LoggingConfig, Services
+from .decorator import as_processor
+from .exception import (
+    CaptureConflictError,
+    CircularHandlerReferenceError,
+    EmptyStackError,
+    InvalidConfigurationError,
+    InvalidOptionError,
+    MixedChannelFilterError,
+    NotProcessableHandlerError,
+    UnknownChannelError,
+    UnknownHandlerError,
+    UnknownServiceError,
+)
+from .formatter import (
+    ConsoleFormatter,
+    FormatterInterface,
+    JsonBatchMode,
+    JsonFormatter,
+    LineFormatter,
+    Normalized,
+    Normalizer,
+)
+from .handler import (
+    AbstractHandler,
+    AbstractProcessingHandler,
+    ActivationStrategyInterface,
+    BufferHandler,
+    ChannelLevelActivationStrategy,
+    ConsoleHandler,
+    DeduplicationHandler,
+    ErrorLevelActivationStrategy,
+    FallbackGroupHandler,
+    FilterHandler,
+    FingersCrossedHandler,
+    FormattableHandlerInterface,
+    GroupHandler,
+    HandlerInterface,
+    NullHandler,
+    ProcessableHandlerInterface,
+    QueueHandler,
+    RotatingFileHandler,
+    SamplingHandler,
+    StreamHandler,
+    SyslogHandler,
+    TestHandler,
+    WhatFailureGroupHandler,
+)
+from .log_context import bind_context, bound_context, clear_context, current_context, unbind_context
+from .log_record import LogRecord
+from .logger import Logger
+from .logger_factory import LoggerFactory
+from .processor import (
+    ContextVarsProcessor,
+    HostnameProcessor,
+    IntrospectionProcessor,
+    PlaceholderProcessor,
+    ProcessIdProcessor,
+    ProcessorInterface,
+    ProcessorRegistry,
+    TagProcessor,
+    UidProcessor,
+    default_processor_registry,
+)
+from .verbosity import Verbosity
+
+try:
+    __version__ = version("xtr-logging")
+except PackageNotFoundError:  # pragma: no cover
+    # Running from a source tree or a vendored copy, with no installed
+    # metadata to read. Having no version is better than refusing to import.
+    __version__ = "0+unknown"
+
+__all__ = [
+    "AbstractHandler",
+    "AbstractProcessingHandler",
+    "ActivationStrategyInterface",
+    "BufferHandler",
+    "CaptureConflictError",
+    "ChannelLevelActivationStrategy",
+    "CircularHandlerReferenceError",
+    "ConsoleFormatter",
+    "ConsoleHandler",
+    "ContextVarsProcessor",
+    "DeduplicationHandler",
+    "EmptyStackError",
+    "ErrorLevelActivationStrategy",
+    "FallbackGroupHandler",
+    "FilterHandler",
+    "FingersCrossedHandler",
+    "FormattableHandlerInterface",
+    "FormatterInterface",
+    "GroupHandler",
+    "HandlerInterface",
+    "HostnameProcessor",
+    "IntrospectionProcessor",
+    "InvalidConfigurationError",
+    "InvalidOptionError",
+    "JsonBatchMode",
+    "JsonFormatter",
+    "LineFormatter",
+    "LogRecord",
+    "Logger",
+    "LoggerFactory",
+    "LoggingConfig",
+    "MixedChannelFilterError",
+    "Normalized",
+    "Normalizer",
+    "NotProcessableHandlerError",
+    "NullHandler",
+    "PlaceholderProcessor",
+    "ProcessIdProcessor",
+    "ProcessableHandlerInterface",
+    "ProcessorInterface",
+    "ProcessorRegistry",
+    "QueueHandler",
+    "RotatingFileHandler",
+    "SamplingHandler",
+    "Services",
+    "StreamHandler",
+    "SyslogHandler",
+    "TagProcessor",
+    "TestHandler",
+    "UidProcessor",
+    "UnknownChannelError",
+    "UnknownHandlerError",
+    "UnknownServiceError",
+    "Verbosity",
+    "WhatFailureGroupHandler",
+    "__version__",
+    "as_processor",
+    "bind_context",
+    "bound_context",
+    "clear_context",
+    "current_context",
+    "default_processor_registry",
+    "unbind_context",
+]

xtr_logging/bridge/__init__.py

@@ -0,0 +1,8 @@
+"""Adapters between this library and something that logs its own way.
+
+Kept apart from the core because everything there stands on its own: a
+:class:`~xtr_logging.logger.Logger` needs no third party to work. A bridge
+does — it speaks to the standard library's :mod:`logging`, or to whatever
+else an application already logs through — so it lives here, reached only
+when that other side is actually in play.
+"""

xtr_logging/bridge/stdlib/__init__.py

@@ -0,0 +1,34 @@
+"""The bridge to the standard library's :mod:`logging`, both ways across.
+
+Out of this library and into :mod:`logging`:
+
+* :class:`~xtr_logging.bridge.stdlib.stdlib_handler.StdlibHandler` relays a
+  channel's records to a :class:`logging.Logger`, keeping their time.
+
+Into this library from :mod:`logging`:
+
+* :class:`~xtr_logging.bridge.stdlib.stdlib_capture_handler.StdlibCaptureHandler`
+  turns a third party's standard-library records into records on a channel, and
+  :class:`~xtr_logging.bridge.stdlib.stdlib_capture.StdlibCapture` takes over
+  the standard library's output with one, so no record is written twice.
+
+And for code that wants this library's interface over a standard backend,
+:class:`~xtr_logging.bridge.stdlib.stdlib_logger.StdlibLogger`. The two
+directions recognise each other's records, so wiring both never loops.
+"""
+
+from .level_mapping import from_stdlib, register_level_names, to_stdlib
+from .stdlib_capture import StdlibCapture
+from .stdlib_capture_handler import StdlibCaptureHandler
+from .stdlib_handler import StdlibHandler
+from .stdlib_logger import StdlibLogger
+
+__all__ = [
+    "StdlibCapture",
+    "StdlibCaptureHandler",
+    "StdlibHandler",
+    "StdlibLogger",
+    "from_stdlib",
+    "register_level_names",
+    "to_stdlib",
+]

xtr_logging/bridge/stdlib/level_mapping.py

@@ -0,0 +1,83 @@
+"""Translating levels between this library's eight and the standard library's five.
+
+:mod:`logging` knows DEBUG, INFO, WARNING, ERROR and CRITICAL. RFC 5424 — and
+so this library — also knows NOTICE, ALERT and EMERGENCY. They are slotted in
+by number where they belong (NOTICE between INFO and WARNING, ALERT and
+EMERGENCY above CRITICAL) so a threshold set on either side keeps its meaning,
+and :func:`register_level_names` teaches :mod:`logging` their names so a
+formatter prints ``NOTICE`` rather than ``Level 25``.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING, Final
+
+from xtr_logging_contracts import Level
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+
+__all__ = ["from_stdlib", "register_level_names", "to_stdlib"]
+
+_TO_STDLIB: Final[Mapping[Level, int]] = {
+    Level.DEBUG: logging.DEBUG,
+    Level.INFO: logging.INFO,
+    Level.NOTICE: 25,
+    Level.WARNING: logging.WARNING,
+    Level.ERROR: logging.ERROR,
+    Level.CRITICAL: logging.CRITICAL,
+    Level.ALERT: 55,
+    Level.EMERGENCY: 60,
+}
+
+# The extra three, paired with the name logging should print for each. The five
+# standard levels already have names, so registering them would only restate
+# what logging knows.
+_EXTRA_NAMES: Final[Mapping[int, str]] = {
+    _TO_STDLIB[Level.NOTICE]: Level.NOTICE.name,
+    _TO_STDLIB[Level.ALERT]: Level.ALERT.name,
+    _TO_STDLIB[Level.EMERGENCY]: Level.EMERGENCY.name,
+}
+
+# Ascending boundaries paired with the level a number below each falls into, so
+# a value between two known levels rounds down to the less severe one.
+_FROM_STDLIB_BOUNDARIES: Final[tuple[tuple[int, Level], ...]] = (
+    (_TO_STDLIB[Level.INFO], Level.DEBUG),
+    (_TO_STDLIB[Level.NOTICE], Level.INFO),
+    (_TO_STDLIB[Level.WARNING], Level.NOTICE),
+    (_TO_STDLIB[Level.ERROR], Level.WARNING),
+    (_TO_STDLIB[Level.CRITICAL], Level.ERROR),
+    (_TO_STDLIB[Level.ALERT], Level.CRITICAL),
+    (_TO_STDLIB[Level.EMERGENCY], Level.ALERT),
+)
+
+
+def to_stdlib(level: Level) -> int:
+    """Return the :mod:`logging` number a record at ``level`` should carry."""
+    return _TO_STDLIB[level]
+
+
+def from_stdlib(levelno: int) -> Level:
+    """Return the level a :mod:`logging` number falls into.
+
+    A number between two known levels rounds down to the less severe one, the
+    way a threshold does: ``logging.WARNING + 1`` is still a warning. Anything
+    at or above EMERGENCY's number is an emergency; there is nothing higher.
+    """
+    for boundary, level in _FROM_STDLIB_BOUNDARIES:
+        if levelno < boundary:
+            return level
+    return Level.EMERGENCY
+
+
+def register_level_names() -> None:
+    """Teach :mod:`logging` the names of NOTICE, ALERT and EMERGENCY.
+
+    Called from the constructors that bridge to :mod:`logging`, never at
+    import, so importing this library leaves the global level table untouched
+    until something actually crosses the bridge. :func:`logging.addLevelName`
+    overwrites, so repeated calls settle on the same three names.
+    """
+    for number, name in _EXTRA_NAMES.items():
+        logging.addLevelName(number, name)

xtr_logging/bridge/stdlib/stdlib_capture.py

@@ -0,0 +1,248 @@
+"""Taking over the standard library's output, so every record is written once.
+
+Capturing is not adding a handler. A handler added next to the ones already
+there — a root ``StreamHandler`` from :func:`logging.basicConfig`, a handler a
+library attached to its own logger — leaves them printing too, and every
+record comes out twice: once through the standard library, once through a
+channel. So a capture *replaces* the standard library's output instead. While
+it is installed the one capture handler, on the root logger, is the only
+handler anywhere in the tree; everything else it moved aside comes back when
+it is released.
+
+That has to hold for handlers attached later, too: the standard library calls
+a logger's own handlers before its parents', so one attached to a library's
+logger after the capture started would print a record before the capture ever
+saw it. While a capture is installed, :meth:`logging.Logger.addHandler` and
+:meth:`logging.Logger.removeHandler` are therefore routed through it — a
+handler attached anywhere is held aside, to be attached for real when the
+capture is released, and the capture's own handler cannot be taken off the
+root. Both methods are the standard library's own again the moment the last
+capture is released.
+
+A record whose logger has no handler to reach — one reconfigured not to
+propagate, its handlers held aside — would fall through to
+:data:`logging.lastResort` and be printed raw to standard error. While
+installed, the capture handler *is* the last resort, so that record is
+captured instead.
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Final, final
+
+from xtr_logging_contracts import Level
+
+from .level_mapping import register_level_names, to_stdlib
+from .stdlib_capture_handler import StdlibCaptureHandler
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+    from types import TracebackType
+    from typing import Self
+
+    from xtr_logging_contracts import LevelLike
+
+    from xtr_logging.logger import Logger
+
+__all__ = ["StdlibCapture"]
+
+_ADD_HANDLER: Final = logging.Logger.addHandler
+_REMOVE_HANDLER: Final = logging.Logger.removeHandler
+
+# Installed captures, most recent last. Only the most recent owns the output.
+_captures: list[StdlibCapture] = []
+
+
+# Named as the standard library names them: these stand in for its methods.
+def _add_handler(self: logging.Logger, hdlr: logging.Handler) -> None:
+    """``Logger.addHandler`` while a capture is installed: hold the handler aside."""
+    _captures[-1].hold(self, hdlr)
+
+
+def _remove_handler(self: logging.Logger, hdlr: logging.Handler) -> None:
+    """``Logger.removeHandler`` while a capture is installed: forget a held handler."""
+    _captures[-1].drop(self, hdlr)
+
+
+def _intercept(active: bool) -> None:
+    """Route ``addHandler`` and ``removeHandler`` through the capture, or give them back."""
+    logging.Logger.addHandler = _add_handler if active else _ADD_HANDLER
+    logging.Logger.removeHandler = _remove_handler if active else _REMOVE_HANDLER
+
+
+@dataclass(slots=True)
+class _Saved:
+    """How a standard logger was set up before the capture changed it."""
+
+    handlers: list[logging.Handler]
+    level: int
+    propagate: bool
+    disabled: bool
+
+
+@final
+class StdlibCapture:
+    """Routes every standard-library record into channels, and nowhere else.
+
+    On :meth:`install`:
+
+    - every existing standard logger loses its handlers, is re-enabled, and
+      propagates again, so each record reaches the root;
+    - the root loses its handlers and gets the one capture handler, at
+      ``level``;
+    - each logger named in ``levels`` is set to its own level.
+
+    Every record the capture handler sees is also checked against the chain of
+    loggers it came through. A handler some code attached after installation
+    Handlers attached while it is installed — through ``addHandler``, as
+    :func:`logging.basicConfig` and :func:`logging.config.dictConfig` attach
+    them — are held aside rather than attached. A logger reconfigured not to
+    propagate is made to again by its first record. And as a last line, every
+    record the capture handler sees is checked against the loggers it came
+    through, for anything put straight into a ``handlers`` list.
+
+    Captures nest: the most recent one owns the output until it is released.
+
+    :meth:`release` puts back every handler, level and flag it changed.
+    """
+
+    __slots__ = ("_handler", "_last_resort", "_levels", "_root_level", "_saved")
+
+    def __init__(
+        self,
+        logger: Logger,
+        *,
+        level: LevelLike = Level.WARNING,
+        levels: Mapping[str, LevelLike] | None = None,
+        routes: Mapping[str, Logger] | None = None,
+    ) -> None:
+        """Capture into ``logger``, or into the channel ``routes`` gives a logger.
+
+        Args:
+            logger: The channel records arrive on unless a route says otherwise.
+            level: The root's level: the threshold for every standard logger
+                that sets none of its own.
+            levels: A level per standard logger name, for loggers that should
+                say more or less than the root lets through.
+            routes: A channel per standard logger name; a logger's children
+                follow it, and the most specific name wins.
+
+        Raises:
+            InvalidLevelError: If a level names no level.
+        """
+        self._handler: StdlibCaptureHandler = StdlibCaptureHandler(logger, routes=routes)
+        self._handler.addFilter(self._take_over_origin)
+        self._root_level: int = to_stdlib(Level.parse(level))
+        self._levels: dict[str, int] = {
+            name: to_stdlib(Level.parse(value)) for name, value in (levels or {}).items()
+        }
+        self._saved: dict[logging.Logger, _Saved] = {}
+        self._last_resort: logging.Handler | None = None
+
+    @property
+    def installed(self) -> bool:
+        """Whether the capture currently owns the standard library's output."""
+        return bool(self._saved)
+
+    def install(self) -> None:
+        """Take over every standard logger. Installing twice changes nothing."""
+        if self.installed:
+            return
+        register_level_names()
+        if not _captures:
+            _intercept(active=True)
+        _captures.append(self)
+        root = logging.getLogger()
+        existing = [
+            candidate
+            for candidate in logging.Logger.manager.loggerDict.values()
+            if isinstance(candidate, logging.Logger)
+        ]
+        for candidate in (*existing, root):
+            self._take_over(candidate)
+        _ADD_HANDLER(root, self._handler)
+        root.setLevel(self._root_level)
+        self._last_resort = logging.lastResort
+        logging.lastResort = self._handler
+        for name, level in self._levels.items():
+            named = logging.getLogger(name)
+            self._take_over(named)
+            named.setLevel(level)
+
+    def release(self) -> None:
+        """Give every standard logger back exactly as it was found.
+
+        Handlers attached while the capture was installed are attached now.
+        """
+        if not self.installed:
+            return
+        _captures.remove(self)
+        if not _captures:
+            _intercept(active=False)
+        _REMOVE_HANDLER(logging.getLogger(), self._handler)
+        logging.lastResort = self._last_resort
+        for taken, saved in self._saved.items():
+            taken.handlers = list(saved.handlers)
+            taken.setLevel(saved.level)
+            taken.propagate = saved.propagate
+            taken.disabled = saved.disabled
+        self._saved.clear()
+
+    def __enter__(self) -> Self:
+        """Install for the ``with`` block."""
+        self.install()
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_value: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
+        """Release, whatever happened in the block."""
+        self.release()
+
+    def hold(self, logger: logging.Logger, handler: logging.Handler) -> None:
+        """Keep ``handler`` for ``logger`` until release, instead of attaching it."""
+        if handler is self._handler:
+            _ADD_HANDLER(logger, handler)
+            return
+        self._take_over(logger)
+        held = self._saved[logger].handlers
+        if handler not in held:
+            held.append(handler)
+
+    def drop(self, logger: logging.Logger, handler: logging.Handler) -> None:
+        """Forget a held ``handler``; the capture's own handler stays where it is."""
+        if handler is self._handler:
+            return
+        _REMOVE_HANDLER(logger, handler)
+        saved = self._saved.get(logger)
+        if saved is not None and handler in saved.handlers:
+            saved.handlers.remove(handler)
+
+    def _take_over(self, taken: logging.Logger) -> None:
+        """Move ``taken``'s handlers aside and make it propagate, remembering how it was."""
+        saved = self._saved.get(taken)
+        if saved is None:
+            saved = _Saved([], taken.level, taken.propagate, taken.disabled)
+            self._saved[taken] = saved
+        foreign = [handler for handler in taken.handlers if handler is not self._handler]
+        saved.handlers.extend(foreign)
+        # Assigned rather than mutated: the standard library may be iterating
+        # the old list for the record being handled right now.
+        taken.handlers = [handler for handler in taken.handlers if handler is self._handler]
+        taken.propagate = True
+        taken.disabled = False
+
+    def _take_over_origin(self, record: logging.LogRecord) -> bool:
+        """Move aside anything put on the record's way up since installation."""
+        current: logging.Logger | None = logging.getLogger(record.name)
+        while current is not None:
+            foreign = any(handler is not self._handler for handler in current.handlers)
+            if foreign or not current.propagate or current.disabled:
+                self._take_over(current)
+            current = current.parent
+        return True

xtr_logging/bridge/stdlib/stdlib_capture_handler.py

@@ -0,0 +1,134 @@
+"""A :mod:`logging` handler that feeds standard-library records into a channel.
+
+Third-party code — uvicorn, SQLAlchemy, httpx, anything built on :mod:`logging`
+— writes through the standard library, not through this one. Installed on those
+loggers, this handler turns each of their records into a
+:class:`~xtr_logging.log_record.LogRecord` on one of this library's channels,
+keeping its time, its exception and whatever it attached through ``extra=``. A
+record this library itself relayed out through
+:class:`~xtr_logging.bridge.stdlib.stdlib_handler.StdlibHandler` is recognised
+and dropped, so wiring both directions does not send a record round in circles.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING, Final, final
+
+from typing_extensions import override
+from xtr_clock import DatePoint, local_timezone
+from xtr_logging_contracts import EXCEPTION_KEY
+
+from .level_mapping import from_stdlib, register_level_names
+from .stdlib_handler import BRIDGED_MARKER
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+
+    from xtr_logging.logger import Logger
+
+__all__ = ["StdlibCaptureHandler"]
+
+# Everything a bare logging.LogRecord already carries; anything else on a record
+# was put there by a caller through `extra=` and so belongs in the context.
+# `message` and `asctime` are set by formatting rather than __init__, and
+# `taskName` exists only on newer Pythons, so all three are named explicitly.
+_STANDARD_ATTRIBUTES: Final[frozenset[str]] = frozenset(vars(logging.makeLogRecord({}))) | {
+    "message",
+    "asctime",
+    "taskName",
+}
+
+
+@final
+class StdlibCaptureHandler(logging.Handler):
+    """Turns the standard library's records into records on a channel.
+
+    The channel is chosen per record: the ``routes`` entry for the most
+    specific standard logger name that matches — ``httpx`` catches
+    ``httpx._client`` too — or, with ``channel_from_name``, one named after the
+    standard logger the record came from, so ``sqlalchemy.engine`` and
+    ``uvicorn.access`` stay apart the way they were; otherwise the channel this
+    handler was built for. Per-name channels are made once and reused.
+    """
+
+    def __init__(
+        self,
+        logger: Logger,
+        *,
+        routes: Mapping[str, Logger] | None = None,
+        channel_from_name: bool = False,
+        level: int = logging.NOTSET,
+    ) -> None:
+        """Capture into ``logger``.
+
+        Args:
+            logger: The channel captured records are added to, or the channel
+                whose handlers and processors the per-name channels share.
+            routes: The channel for records from a standard logger and its
+                children, by standard logger name; the longest match wins.
+            channel_from_name: Route a record no route matches to a channel
+                named after the standard logger it came from, rather than to
+                ``logger`` itself.
+            level: The standard-library level below which records are dropped
+                before this handler sees them; the loggers it is installed on
+                have their own levels too.
+        """
+        super().__init__(level)
+        register_level_names()
+        self._logger: Logger = logger
+        self._channel_from_name: bool = channel_from_name
+        # Longest name first, so the first match is the most specific.
+        self._routes: tuple[tuple[str, Logger], ...] = tuple(
+            sorted((routes or {}).items(), key=lambda route: -len(route[0])),
+        )
+        self._by_name: dict[str, Logger] = {}
+
+    @override
+    def emit(self, record: logging.LogRecord) -> None:
+        """Add ``record`` to a channel, unless this library sent it out.
+
+        Keeps :class:`logging.Handler`'s contract of never letting an error
+        escape: anything that goes wrong is reported through
+        :meth:`logging.Handler.handleError`, which respects
+        :data:`logging.raiseExceptions`, rather than propagating to the code
+        that happened to be logging.
+        """
+        marker: object = getattr(record, BRIDGED_MARKER, False)
+        if marker:
+            return
+        try:
+            self._capture(record)
+        except RecursionError:  # pragma: no cover - stdlib re-raises to surface a stack overflow
+            raise
+        except Exception:  # noqa: BLE001 - Handler.emit reports via handleError, never propagates
+            self.handleError(record)
+
+    def _capture(self, record: logging.LogRecord) -> None:
+        attributes: dict[str, object] = vars(record)
+        context: dict[str, object] = {
+            name: value for name, value in attributes.items() if name not in _STANDARD_ATTRIBUTES
+        }
+        exc_info = record.exc_info
+        exception = exc_info[1] if exc_info is not None else None
+        if isinstance(exception, BaseException):
+            context[EXCEPTION_KEY] = exception
+        when = DatePoint.fromtimestamp(record.created, local_timezone())
+        _ = self._target_for(record.name).add_record(
+            from_stdlib(record.levelno),
+            record.getMessage(),
+            context,
+            datetime=when,
+        )
+
+    def _target_for(self, name: str) -> Logger:
+        for prefix, routed in self._routes:
+            if name == prefix or name.startswith(f"{prefix}."):
+                return routed
+        if not self._channel_from_name:
+            return self._logger
+        cached = self._by_name.get(name)
+        if cached is None:
+            cached = self._logger.with_name(name)
+            self._by_name[name] = cached
+        return cached