17370845950

Python日志系统需兼顾可读性、可维护性、可追溯性和运行时可控性，核心是分离关注点；应使用logging.getLogger(__name__)获取命名记录器，避免污染root logger，并通过dictConfig()声明式配置，在启动早期统一管理handlers、formatters、filters及结构化日志。

Python 日志系统不是“能打印就行”，而是要兼顾可读性、可维护性、可追溯性和运行时可控性。核心在于分离关注点：谁打日志（业务代码）、怎么打（格式与级别）、输出到哪（handler）、如何过滤（filter）以及何时生效（配置时机）。

用 logging.getLogger(__name__) 获取命名记录器

避免直接使用 logging.debug() 这类模块级函数，它们会污染 root logger，导致日志行为不可控。每个模块应通过 logging.getLogger(__name__) 获取专属记录器，形成层级结构（如 myapp.api.auth），便于统一配置和精细控制。

• 子模块继承父 logger 的 handler 和 level，但可单独调整
• 调试某个模块时，只需临时提升其日志级别：logging.getLogger("myapp.db").setLevel(logging.DEBUG)
• 避免硬编码字符串名，__name__ 自动适配包结构

用 di

ctConfig() 声明式配置，而非零散的 basicConfig() 或 addHandler()

在应用启动早期（如 main.py 或 app init 阶段）一次性加载字典配置，清晰表达日志流向与规则。basicConfig() 只作用于 root logger 且不可逆，不适合多 handler、多 level 场景。

• 配置中明确指定 handlers（如 console + rotating file）、formatters（含时间、模块、行号）、filters（按关键字或等级过滤）
• 支持环境变量切换配置（开发用 console，生产用 JSON 格式文件 + syslog handler）
• 示例 key："version": 1, "disable_existing_loggers": False —— 确保第三方库 logger 不被意外关闭

结构化日志优先，避免拼接字符串

用 logger.info("User %s logged in from %s", user_id, ip) 替代 logger.info(f"User {user_id} logged in from {ip}")。前者延迟格式化，不触发时无性能开销；更重要的是，为未来接入 ELK、Loki 等系统预留结构化解析能力。

• 敏感字段（密码、token）绝不出现在日志消息中，可用占位符 + filter 脱敏
• 需要额外上下文（如 request_id、trace_id）时，用 LoggerAdapter 注入，而不是每次手动传参
• 异常记录统一用 logger.exception("Failed to process order") 或 logger.error("...", exc_info=True)

日志级别要有实际语义，避免滥用 INFO

DEBUG：仅开发/排查时开启，含详细流程变量；INFO：用户可观测的关键状态（服务启动、任务完成、配置加载）；WARNING：可能影响体验但未中断的异常（重试成功、降级生效）；ERROR：功能失败，需人工介入；CRITICAL：服务不可用。

• 禁止在循环里打 INFO 日志，改用 DEBUG 或聚合统计后输出
• INFO 不该包含堆栈、大对象 dump 或高频事件（如每秒请求计数应走 metrics，非日志）
• 上线前检查所有 ERROR 日志是否附带可操作线索（哪个参数非法？上游返回什么？）