日志应分级语义化、统一链路追踪、多渠道动态采样、结构化输出并集成可观测体系：DEBUG仅开发用，INFO记关键节点，WARNING标需关注行为，ERROR带完整上下文，CRITICAL限服务宕机等；全链路透传trace_id与span_id；INFO异步落盘，ERROR实时告警，DEBUG热启；采样支持固定率、条件触发与错误突增自动升频；采用JSON结构化日志，含UTC时间戳、service_name、event等字段，并与OpenTelemetry联动实现日志-指标-链路三合一查询。
日志分级与语义化命名
日志不是越详细越好，而是要让每条日志在上下文中可理解、可追溯。关键在于定义清晰的级别语义：DEBUG 仅用于开发期诊断；INFO 表示正常流程中的关键节点（如“用户登录成功”）；WARNING 指代非中断但需关注的行为（如“缓存未命中，回源加载”）；ERROR 必须携带完整上下文（异常类型、堆栈、请求ID、输入参数摘要）；CRITICAL 仅用于服务不可用或数据损坏等必须人工介入的场景。
避免使用模糊描述如“操作失败”，应改为“支付回调验证签名失败，商户ID=1024，timestamp=1712345678”。建议在日志消息中内嵌结构化字段（如 JSON 键值对），而非拼接字符串，便于后续解析与过滤。
统一上下文传递与请求链路追踪
单次请求跨模块、跨线程甚至跨进程时，日志容易失联。解决方案是构建轻量级上下文载体（如 LogContext），在入口处生成唯一 trace_id，并自动注入到 logging 的 LoggerAdapter 或 Filter 中。所有子日志自动携带该 ID 和 span_id（可选），无需手动传参。
常见实践包括：
立即学习“Python免费学习笔记（深入）”；
- HTTP 请求中间件中提取或生成 trace_id（优先从 header 如 X-Trace-ID 获取）
- 异步任务（Celery/asyncio）通过 task headers 或 contextvars 透传上下文
- 数据库查询、RPC 调用等 I/O 操作的日志自动附加当前 span_id 和耗时
多渠道输出与动态采样策略
生产环境不应对所有日志一视同仁。INFO 级别日志量大但价值密度低，适合异步写入文件并按天轮转；ERROR 及以上必须实时推送至告警通道（如企业微信/钉钉机器人 + Elasticsearch + Kibana）；DEBUG 日志默认关闭，可通过配置中心热启（配合 watch 配置变更）。
对高频低风险事件（如“用户刷新首页”）启用采样，例如：
- 固定采样率：1% 的 INFO 日志进入 ELK
- 条件采样：仅当 user_id % 100 == 0 时记录详情日志
- 错误突增触发全量捕获：过去 5 分钟 ERROR 数量环比上涨 300%，自动提升采样率至 100%
结构化日志与可观测性集成
原始文本日志不利于聚合分析。推荐使用 structlog 或 python-json-logger 输出标准 JSON 格式，确保每条日志含：timestamp、level、trace_id、service_name、module、function、line、event（语义化动作名）、extra（业务字段）。
与可观测体系打通的关键点：
- 日志时间戳严格使用 UTC，避免时区混乱
- 预留 metrics 字段，支持直接提取数值型指标（如 “duration_ms”: 127.4）用于 Prometheus 直采
- 在 OpenTelemetry SDK 中复用 trace_id，实现日志、指标、链路三者关联查询
