日志内容设计：关键字段与敏感信息保护

做日志架构这么多年，我最深的一个感触是——内容设计决定了日志的“有用性”和“安全性”。字段漏了，排查问题像大海捞针；敏感信息没处理，合规审计直接亮红灯。今天咱们就把这两块掰开揉碎讲清楚。

1. 核心字段——缺一个都不行

我习惯把关键字段分成两类：定位字段（告诉我谁、什么时间、在哪儿干了什么）和 上下文字段（告诉我干的结果、关联了什么）。下面这张表是通用方案，你们可以根据业务场景增删：

字段	说明	示例值	为什么必须要有
时间戳	事件发生的精确时间，含时区	2025-04-10T14:32:17.123+08:00	定位问题时间窗口、做时序分析
来源	模块/服务/设备标识	order-service / 192.168.1.1	快速定位故障源
事件ID	全局唯一的事件标识	txn-7a9e3f2c-b1d4	串联分布式调用链
用户标识	用户ID或脱敏后的用户名	user_10086	审计谁在执行操作
IP地址	客户端或服务端IP	10.0.0.2 或 192.168.0.0/16	安全溯源、地域分析
操作类型	动作名称	CREATE_ORDER / LOGIN	聚合统计、异常检测
结果状态	成功/失败/超时等	SUCCESS / ERROR_401	监控报警、SLA计算
请求ID	当前请求的跟踪号	rq-20250410-001	关联上下游日志

表格里这些字段，缺一个我都觉得别扭。尤其是事件ID和请求ID——没有它们，你根本连不起来一次完整的请求。我以前排查过一个线上故障，就是因为某条日志没带traceId，硬是人工翻了半小时才拼出完整链路。后来我强制所有入口服务在Nginx层就注入traceId，这才解决了。

2. 时间戳——讲究可不少

时间戳最容易被忽略的细节：精度和时区。我个人习惯用毫秒级UTC时间，格式固定为 ISO 8601（比如 2025-04-10T14:32:17.123Z）。为什么不用本地时间？你想想看，分布式系统里不同机器时区可能不一样，保存本地时间等于给自己挖坑。

示例（JSON日志格式）：

{
  "timestamp": "2025-04-10T14:32:17.123+08:00",
  "timezone": "Asia/Shanghai",
  "event_id": "txn-7a9e3f2c-b1d4",
  "user": "user_10086",
  "source": "order-service",
  "ip": "10.0.0.2",
  "action": "CREATE_ORDER",
  "status": "SUCCESS"
}

3. 事件ID——让日志“说话”的关键

事件ID必须全局唯一，方便跨服务、跨线程追踪。我推荐用 UUID 或 Snowflake ID。Snowflake 的好处是带时间信息和机器ID，排错时可以一眼看出生成时间。

底层实现注意两点：

• ID 生成器要线程安全，避免并发重复；
• 长度控制在 36 字符以内（UUID 默认就是 36 字符），太长影响存储和查询。

对了，事件ID一定要出现在日志的每一行里。我曾经在一个微服务项目里发现某些日志忘了传事件ID，结果告警触发后根本没法定位到具体请求，气得我写了个切面强制注入。

4. 用户和IP——身份加位置，但别裸奔

用户标识和IP是审计溯源的核心，但也是最容易泄露隐私的地方。我建议：

• 用户ID：存储脱敏后的值，比如只保留后四位：***0086。如果做数据分析，用哈希值代替原文。
• IP地址：对最终用户IP做截断或哈希，比如 192.168.1.x 或 sha256(client_ip)。内部网络IP可以全量保留，但生产环境对外IP不能明文存。

5. 如何避免敏感信息泄露——这才是最有价值的部分

说白了，敏感信息泄露这个坑，我踩过不止一次。现在总结了一套 “三不”原则：不该记录的坚决不记录，必须记录的坚决脱敏，脱敏后的日志坚决不上报外网。

哪些字段不能出现在日志里？

• 密码、密码摘要、明文密钥
• 身份证号、护照号、银行卡号（哪怕部分掩码也不建议日志里保留）
• 完整的手机号、家庭地址、生物特征（如指纹、人脸特征向量）
• 认证 、session 、OAuth 授权码
• 数据库连接字符串（含用户名密码部分）

下面是一个脱敏工具函数的伪代码示例：

// Java 示例：脱敏工具
public class LogSanitizer {
    public static String maskSensitive(String raw) {
        if (raw == null) return "null";
        // 手机号：保留前3后4，中间用***代替
        if (raw.matches("1[3-9]\\d{9}")) {
            return raw.replaceAll("(\\d{3})\\d{4}(\\d{4})", "$1****$2");
        }
        // 身份证号：只留前4后4
        if (raw.matches("\\d{18}") || raw.matches("\\d{17}X")) {
            return raw.replaceAll("(\\d{4})\\d{10}(\\d{4})", "$1**********$2");
        }
        // 银行卡号：留前4后4
        if (raw.matches("\\d{16,19}")) {
            return raw.replaceAll("(\\d{4})\\d{8,11}(\\d{4})", "$1********$2");
        }
        return raw; // 非敏感类型原样返回
    }
}

这个函数是我们内部一直在用的。注意：脱敏逻辑要放在 日志采集层，不要放在业务代码里——否则每个工程师都可能忘写。我当时的做法是在 logback 或 log4j2 的 Layout 里统一加一层过滤器，对所有输出内容做正则匹配替换。效果很好，但要注意性能，毕竟正则对高并发场景有一定损耗。

6. 知识图谱：日志字段与安全过滤逻辑

下面这张图概括了从原始业务数据到合规日志的完整流程。你可以把它当作日志内容设计的“施工图”：

从图里你能看到，原始数据经过统一脱敏过滤器后才变成合规日志。这个过滤器我建议放在日志框架的 Appender 层，或者用 Logstash / Fluentd 的 filter 插件实现。千万别让业务开发自己决定脱不脱敏——那样大概率会漏。

7. 实战避坑——我踩过的三个坑

好了，理论讲完了，我分享几个真实教训：

• 坑一：事件ID缺少导致无法关联——有一次线上应用OOM，我们看了所有日志都找不到异常点，后来发现是某个中间件没传请求ID。从那以后我强制所有RPC框架自动注入traceId。
• 坑二：脱敏过滤在业务代码里写——业务工程师A写了一个脱敏工具，但忘了在失败分支里调用；工程师B直接打印 request body 到错误日志，结果用户手机号明文暴露了两个月。现在我的团队统一在日志框架层做脱敏，业务代码只打印业务含义。
• 坑三：时间戳用了本地时间——服务器跨时区部署，结果排查问题时时间对不上。后来我把所有日志时间统一为UTC，并在字段里加了一个 timezone 标识。这个问题现在基本绝迹了。