日志(Logging)

日志按级别记录程序事件,并通过时间、来源和关联字段帮助还原运行过程。日志与指标、链路追踪一起支持排查故障。

一句话定义

日志按级别记录程序事件,并通过时间、来源和关联字段帮助还原运行过程。日志与指标、链路追踪一起支持排查故障。

为什么重要

  • 线上没有调试器:服务器上的程序出了问题,可结合日志、指标、链路追踪与进程状态调查。
  • 比 print 强在哪:有级别(可按需开关)、有时间和来源、可同时输出到多处(控制台、文件、日志平台)、可结构化检索。
  • 可观测性的三大支柱之一:日志(Logs)、指标(Metrics)、链路追踪(Traces)。OpenTelemetry 对这三类信号的定义:https://opentelemetry.io/docs/concepts/signals/

使用边界

惰性格式化只推迟字符串拼接:logger.debug("x=%s", expensive()) 仍会先调用 expensive。昂贵的参数计算需先检查 isEnabledFor;脱敏应覆盖消息、extra 与异常内容。

原理 / 图解

Python 标准库 logging 的核心组件:

图 1
级别 数值 用途
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 等专用工具记录,而不是普通文本日志。

延伸阅读

理解检查

DEBUG 被关闭时,参数中的昂贵函数还会运行吗?

参考答案:会。函数参数在调用 logging 方法前已求值,只有格式化过程可以被推迟。

核验与复现

核验日期:2026-10-14。示例状态:运行通过。本轮日志:17_logging.py。

配套代码与核验资料

继续浏览基础 返回知识 →返回顶部 ↑
本篇目录
教程图解100%
教程图解