kitty-logger 0.2.0.dev0__tar.gz → 0.2.0.dev2__tar.gz

{kitty_logger-0.2.0.dev0/src/kitty_logger.egg-info → kitty_logger-0.2.0.dev2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kitty_logger
-Version: 0.2.0.dev0
+Version: 0.2.0.dev2
 Summary: Cross-process logging via a dedicated log server process and SocketHandler.
 Author: Kitty
 License: MIT
@@ -54,12 +54,20 @@ if __name__ == "__main__":
 
 ## API
 
-- `setup_logging(log_file=None, level=logging.INFO, host="127.0.0.1", port=0, stream=True, console_fmt=..., file_fmt=..., datefmt=None, attach_main_logger=True) -> (host, port)`
+- `setup_logging(log_file=None, level=logging.INFO, host="127.0.0.1", port=0, stream=True, console_fmt=..., file_fmt=..., datefmt=None) -> (host, port)`
   启动日志服务子进程（始终使用 `spawn`）。幂等。已通过 `atexit` 注册清理。
   `port=0` 让操作系统挑选空闲端口；返回真实绑定到的 `(host, port)`。
   **`host` 必须是 loopback**——绑定非 loopback 地址会直接 `ValueError`。
+  同时把主进程内 `logging.getLogger("kitty")` 这一个 logger 初始化好——挂上
+  `SocketHandler`、设置 level、关闭 `propagate`。**不动 root logger**。
+  在 `multiprocessing` 启动的子进程里再次调用本函数会自动 no-op，仅返回
+  从父进程继承的 `(host, port)`，因此可以直接放在模块顶层而不必用
+  `if __name__ == "__main__":` 包裹。
 - `getLogger(name=None) -> logging.Logger`
-  返回一个挂好 `SocketHandler`、指向日志服务的 logger。
+  返回挂在 `kitty` 命名空间下的 logger：`getLogger("foo")` 实际拿到的是
+  `logging.getLogger("kitty.foo")`，`getLogger()` 拿到的是 `kitty` 本身。
+  整个进程内只有 `kitty` 持有 `SocketHandler`，子 logger 通过标准库的祖先链
+  冒泡上来，无需重复挂载。
 - `shutdown_logging()` — 显式停止日志服务子进程。
 
 ## 为什么只支持 spawn
@@ -74,11 +82,12 @@ if __name__ == "__main__":
 
 ## 注意事项
 
-- **不要**在 `setup_logging(attach_main_logger=True)` 之前调用
-  `logging.basicConfig()`（或自行给 root logger 挂 `StreamHandler`）——
-  否则主进程会把每条记录输出两次：一次走本地 root handler，一次走日志
-  服务。要么让 kitty_logger 做唯一的配置入口，要么传
-  `attach_main_logger=False` 自行管理主进程的 handler。
+- **所有 logger 名都带 `kitty.` 前缀**，这是有意保留的标记：日志记录里
+  `%(name)s` 字段一眼可以和第三方库（urllib3、httpx 等）的输出区分。
+  `getLogger(__name__)` 在模块 `myapp.svc` 下实际得到的是 `kitty.myapp.svc`。
+- `kitty` 子树**不向 root 冒泡**：第三方库挂在 root 上的 handler 不会收到
+  kitty_logger 的日志，反之 root 上输出的日志也不会被 kitty_logger 转发。
+  两条输出渠道互不干扰。
 - `shutdown_logging()` 会卸载本进程内 kitty_logger 自己挂的
   `SocketHandler`，并清理 `KITTY_LOGGER_*` 环境变量，确保进程状态与
   `setup_logging` 对称。如果你额外挂了别的 handler，仍由你自己负责清理。

{kitty_logger-0.2.0.dev0 → kitty_logger-0.2.0.dev2}/README.md

@@ -41,12 +41,20 @@ if __name__ == "__main__":
 
 ## API
 
-- `setup_logging(log_file=None, level=logging.INFO, host="127.0.0.1", port=0, stream=True, console_fmt=..., file_fmt=..., datefmt=None, attach_main_logger=True) -> (host, port)`
+- `setup_logging(log_file=None, level=logging.INFO, host="127.0.0.1", port=0, stream=True, console_fmt=..., file_fmt=..., datefmt=None) -> (host, port)`
   启动日志服务子进程（始终使用 `spawn`）。幂等。已通过 `atexit` 注册清理。
   `port=0` 让操作系统挑选空闲端口；返回真实绑定到的 `(host, port)`。
   **`host` 必须是 loopback**——绑定非 loopback 地址会直接 `ValueError`。
+  同时把主进程内 `logging.getLogger("kitty")` 这一个 logger 初始化好——挂上
+  `SocketHandler`、设置 level、关闭 `propagate`。**不动 root logger**。
+  在 `multiprocessing` 启动的子进程里再次调用本函数会自动 no-op，仅返回
+  从父进程继承的 `(host, port)`，因此可以直接放在模块顶层而不必用
+  `if __name__ == "__main__":` 包裹。
 - `getLogger(name=None) -> logging.Logger`
-  返回一个挂好 `SocketHandler`、指向日志服务的 logger。
+  返回挂在 `kitty` 命名空间下的 logger：`getLogger("foo")` 实际拿到的是
+  `logging.getLogger("kitty.foo")`，`getLogger()` 拿到的是 `kitty` 本身。
+  整个进程内只有 `kitty` 持有 `SocketHandler`，子 logger 通过标准库的祖先链
+  冒泡上来，无需重复挂载。
 - `shutdown_logging()` — 显式停止日志服务子进程。
 
 ## 为什么只支持 spawn
@@ -61,11 +69,12 @@ if __name__ == "__main__":
 
 ## 注意事项
 
-- **不要**在 `setup_logging(attach_main_logger=True)` 之前调用
-  `logging.basicConfig()`（或自行给 root logger 挂 `StreamHandler`）——
-  否则主进程会把每条记录输出两次：一次走本地 root handler，一次走日志
-  服务。要么让 kitty_logger 做唯一的配置入口，要么传
-  `attach_main_logger=False` 自行管理主进程的 handler。
+- **所有 logger 名都带 `kitty.` 前缀**，这是有意保留的标记：日志记录里
+  `%(name)s` 字段一眼可以和第三方库（urllib3、httpx 等）的输出区分。
+  `getLogger(__name__)` 在模块 `myapp.svc` 下实际得到的是 `kitty.myapp.svc`。
+- `kitty` 子树**不向 root 冒泡**：第三方库挂在 root 上的 handler 不会收到
+  kitty_logger 的日志，反之 root 上输出的日志也不会被 kitty_logger 转发。
+  两条输出渠道互不干扰。
 - `shutdown_logging()` 会卸载本进程内 kitty_logger 自己挂的
   `SocketHandler`，并清理 `KITTY_LOGGER_*` 环境变量，确保进程状态与
   `setup_logging` 对称。如果你额外挂了别的 handler，仍由你自己负责清理。

{kitty_logger-0.2.0.dev0 → kitty_logger-0.2.0.dev2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "kitty_logger"
-version = "0.2.0.dev0"
+version = "0.2.0.dev2"
 description = "Cross-process logging via a dedicated log server process and SocketHandler."
 readme = "README.md"
 requires-python = ">=3.12"

{kitty_logger-0.2.0.dev0 → kitty_logger-0.2.0.dev2}/src/kitty_logger/__init__.py

@@ -6,6 +6,11 @@
 日志收敛到主进程指定的文件 / ``stderr`` 中，不会因多进程并发写文件而
 错行或丢失。
 
+命名空间：所有由本库返回的 logger 都挂在 ``kitty`` 这棵子树下。
+``getLogger("foo")`` 实际拿到的是 ``logging.getLogger("kitty.foo")``，
+日志记录里 ``%(name)s`` 会带 ``kitty.`` 前缀，便于和第三方库的日志区分。
+``kitty`` 子树独立运行，不会向 root 冒泡，也不会被 root 上的 handler 干扰。
+
 典型用法::
 
     # main.py
@@ -28,4 +33,4 @@ from ._client import getLogger
 from ._setup import setup_logging, shutdown_logging
 
 __all__ = ["setup_logging", "shutdown_logging", "getLogger"]
-__version__ = "0.2.0.dev0"
+__version__ = "0.2.0.dev2"

kitty_logger-0.2.0.dev2/src/kitty_logger/_client.py

@@ -0,0 +1,112 @@
+"""子进程侧 API：:func:`getLogger`。
+
+子进程通过环境变量
+``KITTY_LOGGER_HOST`` / ``KITTY_LOGGER_PORT`` / ``KITTY_LOGGER_LEVEL``
+找到日志服务地址；这些环境变量是父进程在 :func:`setup_logging` 时写入的，
+``spawn`` 出来的后代进程会自动继承。
+
+命名空间约定
+------------
+
+所有由本库返回的 logger 都挂在 ``kitty`` 这棵子树下：
+
+- ``getLogger()`` → ``logging.getLogger("kitty")``
+- ``getLogger("foo.bar")`` → ``logging.getLogger("kitty.foo.bar")``
+
+整个进程内只有 ``kitty`` 这一个 logger 持有指向日志服务的
+:class:`SocketHandler`，子 logger 通过标准库的祖先链冒泡上来。
+``kitty`` 自身的 ``propagate`` 被关闭，与 root 上的第三方库日志互不干扰。
+"""
+
+import logging
+import logging.handlers
+import os
+import threading
+
+from ._env import ENV_HOST, ENV_LEVEL, ENV_PORT
+
+# 本库使用的 logger 命名空间根。所有用户拿到的 logger 都在这棵子树下。
+KITTY_NAMESPACE = "kitty"
+
+# 保护 ``kitty`` logger 上的 handler 初始化。
+_lock = threading.Lock()
+
+
+def _read_endpoint() -> tuple[str, int]:
+    """从环境变量读出 ``(host, port)``；未设置则抛出友好错误。"""
+    host = os.environ.get(ENV_HOST)
+    port = os.environ.get(ENV_PORT)
+    if not host or not port:
+        raise RuntimeError(
+            "kitty_logger 尚未在当前进程树中初始化。"
+            + "请先在主进程调用 kitty_logger.setup_logging()，"
+            + "再创建（spawn）子进程或调用 getLogger()。"
+        )
+    return host, int(port)
+
+
+def _read_level() -> int:
+    """从环境变量解析默认 level。优先按整数解析，失败则按级别名解析。"""
+    raw = os.environ.get(ENV_LEVEL)
+    if raw is None:
+        return logging.INFO
+    try:
+        return int(raw)
+    except ValueError:
+        pass
+    return logging.getLevelNamesMapping().get(raw.upper(), logging.INFO)
+
+
+def _ensure_kitty_handler() -> logging.Logger:
+    """保证本进程内 ``kitty`` logger 已挂上指向日志服务的 SocketHandler。
+
+    幂等：已挂过则直接返回；``spawn`` 出来的全新解释器里第一次调用时
+    才会真正去读 ENV、建 SocketHandler。
+
+    .. note::
+       :class:`logging.handlers.SocketHandler` 直接 pickle ``LogRecord``
+       发送，由接收端格式化；在这里给 handler 设置 ``formatter`` 没有
+       任何效果，会被服务端忽略。
+    """
+    SocketHandler = logging.handlers.SocketHandler
+    kitty = logging.getLogger(KITTY_NAMESPACE)
+
+    with _lock:
+        for h in kitty.handlers:
+            if isinstance(h, SocketHandler):
+                return kitty
+
+        host, port = _read_endpoint()
+        level = _read_level()
+
+        kitty.addHandler(SocketHandler(host, port))
+
+        # 仅在仍是默认 ``NOTSET`` 时才设置 level，避免悄悄覆盖
+        # 用户已经显式设置过的级别。
+        if kitty.level == logging.NOTSET:
+            kitty.setLevel(level)
+
+        # ``kitty`` 子树自成一系，不向 root 冒泡：这样和第三方库挂在 root
+        # 上的 handler 互不串扰；用户控制 root 的输出渠道时也不会无意中
+        # 把 kitty_logger 的日志带过去（反之亦然）。
+        kitty.propagate = False
+
+    return kitty
+
+
+def getLogger(name: str | None = None) -> logging.Logger:
+    """返回挂在 ``kitty`` 命名空间下的 logger，自动连到日志服务。
+
+    必须在父进程已经调用过 :func:`kitty_logger.setup_logging` 之后才能
+    使用。本库只支持 ``spawn`` 启动方式；spawn 出来的子进程模块级状态
+    天然为空，第一次调用时会按需完成初始化。
+
+    :param name: 业务名；``None`` 表示直接返回 ``kitty`` 本身。``"foo"``
+        会被转换为 ``logging.getLogger("kitty.foo")``——日志记录里
+        ``%(name)s`` 字段会带 ``kitty.`` 前缀，这是有意保留的标记，方便
+        和第三方库日志区分。
+    :raises RuntimeError: 当前进程树尚未调用 ``setup_logging``。
+    """
+    _ensure_kitty_handler()
+    full = KITTY_NAMESPACE if not name else f"{KITTY_NAMESPACE}.{name}"
+    return logging.getLogger(full)

{kitty_logger-0.2.0.dev0 → kitty_logger-0.2.0.dev2}/src/kitty_logger/_server.py

@@ -169,6 +169,28 @@ def run_server(
         root.addHandler(h)
     root.setLevel(level)
 
+    # 防御 ``spawn`` bootstrap：服务子进程在 ``_fixup_main_from_path`` 重新
+    # import 用户主脚本时，主脚本顶层 import 的第三方库可能在模块级调用
+    # ``kitty_logger.getLogger(...)``。由于父进程已经把 KITTY_LOGGER_HOST/
+    # PORT/LEVEL 写进 ENV，本服务子进程里的 ``_ensure_kitty_handler()`` 会
+    # 顺利地往 ``kitty`` logger 上挂一个指向本服务自己监听端口的
+    # :class:`SocketHandler`，并把 ``propagate`` 关掉。结果是：本服务接收
+    # 到记录后调 ``logging.getLogger(record.name).handle(record)``，记录
+    # 沿祖先链冒泡到 ``kitty`` 时被这个 handler 捞走，原样发回给本服务
+    # 自身（形成网络回环），同时因为 ``propagate=False`` 而不会再到达
+    # root 上配置好的落地 handler，外部表现为日志凭空消失。
+    # 因此在开始 serve 之前，强制把 ``kitty`` logger 还原成"无 handler、
+    # propagate=True、level=NOTSET"，让记录稳稳地冒泡到 root。
+    kitty = logging.getLogger("kitty")
+    for h in list(kitty.handlers):
+        kitty.removeHandler(h)
+        try:
+            h.close()
+        except OSError:
+            pass
+    kitty.propagate = True
+    kitty.setLevel(logging.NOTSET)
+
     server = _LogRecordSocketReceiver(listening_sock)
 
     def _wait_shutdown() -> None:

{kitty_logger-0.2.0.dev0 → kitty_logger-0.2.0.dev2}/src/kitty_logger/_setup.py

@@ -128,7 +128,6 @@ def setup_logging(
     console_fmt: str = DEFAULT_CONSOLE_FMT,
     file_fmt: str = DEFAULT_FILE_FMT,
     datefmt: str | None = None,
-    attach_main_logger: bool = True,
 ) -> tuple[str, int]:
     """在主进程里启动跨进程日志服务，返回服务真实绑定到的 ``(host, port)``。
 
@@ -142,9 +141,20 @@ def setup_logging(
     无颜色的 :class:`FileFormatter`，两者均使用毫秒级时间戳。
 
     幂等：重复调用直接返回已记录的 ``(host, port)``，不会重复启动子进程。
+    在 ``multiprocessing`` 启动的子进程里调用本函数时，会自动判断当前
+    不是原始主进程并直接返回从父进程继承的 ``(host, port)``，本身不再
+    启动新的日志服务——这意味着用户可以把 ``setup_logging()`` 直接放在
+    模块顶层而不必用 ``if __name__ == "__main__":`` 包裹。
+
+    本函数同时把主进程内 ``logging.getLogger("kitty")`` 这一个 logger
+    初始化好——挂上指向日志服务的 :class:`SocketHandler`、设置 level、
+    并把 ``propagate`` 关掉。所有通过 :func:`kitty_logger.getLogger`
+    取到的子 logger 都挂在 ``kitty`` 这棵子树下，借标准库的祖先链冒泡到
+    ``kitty`` 的这个 handler 上，无需自己额外配置。
 
     :param log_file: 日志文件路径；``None`` 表示不落盘。
-    :param level: 服务端 root logger 的级别。
+    :param level: 服务端 root logger 的级别，同时也是主进程 ``kitty``
+        logger 的初始 level（仅在它仍是 ``NOTSET`` 时设置）。
     :param host: 监听地址，默认 ``127.0.0.1``。**必须是 loopback**：
                  绑定非 loopback 地址会直接 :class:`ValueError`。
     :param port: 监听端口；``0`` 让 OS 自动选择空闲端口。
@@ -152,8 +162,6 @@ def setup_logging(
     :param console_fmt: 控制台 handler 的 format 字符串。
     :param file_fmt: 文件 handler 的 format 字符串。
     :param datefmt: 时间戳的 ``strftime`` 格式；``None`` 走默认值。
-    :param attach_main_logger: 是否给主进程的 root logger 也挂一个
-        :class:`SocketHandler`，让主进程自身的日志走同一个服务。
     :return: 服务真实绑定到的 ``(host, port)``。
 
     .. note::
@@ -169,6 +177,22 @@ def setup_logging(
        请使用 ``multiprocessing.get_context("spawn")``，或在顶层用
        ``if __name__ == "__main__":`` 守卫配合默认 ``spawn`` 行为。
     """
+    # ``multiprocessing`` 启动出来的子进程里再次执行 setup_logging（典型
+    # 场景：spawn bootstrap 通过 ``_fixup_main_from_path`` 重新 import 主
+    # 脚本，从而触发主脚本顶层那行 ``kitty_logger.setup_logging(...)``）
+    # 一律走 no-op：日志服务只该在原始主进程里跑一份；子进程通过继承的
+    # ENV 找服务地址，``getLogger`` 第一次被调用时再按需挂 SocketHandler。
+    if mp.parent_process() is not None:
+        host_env = os.environ.get(ENV_HOST)
+        port_env = os.environ.get(ENV_PORT)
+        if not host_env or not port_env:
+            raise RuntimeError(
+                "kitty_logger 在子进程里被调用 setup_logging，但没有从父进程"
+                "继承到 KITTY_LOGGER_HOST / KITTY_LOGGER_PORT 环境变量。"
+                "请确保父进程已经先调用 setup_logging() 后再 spawn 本进程。"
+            )
+        return host_env, int(port_env)
+
     global _state
     if _is_running(state=_state):
         return _state["host"], _state["port"]
@@ -183,6 +207,16 @@ def setup_logging(
     # 被 ``kill -9`` 也会让内核 close 它的 fd，子进程在另一端会读到 EOF。
     parent_alive_send, parent_alive_recv = socket.socketpair()
 
+    # ENV 必须在 ``proc.start()`` 之前写入：spawn 出的服务子进程虽然通过
+    # kwargs 拿到了所有运行参数，但它在 bootstrap 阶段会用
+    # ``_fixup_main_from_path`` 重新 import 主脚本，主脚本顶层若间接触发
+    # ``kitty_logger.getLogger(...)``（例如某个被顶层 import 的库在模块级
+    # 调用了 getLogger），此时子进程必须已经能从 ENV 读到服务地址，否则
+    # 子进程会在 import 阶段抛 RuntimeError 而异常退出。
+    os.environ[ENV_HOST] = bound_host
+    os.environ[ENV_PORT] = str(bound_port)
+    os.environ[ENV_LEVEL] = str(level)
+
     ctx = mp.get_context("spawn")
     shutdown_event = ctx.Event()
     proc = ctx.Process(
@@ -209,13 +243,6 @@ def setup_logging(
     listening_sock.close()
     parent_alive_recv.close()
 
-    # ENV 是给"日后由本进程 spawn 出来的工作子进程"用的——它们靠 ENV
-    # 找到服务地址。服务子进程本身已经通过 kwargs 拿到所有参数，因此在
-    # ``proc.start()`` 之后再写 ENV 没有竞态问题。
-    os.environ[ENV_HOST] = bound_host
-    os.environ[ENV_PORT] = str(bound_port)
-    os.environ[ENV_LEVEL] = str(level)
-
     new_state: _RunningState = {
         "running": True,
         "host": bound_host,
@@ -226,11 +253,12 @@ def setup_logging(
     }
     _state = new_state
 
-    if attach_main_logger:
-        # 让主进程自身的日志也走同一个服务，避免输出渠道分裂。
-        from ._client import _attach_socket_handler
+    # 主进程也要把 ``kitty`` logger 初始化好——挂上 SocketHandler，让
+    # 主进程里 ``kitty_logger.getLogger(...)`` 拿到的子 logger 直接可用，
+    # 不需要再额外配置。
+    from ._client import _ensure_kitty_handler
 
-        _attach_socket_handler(logging.getLogger(), bound_host, bound_port, level)
+    _ensure_kitty_handler()
 
     _ = atexit.register(shutdown_logging)
     return bound_host, bound_port
@@ -244,6 +272,10 @@ def _detach_all_socket_handlers(host: str, port: int) -> None:
     （:mod:`logging` 静默吞掉 socket 错误，外部表现为日志凭空消失）。
     在 shutdown 时主动卸载，保证状态对称——``setup_logging`` 装上去什么，
     ``shutdown_logging`` 全部取下来。
+
+    新架构下整个进程理论上只有 ``kitty`` logger 持有 SocketHandler，但
+    仍按"扫所有 logger"的方式做兜底，便于早期版本里残留的 handler 也
+    能在 shutdown 时被清理掉。
     """
     from logging.handlers import SocketHandler
 
@@ -309,12 +341,6 @@ def shutdown_logging(timeout: float = 5.0) -> None:
     # 否则后续 logging 调用会向一个失效端口发送，触发静默丢日志。
     _detach_all_socket_handlers(host, port)
 
-    # 同步清理 _client 的 dedup 集合与 ENV，让"二次 setup"能真正回到
-    # 干净状态。
-    from . import _client
-
-    with _client._lock:
-        _client._configured_loggers.clear()
-
+    # 清掉环境变量，让"二次 setup"能真正回到干净状态。
     for k in (ENV_HOST, ENV_PORT, ENV_LEVEL):
         os.environ.pop(k, None)

{kitty_logger-0.2.0.dev0 → kitty_logger-0.2.0.dev2/src/kitty_logger.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kitty_logger
-Version: 0.2.0.dev0
+Version: 0.2.0.dev2
 Summary: Cross-process logging via a dedicated log server process and SocketHandler.
 Author: Kitty
 License: MIT
@@ -54,12 +54,20 @@ if __name__ == "__main__":
 
 ## API
 
-- `setup_logging(log_file=None, level=logging.INFO, host="127.0.0.1", port=0, stream=True, console_fmt=..., file_fmt=..., datefmt=None, attach_main_logger=True) -> (host, port)`
+- `setup_logging(log_file=None, level=logging.INFO, host="127.0.0.1", port=0, stream=True, console_fmt=..., file_fmt=..., datefmt=None) -> (host, port)`
   启动日志服务子进程（始终使用 `spawn`）。幂等。已通过 `atexit` 注册清理。
   `port=0` 让操作系统挑选空闲端口；返回真实绑定到的 `(host, port)`。
   **`host` 必须是 loopback**——绑定非 loopback 地址会直接 `ValueError`。
+  同时把主进程内 `logging.getLogger("kitty")` 这一个 logger 初始化好——挂上
+  `SocketHandler`、设置 level、关闭 `propagate`。**不动 root logger**。
+  在 `multiprocessing` 启动的子进程里再次调用本函数会自动 no-op，仅返回
+  从父进程继承的 `(host, port)`，因此可以直接放在模块顶层而不必用
+  `if __name__ == "__main__":` 包裹。
 - `getLogger(name=None) -> logging.Logger`
-  返回一个挂好 `SocketHandler`、指向日志服务的 logger。
+  返回挂在 `kitty` 命名空间下的 logger：`getLogger("foo")` 实际拿到的是
+  `logging.getLogger("kitty.foo")`，`getLogger()` 拿到的是 `kitty` 本身。
+  整个进程内只有 `kitty` 持有 `SocketHandler`，子 logger 通过标准库的祖先链
+  冒泡上来，无需重复挂载。
 - `shutdown_logging()` — 显式停止日志服务子进程。
 
 ## 为什么只支持 spawn
@@ -74,11 +82,12 @@ if __name__ == "__main__":
 
 ## 注意事项
 
-- **不要**在 `setup_logging(attach_main_logger=True)` 之前调用
-  `logging.basicConfig()`（或自行给 root logger 挂 `StreamHandler`）——
-  否则主进程会把每条记录输出两次：一次走本地 root handler，一次走日志
-  服务。要么让 kitty_logger 做唯一的配置入口，要么传
-  `attach_main_logger=False` 自行管理主进程的 handler。
+- **所有 logger 名都带 `kitty.` 前缀**，这是有意保留的标记：日志记录里
+  `%(name)s` 字段一眼可以和第三方库（urllib3、httpx 等）的输出区分。
+  `getLogger(__name__)` 在模块 `myapp.svc` 下实际得到的是 `kitty.myapp.svc`。
+- `kitty` 子树**不向 root 冒泡**：第三方库挂在 root 上的 handler 不会收到
+  kitty_logger 的日志，反之 root 上输出的日志也不会被 kitty_logger 转发。
+  两条输出渠道互不干扰。
 - `shutdown_logging()` 会卸载本进程内 kitty_logger 自己挂的
   `SocketHandler`，并清理 `KITTY_LOGGER_*` 环境变量，确保进程状态与
   `setup_logging` 对称。如果你额外挂了别的 handler，仍由你自己负责清理。

{kitty_logger-0.2.0.dev0 → kitty_logger-0.2.0.dev2}/tests/test_kitty_logger.py

@@ -4,6 +4,7 @@
 - 半包 / 中途断连不会导致服务端死循环或丢失后续记录。
 - 重复调用 ``setup_logging`` / ``shutdown_logging`` 是幂等的。
 - ``setup_logging`` 绑定非 loopback 地址会直接 ``ValueError``。
+- 新架构：``kitty`` 子树的 ``propagate`` 行为、子 logger 自动冒泡。
 """
 
 from __future__ import annotations
@@ -43,15 +44,14 @@ def _spawn_worker(idx: int) -> None:
 @pytest.fixture(autouse=True)
 def _isolate_state(monkeypatch):
     """确保每个用例都从干净的全局状态出发。"""
-    # setup_logging 是模块级单例，跑完后必须 shutdown 干净。
     yield
     try:
         kitty_logger.shutdown_logging()
     except Exception:
         pass
-    # 重置 _client 模块状态，避免集合泄漏到下一个用例。
-    _client._configured_loggers = set()
-    # 清掉测试期间挂上去的 SocketHandler。
+    # 清掉测试期间挂上去的 SocketHandler，并把 ``kitty`` 子树相关 logger
+    # 的状态（level / propagate / handlers）复位到默认值——避免前一个用例
+    # 残留的 ``propagate=False`` 把后一个用例的日志吞掉。
     for lg in [logging.getLogger()] + [
         obj
         for obj in logging.Logger.manager.loggerDict.values()
@@ -60,6 +60,9 @@ def _isolate_state(monkeypatch):
         for h in list(lg.handlers):
             if isinstance(h, logging.handlers.SocketHandler):
                 lg.removeHandler(h)
+        if lg.name == "kitty" or lg.name.startswith("kitty."):
+            lg.setLevel(logging.NOTSET)
+            lg.propagate = True
     # 清环境变量。
     for k in ("KITTY_LOGGER_HOST", "KITTY_LOGGER_PORT", "KITTY_LOGGER_LEVEL"):
         os.environ.pop(k, None)
@@ -89,6 +92,9 @@ def test_end_to_end_spawn(tmp_path: Path):
     )
     # 进程名应当出现在每行里，便于跨进程定位。
     assert "MainProcess" in text and "SpawnProcess" in text
+    # logger 名都带 ``kitty.`` 前缀。
+    assert "kitty.main" in text
+    assert "kitty.worker.0" in text
 
 
 def test_setup_logging_idempotent(tmp_path: Path):
@@ -215,32 +221,46 @@ def test_level_env_accepts_name(tmp_path: Path):
     assert _client._read_level() == logging.INFO
 
 
+def test_setup_attaches_handler_to_kitty_only(tmp_path: Path):
+    """setup_logging 只动 ``kitty`` logger，不去碰 root。"""
+    root = logging.getLogger()
+    before = list(root.handlers)
+    kitty_logger.setup_logging(
+        log_file=str(tmp_path / "app.log"),
+        stream=False,
+    )
+    after = list(root.handlers)
+    assert after == before, "setup_logging 不应改动 root logger 的 handlers"
+
+    kitty = logging.getLogger("kitty")
+    sock_handlers = [
+        h for h in kitty.handlers if isinstance(h, logging.handlers.SocketHandler)
+    ]
+    assert len(sock_handlers) == 1, "kitty logger 应当恰好挂一个 SocketHandler"
+    assert kitty.propagate is False, "kitty 不应向 root 冒泡"
+
+
 def test_shutdown_cleans_state(tmp_path: Path):
-    """shutdown 后：root 上的 SocketHandler 被卸载、ENV 被清、_configured_loggers 清空。"""
+    """shutdown 后：kitty 上的 SocketHandler 被卸载、ENV 被清。"""
     log_path = tmp_path / "app.log"
     kitty_logger.setup_logging(log_file=str(log_path), stream=False)
     _ = kitty_logger.getLogger("svc.a")
 
+    kitty = logging.getLogger("kitty")
     assert os.environ.get("KITTY_LOGGER_HOST")
-    assert any(
-        isinstance(h, logging.handlers.SocketHandler)
-        for h in logging.getLogger().handlers
-    )
-    assert _client._configured_loggers  # 至少包含 "svc.a"
+    assert any(isinstance(h, logging.handlers.SocketHandler) for h in kitty.handlers)
 
     kitty_logger.shutdown_logging()
 
     assert not any(
-        isinstance(h, logging.handlers.SocketHandler)
-        for h in logging.getLogger().handlers
+        isinstance(h, logging.handlers.SocketHandler) for h in kitty.handlers
     )
     for k in ("KITTY_LOGGER_HOST", "KITTY_LOGGER_PORT", "KITTY_LOGGER_LEVEL"):
         assert k not in os.environ
-    assert not _client._configured_loggers
 
 
 def test_setup_after_shutdown_uses_new_port(tmp_path: Path):
-    """shutdown 之后再 setup，新端口必须真正生效（旧 dedup 不能阻止重新挂 handler）。"""
+    """shutdown 之后再 setup，新端口必须真正生效。"""
     log_path = tmp_path / "app.log"
     h1, p1 = kitty_logger.setup_logging(log_file=str(log_path), stream=False)
     _ = kitty_logger.getLogger("svc.b")
@@ -251,37 +271,109 @@ def test_setup_after_shutdown_uses_new_port(tmp_path: Path):
     log = kitty_logger.getLogger("svc.b")
     log.info("after-restart")
 
-    # 新 logger 的 SocketHandler 必须指向新端口，不能还指向旧端口。
+    # ``kitty`` 上的 SocketHandler 必须指向新端口。
+    kitty = logging.getLogger("kitty")
     sock_handlers = [
-        h for h in log.handlers if isinstance(h, logging.handlers.SocketHandler)
+        h for h in kitty.handlers if isinstance(h, logging.handlers.SocketHandler)
     ]
-    assert sock_handlers, "expected a SocketHandler attached to svc.b after restart"
+    assert sock_handlers, "expected a SocketHandler attached to kitty after restart"
     assert all(h.port == p2 for h in sock_handlers)
     assert p1 != p2 or h1 == h2  # 端口可能被 OS 复用，只要 handler 指向当前端口即可
 
     _wait_for_lines(log_path2, lambda t: "after-restart" in t)
 
 
-def test_attach_main_logger_false_leaves_root_alone(tmp_path: Path):
-    root = logging.getLogger()
-    before = list(root.handlers)
+def test_attach_does_not_override_explicit_level(tmp_path: Path):
+    """用户已显式给 ``kitty`` 设置过 level，setup_logging 不应悄悄覆盖。"""
+    kitty = logging.getLogger("kitty")
+    kitty.setLevel(logging.DEBUG)
     kitty_logger.setup_logging(
         log_file=str(tmp_path / "app.log"),
+        level=logging.WARNING,
         stream=False,
-        attach_main_logger=False,
     )
-    after = list(root.handlers)
-    assert after == before, "attach_main_logger=False 不应改动 root logger 的 handlers"
+    assert kitty.level == logging.DEBUG
 
 
-def test_attach_does_not_override_explicit_level(tmp_path: Path):
-    """用户已显式设置的 level 不应被悄悄覆盖。"""
-    custom = logging.getLogger("explicit-level-user")
-    custom.setLevel(logging.DEBUG)
-    kitty_logger.setup_logging(
-        log_file=str(tmp_path / "app.log"),
-        level=logging.WARNING,
-        stream=False,
+def test_child_logger_propagates_to_kitty(tmp_path: Path):
+    """``getLogger("foo")`` 返回的 logger 名是 ``kitty.foo``，且会冒泡到 ``kitty``。"""
+    log_path = tmp_path / "app.log"
+    kitty_logger.setup_logging(log_file=str(log_path), stream=False)
+
+    log = kitty_logger.getLogger("foo.bar")
+    assert log.name == "kitty.foo.bar"
+    # 子 logger 自身没挂 SocketHandler——它靠 propagate 冒到 kitty。
+    assert not any(isinstance(h, logging.handlers.SocketHandler) for h in log.handlers)
+    assert log.propagate is True
+
+    log.info("from-foo-bar")
+    _wait_for_lines(log_path, lambda t: "from-foo-bar" in t and "kitty.foo.bar" in t)
+
+
+def test_server_resilient_to_module_level_getlogger_in_user_script(tmp_path: Path):
+    """回归：用户主脚本顶层 import 的库在模块级调用 kitty_logger.getLogger(...)
+    时，服务子进程在 ``spawn`` bootstrap 阶段也会触发该模块级调用，从而把
+    服务自身的 ``kitty`` logger 挂上一个指向本服务监听端口的 SocketHandler，
+    使得接收到的 record 顺着祖先链被发回服务自身、永远不落地。
+    ``run_server`` 必须在开始 serve 之前把 ``kitty`` logger 还原成无 handler、
+    propagate=True 的状态。
+    """
+    import subprocess
+    import sys as _sys
+
+    fake_lib = tmp_path / "fake_lib.py"
+    fake_lib.write_text(
+        "import kitty_logger\n" "log = kitty_logger.getLogger(__name__)\n",
+        encoding="utf-8",
+    )
+
+    log_file = tmp_path / "app.log"
+    main_py = tmp_path / "main.py"
+    main_py.write_text(
+        "import sys, logging, time\n"
+        f"sys.path.insert(0, {str(tmp_path)!r})\n"
+        "from kitty_logger import setup_logging, getLogger\n"
+        "if __name__ == '__main__':\n"
+        f"    setup_logging(log_file={str(log_file)!r}, stream=False, level=logging.DEBUG)\n"
+        "import fake_lib  # noqa: E402,F401  -- 模块级 getLogger 触发回归路径\n"
+        "if __name__ == '__main__':\n"
+        "    getLogger('user').info('real-user-log')\n"
+        "    time.sleep(1)\n",
+        encoding="utf-8",
+    )
+
+    result = subprocess.run(
+        [_sys.executable, str(main_py)],
+        capture_output=True,
+        text=True,
+        timeout=20,
+    )
+    assert result.returncode == 0, f"stderr={result.stderr}"
+
+    text = _wait_for_lines(log_file, lambda t: "real-user-log" in t)
+    assert "kitty.user" in text
+
+
+def _spawn_worker_calling_setup(idx: int, log_file: str) -> None:
+    """子进程里也调一次 setup_logging：应该是 no-op，仅返回从 ENV 继承的端点。"""
+    h, p = kitty_logger.setup_logging(log_file=log_file, stream=False)
+    log = kitty_logger.getLogger(f"child.{idx}")
+    log.info("child says host=%s port=%s", h, p)
+
+
+def test_setup_logging_in_child_is_noop(tmp_path: Path):
+    """子进程里调用 setup_logging() 不应再起监听器，仅返回从 ENV 继承的端点。"""
+    log_path = tmp_path / "app.log"
+    host, port = kitty_logger.setup_logging(log_file=str(log_path), stream=False)
+
+    ctx = mp.get_context("spawn")
+    p = ctx.Process(target=_spawn_worker_calling_setup, args=(0, str(log_path)))
+    p.start()
+    p.join(timeout=10)
+    assert p.exitcode == 0
+
+    text = _wait_for_lines(
+        log_path,
+        lambda t: f"host={host} port={port}" in t and "kitty.child.0" in t,
     )
-    _ = kitty_logger.getLogger("explicit-level-user")
-    assert custom.level == logging.DEBUG
+    assert "SpawnProcess" in text

kitty_logger-0.2.0.dev0/src/kitty_logger/_client.py

@@ -1,102 +0,0 @@
-"""子进程侧 API：:func:`getLogger`。
-
-子进程通过环境变量
-``KITTY_LOGGER_HOST`` / ``KITTY_LOGGER_PORT`` / ``KITTY_LOGGER_LEVEL``
-找到日志服务地址；这些环境变量是父进程在 :func:`setup_logging` 时写入的，
-``spawn`` 出来的后代进程会自动继承。
-"""
-
-import logging
-import logging.handlers
-import os
-import threading
-
-from ._env import ENV_HOST, ENV_LEVEL, ENV_PORT
-
-# 保护下面这个模块级集合的并发访问。
-_lock = threading.Lock()
-
-# 已挂过 SocketHandler 的 logger 名集合，用于在同一进程内做去重。
-# root logger 在集合里以空字符串 ``""`` 作为 key。
-_configured_loggers: set[str] = set()
-
-
-def _read_endpoint() -> tuple[str, int]:
-    """从环境变量读出 ``(host, port)``；未设置则抛出友好错误。"""
-    host = os.environ.get(ENV_HOST)
-    port = os.environ.get(ENV_PORT)
-    if not host or not port:
-        raise RuntimeError(
-            "kitty_logger 尚未在当前进程树中初始化。"
-            + "请先在主进程调用 kitty_logger.setup_logging()，"
-            + "再创建（spawn）子进程或调用 getLogger()。"
-        )
-    return host, int(port)
-
-
-def _read_level() -> int:
-    """从环境变量解析默认 level。优先按整数解析，失败则按级别名解析。"""
-    raw = os.environ.get(ENV_LEVEL)
-    if raw is None:
-        return logging.INFO
-    try:
-        return int(raw)
-    except ValueError:
-        pass
-    return logging.getLevelNamesMapping().get(raw.upper(), logging.INFO)
-
-
-def _attach_socket_handler(
-    logger: logging.Logger,
-    host: str,
-    port: int,
-    level: int,
-) -> None:
-    """给 ``logger`` 挂上指向日志服务的 :class:`SocketHandler`。
-
-    .. note::
-       :class:`logging.handlers.SocketHandler` 直接 pickle ``LogRecord``
-       发送，由接收端格式化；在这里给 handler 设置 ``formatter`` 没有
-       任何效果，会被服务端忽略。
-    """
-    SocketHandler = logging.handlers.SocketHandler
-
-    # 同一 logger 上避免重复挂指向相同端点的 SocketHandler——例如模块被
-    # 重新 import、或测试用例反复 setup 的场景。
-    for h in logger.handlers:
-        if isinstance(h, SocketHandler) and (h.host, h.port) == (host, port):
-            return
-
-    logger.addHandler(SocketHandler(host, port))
-
-    # 仅在 logger 仍是默认 ``NOTSET`` 时才设置 level，避免悄悄覆盖
-    # 用户已经显式设置过的级别。
-    if logger.level == logging.NOTSET:
-        logger.setLevel(level)
-
-    # 关闭向 root 的传播，避免与已存在的 root handler（比如调用过
-    # ``basicConfig``）造成重复输出。root 自身没有父级，跳过此项。
-    if logger is not logging.getLogger():
-        logger.propagate = False
-
-
-def getLogger(name: str | None = None) -> logging.Logger:
-    """返回一个会把日志通过 :class:`SocketHandler` 发送到日志服务的 logger。
-
-    必须在父进程已经调用过 :func:`kitty_logger.setup_logging` 之后才能
-    使用。本库只支持 ``spawn`` 启动方式；spawn 出来的子进程模块级状态
-    天然为空，因此不需要处理"继承自父进程的 SocketHandler"问题。
-
-    :param name: logger 名；``None`` 表示 root logger。
-    :raises RuntimeError: 当前进程树尚未调用 ``setup_logging``。
-    """
-    host, port = _read_endpoint()
-    level = _read_level()
-    logger = logging.getLogger(name)
-
-    with _lock:
-        key = name or ""
-        if key not in _configured_loggers:
-            _attach_socket_handler(logger, host, port, level)
-            _configured_loggers.add(key)
-    return logger