一句话定义
日志按级别记录程序事件,并通过时间、来源和关联字段帮助还原运行过程。日志与指标、链路追踪一起支持排查故障。
为什么重要
- 线上没有调试器:服务器上的程序出了问题,可结合日志、指标、链路追踪与进程状态调查。
- 比 print 强在哪:有级别(可按需开关)、有时间和来源、可同时输出到多处(控制台、文件、日志平台)、可结构化检索。
- 可观测性的三大支柱之一:日志(Logs)、指标(Metrics)、链路追踪(Traces)。OpenTelemetry 对这三类信号的定义:https://opentelemetry.io/docs/concepts/signals/
使用边界
惰性格式化只推迟字符串拼接:logger.debug("x=%s", expensive()) 仍会先调用 expensive。昂贵的参数计算需先检查 isEnabledFor;脱敏应覆盖消息、extra 与异常内容。
原理 / 图解
Python 标准库 logging 的核心组件:
| 级别 | 数值 | 用途 |
|---|---|---|
| DEBUG | 10 | 开发调试的细节(请求体大小、中间变量) |
| INFO | 20 | 正常的关键事件(服务启动、调用模型) |
| WARNING | 30 | 值得注意但不影响运行(接近限流、使用了默认值) |
| ERROR | 40 | 某个操作失败 |
| CRITICAL | 50 | 整个程序可能无法继续 |
logging 官方 HOWTO 与 Cookbook:https://docs.python.org/3/howto/logging.html 、https://docs.python.org/3/howto/logging-cookbook.html
可运行示例
两个 Handler:控制台给人看(文本、INFO 以上),内存缓冲给机器看(JSON、DEBUG 以上),并演示 extra 上下文、logger.exception 和密钥脱敏(Python 3.15.0 一稿运行记录,示例 key 为伪造):
# 文件:examples/17_logging.py
# 日志:分级、结构化、带上下文;与 print 的区别
import logging, json, io, sys
class JsonFormatter(logging.Formatter):
def format(self, record):
payload = {"level": record.levelname, "logger": record.name, "msg": record.getMessage()}
if hasattr(record, "request_id"):
payload["request_id"] = record.request_id
if record.exc_info:
payload["exc"] = self.formatException(record.exc_info).splitlines()[-1]
return json.dumps(payload, ensure_ascii=False)
logger = logging.getLogger("app.llm")
logger.setLevel(logging.DEBUG)
console = logging.StreamHandler(sys.stdout) # 人看的:文本格式,INFO 以上
console.setLevel(logging.INFO)
console.setFormatter(logging.Formatter("%(levelname)-7s %(name)s: %(message)s"))
buffer = io.StringIO()
machine = logging.StreamHandler(buffer) # 机器看的:JSON,DEBUG 以上
machine.setFormatter(JsonFormatter())
logger.addHandler(console); logger.addHandler(machine)
logger.debug("请求体大小=%d tokens", 1234) # 只进 JSON
logger.info("调用模型", extra={"request_id": "req-7"})
logger.warning("接近速率限制: 剩余 %d 次", 3)
try:
1 / 0
except ZeroDivisionError:
logger.exception("计算失败", extra={"request_id": "req-8"})
print("---- JSON 日志(可被 ELK/Loki 等系统检索)----")
print(buffer.getvalue().strip())
# 安全:日志里不要出现密钥
api_key = "sk-abcdef1234567890"
logger.info("使用 key=%s", api_key[:5] + "***")
一稿留存输出:
INFO app.llm: 调用模型
WARNING app.llm: 接近速率限制: 剩余 3 次
ERROR app.llm: 计算失败
Traceback (most recent call last):
File "17_logging.py", line 28, in <module>
1 / 0
~~^~~
ZeroDivisionError: division by zero
---- JSON 日志(可被 ELK/Loki 等系统检索)----
{"level": "DEBUG", "logger": "app.llm", "msg": "请求体大小=1234 tokens"}
{"level": "INFO", "logger": "app.llm", "msg": "调用模型", "request_id": "req-7"}
{"level": "WARNING", "logger": "app.llm", "msg": "接近速率限制: 剩余 3 次"}
{"level": "ERROR", "logger": "app.llm", "msg": "计算失败", "request_id": "req-8", "exc": "ZeroDivisionError: division by zero"}
INFO app.llm: 使用 key=sk-ab***
观察:
DEBUG那条只出现在 JSON 中,控制台没有——同一条日志,不同目的地按不同级别过滤。logger.exception自动附带了完整的栈追踪。request_id让你能把同一请求的所有日志串起来。
常见误区
- 用 f-string 拼日志:
logger.debug(f"x={big()}")即使 DEBUG 关闭也会计算big()。推荐logger.debug("x=%s", x)的惰性格式化;若参数本身计算昂贵,还需检查logger.isEnabledFor(logging.DEBUG);若参数本身计算昂贵,还需检查logger.isEnabledFor(logging.DEBUG)。https://docs.python.org/3/howto/logging.html#optimization - 在库代码里调用
logging.basicConfig:配置日志是应用程序的事,库只应getLogger(__name__)。官方 HOWTO 的“为库配置日志”一节:https://docs.python.org/3/howto/logging.html#configuring-logging-for-a-library - 日志里记录密钥、密码、完整用户隐私数据:日志往往保存很久、权限更宽,是数据泄露的常见渠道。
- 什么都记:日志太多等于没有日志,还会产生存储成本。
- 用
print代替日志上线。
与 AI 开发的关系
- LLM 应用必须记录的东西:模型名与版本、提示词模板版本、token 用量、延迟、请求 ID、工具调用参数与结果、错误与重试次数。没有这些就无法复现“为什么昨天好好的今天答错了”。
- 隐私与合规:用户输入可能包含个人信息,记录前要脱敏或采样,并遵守所在地区的数据保护规定。
- LLM 可观测平台:如 Langfuse、LangSmith、Arize Phoenix,以及 OpenTelemetry 的生成式 AI 语义约定,把日志、链路追踪与 token 成本放在一起分析。OpenTelemetry GenAI 语义约定:https://github.com/open-telemetry/semantic-conventions-genai
- 训练日志:训练损失、学习率等通常用 TensorBoard、Weights & Biases 等专用工具记录,而不是普通文本日志。
延伸阅读
- Logging HOWTO:https://docs.python.org/3/howto/logging.html
- Logging Cookbook:https://docs.python.org/3/howto/logging-cookbook.html
- structlog(结构化日志库):https://www.structlog.org/
- OpenTelemetry 信号概念:https://opentelemetry.io/docs/concepts/signals/
理解检查
DEBUG 被关闭时,参数中的昂贵函数还会运行吗?
参考答案:会。函数参数在调用 logging 方法前已求值,只有格式化过程可以被推迟。
核验与复现
核验日期:2026-10-14。示例状态:运行通过。本轮日志:17_logging.py。
配套代码与核验资料