Nginx日志需从打点逻辑、字段语义、解析友好性、安全合规四维度统一设计，包含12个经千级QPS验证的必备字段，分组覆盖时间节点、客户端来源、请求三要素、状态校验、耗时归因、流量大小、链路透传及业务锚点，并严格规范格式与落地验证。
要让 Nginx 日志真正支撑企业级可观测性，不能只改几个字段，得从打点逻辑、字段语义、解析友好性、安全合规四个维度统一设计。核心是：结构清晰可解析、关键链路不丢失、业务维度可筛选、敏感信息有收敛。
字段组合必须满足可观测性闭环
以下 12 个字段已在千级 QPS 场景验证，按功能分组，缺一不可：
- 时间与节点标识：$time_iso8601（非 $time_local，避免时区混淆）、$hostname（区分具体机器，故障定位必备）
- 客户端真实来源：$remote_addr（防伪造基础 IP）、$http_x_forwarded_for（保留原始链路，但需在采集层清洗截断，防注入）
- 请求三要素拆解：$request_method|$request_uri|$server_protocol（不合并为 $request，避免 URI 中空格或引号破坏结构）
- 状态双校验：$status（Nginx 返回码）、$upstream_status（后端真实返回码，502/504 时快速判断是网关还是服务挂了）
- 耗时三层归因：$request_time（总耗时）、$upstream_response_time（后端响应）、$upstream_connect_time（建连延迟，识别网络抖动）
- 流量与体大小分离：$bytes_sent（含响应头）、$body_bytes_sent（纯 body），对比可发现 gzip 是否生效、响应是否被截断
- 链路透传刚需：$request_id（Nginx 自动生成）、$trace_id、$span_id（若已集成 OpenTelemetry/SkyWalking，必须透传，否则 APM 断链）
- 业务上下文锚点：$http_x_api_version、$http_x_app_id（用于灰度分流、租户隔离、AB 测试快速筛选）
格式定义必须适配下游采集与解析
推荐用 | 分隔，禁用空格和引号包裹，直接兼容 Logstash grok 或 Filebeat dissect：
log_format standard '$time_iso8601|$hostname|$remote_addr|$http_x_forwarded_for|'$request_method|$request_uri|$server_protocol|'$status|$upstream_status|'$request_time|$upstream_response_time|$upstream_connect_time|'$bytes_sent|$body_bytes_sent|'$http_user_agent|$http_referer|'$request_id|$trace_id|$span_id|'$http_x_api_version|$http_x_app_id';
注意：
– 不用双引号包裹字段，避免 JSON 解析时多层转义
– 每行结尾加空格再换行，Nginx 会自动拼接
– 所有变量前必须带 $，拼错会导致 nginx -t 失败
日志输出需分场景、控粒度、防泄露
不同业务线或接口类型应使用不同日志格式，而非全局一套：
- 对外 API 网关：启用 full 格式（含 trace_id、upstream_detail）
- 静态资源服务：精简为 minimal 格式（仅 $time_iso8601|$remote_addr|$uri|$status|$body_bytes_sent）
- 管理后台接口：增加 $remote_user 和 $http_authorization（脱敏后记录，如 Bearer ***abc）
- 所有含敏感参数的 URI（如 ?token=xxx、?id_card=123）必须在 log_format 中用 $uri 替代 $request_uri，并在采集层正则过滤 args
落地前必须完成三项验证
配置不是写完就生效，要闭环验证：
- 语法验证：执行 nginx -t，确认无“invalid number of arguments”或“unknown variable”报错
- 内容验证：curl 一次接口后，tail -n 1 logs/access.log，检查字段数量、分隔符、时间格式是否符合预期
- 解析验证：用 Filebeat 的 dissect 或 Logstash 的 grok 跑一条日志，确认每个字段都能正确提取为独立 key-value
