4、关键字段定义：时间戳、客户端IP、请求方法、状态码、耗时、链路ID的规范
各位做接口日志的同学心里都清楚——日志字段如果不规范，SIEM 根本没法用。我见过太多团队，日志是写了，但时间戳格式五花八门，客户端 IP 抓不到真实来源，链路 ID 说断就断。最后审计排障的时候，全靠人工对着时间轴手工对……那叫一个痛苦。
这一节，我就把六个最关键的字段拎出来，一个一个说清楚规范。你想想看，SIEM 联动审计本质上就是靠这些字段做关联和回溯，字段规范了，后面所有事都顺了。
4.1 时间戳：统一宇宙时间，别管本地
时间戳是所有日志的第一道门槛。SIEM 要跨系统关联，时间不一致，什么都对不上。我个人的铁律是：全部用 UTC 时间，精确到毫秒，格式固定为 ISO 8601。
推荐格式：2025-07-15T14:23:45.678Z
必须带毫秒（三位小数），必须带结尾的 Z 表示 UTC。不要用 ±08:00 这种偏移，SIEM 解析起来多一道弯。
记得我刚接手一个日志平台时，发现时间戳有的用时间戳整数（秒），有的用 yyyy-MM-dd HH:mm:ss，还有的用 MM/dd/yyyy HH:mm:ss.SSS。结果 SIEM 解析出十几条时间线，告警聚合全乱了。后来我统一了格式，规则命中率直接翻倍。
| 维度 | 推荐规范 | 踩坑案例 |
|---|---|---|
| 时区 | 强制 UTC | 用了本地时间，日志从不同机房汇聚后时间线错乱 |
| 精度 | 毫秒（3位小数） | 只用秒精度，高并发下两条日志时间戳一样，无法排序 |
| 格式 | ISO 8601（Z结尾） | 用了空格、中划线、斜杠混合解析器报错 |
建议在应用层直接输出 UTC 毫秒时间戳，不要交给日志采集器去转换。我曾经见过采集器时区配置错了，所有时间都偏移了8小时，排查了整整两天。
4.2 客户端 IP：拿真实的，别拿代理的
接口日志里最容易被埋坑的就是 IP。你看到的可能是反向代理的 IP，不是用户的真实 IP。SIEM 做地域分析、威胁情报匹配时，不真实的 IP 等于废数据。
我的做法：日志字段里保留两个 IP——client_ip（真实客户端）、proxy_ip（代理 IP 列表）。从 X-Forwarded-For 头提取最左侧第一个非私有IP。如果只有一层 Nginx，remote_addr 就是代理 IP。你永远不要相信只有一个字段就够了。
注意：如果 X-Forwarded-For 是用户可控的，必须做合法性校验。我见过攻击者伪造 X-Forwarded-For: 127.0.0.1 骗过 SIEM 的白名单检测。
提取 IP 后，必须检验 IPv4 还是 IPv6，统一格式化成标准字符串。IPv6 建议用压缩格式（例如 ::1 表示本机），SIEM 查询时能直接用索引。
4.3 请求方法：全部大写，别搞花活
请求方法看起来简单，但有的框架输出 GET，有的输出 get，还有的带了下划线。SIEM 做分组聚合时，大小写不一致会导致统计偏少。我要求所有接口日志里的 method 字段强制大写：GET、POST、PUT、DELETE、PATCH、HEAD、OPTIONS。自定义方法（例如 REPORT）也保持大写。
日志示例：method: "POST" 不要写成 method: "post" 或 method: "POST /api/v1/xxx"（那是URI，别混）。
4.4 状态码：保留原始，补充业务码
HTTP 状态码是必须的，但光靠它不够。比如接口返回 200，但业务逻辑失败，SIEM 统计的“成功请求”其实是假的。我习惯把状态码拆成两层：
http_status：HTTP 协议状态码，整数（200、404、500等）biz_code：业务状态码，字符串（如SUCCESS、AUTH_FAILED、BIZ_1002）
SIEM 做告警时，用 biz_code 更精准。比如 http_status=200 但 biz_code=ERROR 的日志，应该标记为异常。
| 场景 | http_status | biz_code | SIEM 应该 |
|---|---|---|---|
| 正常请求成功 | 200 | SUCCESS | 忽略或正常计数 |
| 业务校验失败 | 200 | PARAM_INVALID | 告警或关注 |
| 用户未登录 | 401 | UNAUTHORIZED | 告警（如果是敏感接口） |
注意：业务状态码的命名要有统一前缀，不要一会儿 OK，一会儿 success，一会儿 0。我建议使用大写字母+下划线，例如 SUCCESS、DB_ERROR。
4.5 耗时：统一单位，精确到毫秒
接口耗时（duration）是排查性能瓶颈的关键。很多系统输出秒、微秒甚至纳秒，SIEM 做聚合运算时同一字段单位不一致，算均值就错了。我的建议：统一用毫秒，浮点类型，保留整数或一位小数。例如 103 毫秒，2450.5 毫秒。
为什么不用秒？因为很多接口耗时在几十到几百毫秒，用秒全是小数，SIEM 存储和查询性能都不好。微秒又太细，对普通接口意义不大。毫秒是折中点。
另外，耗时里要不要包含网络延迟？我倾向于只记录应用层处理时间，即从进入 Controller 到返回 Response 的时间。网络传输时间由其他层的日志去管。
我曾经遇到一个团队把耗时记录成 0.123s 的字符串格式，SIEM 无法直接做数值计算。后来我改成 123（毫秒整数），计算性能提升了一大截。
4.6 链路 ID：把调用链穿起来
链路 ID（trace_id）是现代分布式系统审计的命根子。没有它，一个请求经过网关、多个微服务、数据库，你根本连不起来。我强烈要求每个接口日志必须携带 trace_id，且跨服务透传。
生成规则：统一用 UUID v4 格式，32 位十六进制 + 4 个短横线，例如 550e8400-e29b-41d4-a716-446655440000。为什么不用整数自增？因为多个服务不可能共享一个序列生成器。UUID v4 足够随机，碰撞概率极低。
透传方式：通过 HTTP Header（如 X-Trace-Id）在调用链传递。如果没有传入，每个服务可以各自生成，但那样链路就断了。我建议在网关层统一生成，下游服务直接复用，不要重复生成。
日志示例：trace_id: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
有一个容易忽略的点：链路 ID 应该出现在每一个微服务的请求日志和响应日志里。我曾经排查过一个慢请求，A 服务有 trace_id，B 服务没打印，结果费了半天劲才发现是 B 服务数据库查询慢了 3 秒。
4.7 规范落地：一个字段都不能少
好了，六个字段的标准讲完了。但光有标准没用，必须让全团队统一执行。我建议把这套规范写进 API 的日志切面（AOP）里，自动填充。比如用 Logback 的 MDC 或者 Go 的中间件，让每个接口请求自动带上这些字段，不靠人工拼。
又一次血的教训：我曾经在一个项目中允许不同模块各自实现日志字段，结果 SIEM 索引爆炸，每天几十个字段名变体，查询效率极低。最后我强制只允许一个统一的日志切面输出，字段名、类型、格式全部锁死。
另外，这六个字段之间的逻辑关系也很重要。下面我用一张图把规范的关键流程串起来，你想看明白就清楚了。
你看，从原始请求开始，经过规范化引擎统一处理，六个字段带着各自的标准值，最终汇聚到 SIEM。任何一个字段的格式跑偏，后面的 SIEM 关联都会出问题。
4.8 整体规范速查表
最后我把这六个字段的规范汇总成一个速查表，你可以直接贴到团队 wiki 里。
| 字段 | 类型 | 格式/规则 | 示例 |
|---|---|---|---|
| 时间戳 | 字符串 | ISO 8601 UTC，毫秒，Z结尾 | 2025-07-15T14:23:45.678Z |
| 客户端IP | 字符串 | 优先从 X-Forwarded-For 提取真实 IP，校验合法性 | 203.0.113.5 或 2001:db8::1 |
| 请求方法 | 字符串（大写） | 标准 HTTP 方法大写 | POST |
| 状态码 | 整数 + 字符串 | http_status 整数，biz_code 大写字符串 | 200 + SUCCESS |
| 耗时 | 浮点数 | 毫秒，保留0~1位小数 | 103 或 2450.5 |
| 链路ID | 字符串 | UUID v4 格式，跨服务透传 | 550e8400-e29b-41d4-a716-446655440000 |
把这六个字段固定下来，你的接口日志质量至少提升一个档次。后面几章我们会聊怎么把这些字段接入 SIEM，以及如何设计告警规则——不过那是后话了。先把基础打牢，日志规范就是地基，地基不稳，上层建筑再花哨也没用。