Python Academy · 课时

结构化日志记录

Q: 「结构化日志记录」这节课中我会学到什么？

输出 JSON 格式的日志，生成机器可读的数据。 你通过在浏览器中直接运行的动手代码来练习 Python Academy，全天候 AI 导师会在你学习这节课的过程中回答你的问题。

输出 JSON 格式的日志，生成机器可读的数据。

结构化日志记录 是 CoddyKit 上的免费 Python Academy 课时。这是第 3 节课，共 4 节。你可以在下方免费阅读本课时的完整内容 — 然后在浏览器中使用内置代码编辑器和全天候 AI 导师进行实践。这是 Python Academy 学习路径的一部分，你的进度在网页和 CoddyKit 应用中同步。 Python Academy 课程共包含 4 节课。

什么是结构化日志记录？

结构化日志记录会将日志记录以机器可读的数据（JSON）形式输出，而不是自由格式的文本，因此便于建立索引、搜索和设置告警。

import logging, json

def log_json(level, msg, **kw):
    record = {"level": level, "msg": msg, **kw}
    print(json.dumps(record))

log_json("INFO", "Request received", path="/api/users", method="GET")

自定义 JSON 格式化器

继承 logging.Formatter，即可输出 JSON，而不是普通文本。

import logging, json

class JSONFormatter(logging.Formatter):
    def format(self, record):
        return json.dumps({
            "time": self.formatTime(record),
            "level": record.levelname,
            "name": record.name,
            "msg": record.getMessage(),
        })

handler = logging.StreamHandler()
handler.setFormatter(JSONFormatter())
logging.getLogger().addHandler(handler)

python-json-logger

python-json-logger 软件包提供开箱即用的 JSON 格式化器，并支持标准字段和额外字段。

# pip install python-json-logger
import logging
from pythonjsonlogger import jsonlogger

logger = logging.getLogger()
handler = logging.StreamHandler()
handler.setFormatter(jsonlogger.JsonFormatter())
logger.addHandler(handler)
logger.info("User created", extra={"user_id": 42})

structlog

structlog 是一个常用的第三方库，它将上下文累积与格式化分离，并支持处理器管道。

# pip install structlog
import structlog

log = structlog.get_logger()
log = log.bind(request_id="abc123")
log.info("payment_processed", amount=49.99, currency="USD")

使用 structlog 绑定上下文

structlog 可以将键值对绑定到日志记录器上，使其在之后的所有调用中持续有效。

import structlog

log = structlog.get_logger().bind(
    service="auth",
    env="prod"
)
log.warning("login_failed", user="alice", reason="bad_password")
# {service:auth, env:prod, user:alice, reason:bad_password}

添加时间戳和调用方信息

处理器可以自动丰富记录。将 TimeStamper 和 CallsiteParameterAdder 添加到每条日志记录中。

import structlog

structlog.configure(
    processors=[
        structlog.processors.TimeStamper(fmt="iso"),
        structlog.processors.CallsiteParameterAdder([structlog.processors.CallsiteParameter.FILENAME]),
        structlog.processors.JSONRenderer(),
    ]
)

在 Web 应用中记录请求 ID

在 Web 框架中，请在每个请求开始时绑定请求 ID，这样该请求期间的每一行日志都会包含这个 ID。

import structlog

def middleware(request, call_next):
    req_id = request.headers.get("X-Request-Id", generate_id())
    log = structlog.get_logger().bind(request_id=req_id)
    log.info("request_started", path=request.url.path)
    response = call_next(request)
    log.info("request_finished", status=response.status_code)
    return response

ECS 日志格式

Elastic Common Schema（ECS）是 Elastic Stack 使用的标准 JSON 日志格式。对于 Python，请使用 ecs-logging。

# pip install ecs-logging
import logging
import ecs_logging

logger = logging.getLogger("app")
handler = logging.StreamHandler()
handler.setFormatter(ecs_logging.StdlibFormatter())
logger.addHandler(handler)
logger.info("Event logged in ECS format")

日志聚合系统

结构化 JSON 日志可以自然地流入各种聚合工具：Elasticsearch/Kibana（ELK）、Grafana Loki、Datadog、AWS CloudWatch Logs Insights。

# Loki query example:
# {app="myservice"} | json | level="ERROR"

# CloudWatch Insights:
# fields @timestamp, level, msg
# | filter level = "ERROR"
# | sort @timestamp desc

避免在日志中记录 PII

记录日志前请清除个人身份信息。使用自定义处理器或过滤器遮盖电子邮件地址、令牌和密码。

import re

def mask_pii(_, __, event_dict):
    msg = event_dict.get("event", "")
    event_dict["event"] = re.sub(
        r"[\w.+-]+@[\w-]+\.[\w.]+", "***@***.***", msg
    )
    return event_dict

结构化日志与非结构化日志的权衡

结构化日志便于搜索和设置告警，但内容较为冗长。生产环境使用结构化日志，开发环境使用便于人工阅读的格式，并通过基于环境的配置进行切换。

import structlog, os

if os.getenv("ENV") == "production":
    renderer = structlog.processors.JSONRenderer()
else:
    renderer = structlog.dev.ConsoleRenderer()

structlog.configure(processors=[renderer])

快速检查

与纯文本日志相比，JSON 结构化日志的主要优势是什么？

回顾

结构化日志记录会输出键值形式的 JSON 记录。可以使用 JSONFormatter、python-json-logger 或 structlog。在操作开始时绑定上下文（请求 ID、用户），这样该操作期间的每一行日志都会携带这些上下文。

常见问题解答

「结构化日志记录」课时是免费的吗？

是的 — 「结构化日志记录」的完整文本可在网页上免费阅读。要进行交互式练习（内置代码编辑器和全天候 AI 导师）并解锁 Python Academy 课程的其余内容，请升级到 CoddyKit PRO。 Python Academy 课程共包含 4 节课。

「结构化日志记录」这节课中我会学到什么？

输出 JSON 格式的日志，生成机器可读的数据。你通过在浏览器中直接运行的动手代码来练习 Python Academy，全天候 AI 导师会在你学习这节课的过程中回答你的问题。

学习 Python Academy 需要有经验吗？

无需任何先前经验。CoddyKit 上的 Python Academy 课程适合初学者到高级学习者，你可以从这里开始或从头开始，按照自己的节奏学习。这是第 3 节课，共 4 节。

「结构化日志记录」课时需要多长时间？

大多数 CoddyKit 课程大约需要 5–10 分钟。每节课都很精短且互动，所以你能稳步进步，并在网页和应用中从离开的地方继续。

我能在这节 Python Academy 课中编写并运行代码吗？

能。每节 Python Academy 课都包含内置代码编辑器，你可以在浏览器中直接编写并运行真实代码，并获得即时 AI 反馈 — 无需本地设置。

此课程中的所有课时

← 返回 Python Academy