litestar-logging

日志记录

执行工作流

1. 首先选择日志后端：stdlib logging、picologging、Structlog 或自定义配置子类。
2. 在应用设置时，通过 logging_config 或 Structlog 插件配置一次日志记录。
3. 除非有明确原因，否则在 Litestar 中使用非阻塞的 queue_listener 处理器。
4. 决定何时记录异常，以及应抑制哪些堆栈跟踪。
5. 统一请求日志记录器和应用日志记录器的用法，确保字段、级别和脱敏规则保持一致。
6. 验证日志仍然具有可操作性，同时不会泄露敏感数据。

核心规则

• 在构建应用时集中配置日志记录。
• 对异步应用，优先使用内置的非阻塞 queue_listener 处理器。
• 将异常日志策略作为明确的决策；除调试模式外，Litestar 默认不会记录异常。
• 对不应频繁输出跟踪信息的预期异常类型或状态码，使用 disable_stack_trace。
• 避免将机密信息、认证材料和敏感请求数据写入日志。
• 避免在中间件、异常处理器和业务代码中重复记录日志。
• 将日志记录与指标和跟踪分开处理。

决策指南

• 对标准日志记录或基于 picologging 的设置，使用 LoggingConfig。
• 如果需要使用 picologging 作为后端，请设置 logging_module="picologging"。
• 如果项目标准是使用 Structlog 进行结构化日志记录，请使用 StructlogPlugin。
• 如果生产环境的事故处理要求即使在调试模式之外也记录异常，请使用 log_exceptions="always"。
• 对常见的预期错误（例如 404 或领域级验证问题），使用 disable_stack_trace。
• 只有当内置配置无法表达所需行为时，才继承 BaseLoggingConfig。

参考文件

只阅读所需章节：

• 有关 stdlib logging、picologging、日志记录器访问和自定义配置子类，请阅读 references/configuration-patterns.md。
• 有关异常日志记录、堆栈跟踪抑制、Structlog 和脱敏指南，请阅读 references/exception-and-structlog-patterns.md。

建议的默认设置

• 明确指定根级别、处理器选择和格式化器格式。
• 使用 request.logger 记录请求范围内的日志，并使用一个共享的应用日志记录器记录应用级事件。
• 有意记录异常，而不是假设 Litestar 会代劳。
• 仅对预期的高频故障抑制跟踪信息。
• 保持消息字段和键名稳定，以便搜索。

反模式

• 在异步请求路径中使用阻塞式日志处理器，而 queue_listener 已足够满足需求。
• 记录机密信息、令牌或未经处理的敏感负载。
• 在多个层中记录同一故障，却没有提供额外上下文。
• 对运维人员已了解的高频预期故障启用堆栈跟踪。
• 尚未充分尝试内置选项，就先继承日志配置类。

验证清单

• 确认日志配置恰好执行一次。
• 确认请求和应用日志记录器按预期级别输出日志。
• 确认 log_exceptions 和 disable_stack_trace 符合事故处理策略。
• 确认机密信息和敏感请求字段已被移除或脱敏。
• 确认已使用基于队列的处理器或其他等效的非阻塞机制。
• 确认结构化日志输出符合下游日志采集的预期。

跨技能衔接

• 使用 litestar-metrics 处理定量可观测性以及抓取／导出相关事项。
• 使用 litestar-exception-handling 处理与日志行为分离、面向客户端的错误契约。
• 使用 litestar-debugging 处理由事故驱动的故障排查工作流。
• 当日志策略涉及机密信息、认证上下文或脱敏要求时，使用 litestar-security。

Litestar 参考资料

• https://docs.litestar.dev/latest/usage/logging.html