结构化日志字段命名须用 snake_case，禁用 pascalcase/camelcase；避免 python 保留字；禁止动态值嵌入字段名；extra 参数仅支持扁平字典；时间字段统一用带时区的 iso 8601 timestamp；敏感字段必须前置脱敏；字段设计需兼顾长期兼容性。
字段命名必须用 snake_case，别碰 PascalCase 或 camelCase
结构化日志最终常被写入 Elasticsearch、Loki 或解析进 Pandas，这些系统对字段名大小写和分隔符极其敏感。user_id 能自动映射为 keyword 类型，userId 可能被拆成 userid 或触发 analyzer 分词，查都查不到。
实操建议：
立即学习“Python免费学习笔记（深入）”；
- 所有字段名统一走
snake_case，包括从第三方库（如requests）取的原始键，比如把responseTime改成response_time - 避免用 Python 保留字作字段名，比如
type、id、class——Elasticsearch 会报invalid field name错误 - 不要在字段名里塞动态值，例如
user_123_action，这会让日志 schema 失控，聚合分析直接报废
logger.info() 的 extra 参数只接收字典，且不能嵌套
很多人以为 extra 能传任意结构，结果日志里出现 "extra": "{...}" 这种字符串，字段根本不可检索。LogRecord 本身不序列化嵌套结构，只会调 str()，导致 JSON 字段变成字符串。
实操建议：
立即学习“Python免费学习笔记（深入）”；
-
extra必须是扁平字典，深度为 1，例如：{"user_id": 42, "endpoint": "/api/v1/order", "status_code": 200} - 需要嵌套语义？提前展平：
{"order_item_count": 3, "order_total_usd": 99.99}，而不是{"order": {"items": 3, "total": 99.99}} - 如果真要存原始 JSON（比如 webhook payload），用单独字段 + 显式序列化：
"webhook_payload_json": json.dumps(payload, separators=(',', ':'))
时间字段必须用 time 或 timestamp，且带时区信息
默认 logging 模块输出的时间是本地时区字符串，没有 ISO 格式，也没时区偏移。下游系统（如 Grafana + Loki）依赖标准时间字段做排序、范围查询、时序对齐——缺时区或格式不一致，跨服务日志就对不上时间线。
实操建议：
立即学习“Python免费学习笔记（深入）”；
- 固定用
timestamp字段名，值为 ISO 8601 字符串，带Z或+00:00，例如："timestamp": "2024-05-22T14:30:45.123Z" - 别用
datetime.now()，改用datetime.now(timezone.utc)；序列化时显式调.isoformat() - 如果用
structlog，配structlog.processors.TimeStamper(fmt='iso')，它默认带 UTC 和微秒精度
敏感字段必须在写入前脱敏，不能靠日志系统后期过滤
日志一旦落盘，尤其进了集中式系统（如 ELK），再想删字段或掩码，成本极高，还可能违反审计要求。等发现 password、auth_token、ssn 出现在日志里，已经晚了。
实操建议：
立即学习“Python免费学习笔记（深入）”；
- 在构造
extra字典时就做清洗：遇到password、token、api_key等关键词，直接替换成"***"或None - 用白名单机制比黑名单更可靠：只允许明确列出的字段进入日志，其余一律丢弃或打标
"redacted": true - 别信中间件或日志采集器的“字段过滤”功能——它们可能漏掉 raw message、traceback 里的敏感内容
字段设计不是一次定稿的事。服务越久，业务字段越多，上下游系统对 schema 的容忍度越低。最麻烦的往往不是加字段，而是改已有字段类型或重命名——这时候你得翻遍所有日志消费方，一个一个确认兼容性。
