推荐使用带escape=json的JSON格式模板，确保字段完整、语义清晰且兼容采集工具；其次可选竖线分隔的增强文本格式以兼顾可读性与grok解析；并按需扩展后端标识、API分类、认证状态等业务字段。
在构建 Nginx 日志集中收集系统（如对接 ELK、Loki、Graylog 或 Splunk）时，日志格式模板是关键一环。它直接影响后续的解析准确性、字段提取效率和查询体验。一个设计良好的 log_format 应满足：结构化（推荐 JSON）、字段完整、语义清晰、兼容采集工具解析规则。
标准 JSON 格式模板（推荐）
使用 log_format 配合 escape=json 生成合法 JSON 行，便于 Filebeat、Fluentd、Prometheus Pushgateway 等直接解析：
log_format json_combined escape=json '{'
'"time_local":"$time_local",'
'"remote_addr":"$remote_addr",'
'"remote_user":"$remote_user",'
'"request":"$request",'
'"status":$status,'
'"body_bytes_sent":$body_bytes_sent,'
'"http_referer":"$http_referer",'
'"http_user_agent":"$http_user_agent",'
'"http_x_forwarded_for":"$http_x_forwarded_for",'
'"request_time":$request_time,'
'"upstream_response_time":"$upstream_response_time",'
'"upstream_addr":"$upstream_addr",'
'"host":"$host",'
'"server_name":"$server_name",'
'"scheme":"$scheme",'
'"request_id":"$request_id"'
'}';
说明：
-
所有字符串字段加双引号，数字字段不加引号（如
$status、$body_bytes_sent），确保 JSON 合法性； -
$request_id需配合map模块或第三方模块（如ngx_http_request_id_module）生成，用于全链路追踪； -
$upstream_response_time和$upstream_addr在反向代理场景下非常关键，建议保留； - 若使用 OpenResty，可进一步嵌入 Lua 变量（如用户 ID、服务版本）增强上下文。
兼容传统文本解析的增强型空格分隔模板
当采集端暂不支持 JSON（如旧版 Logstash grok）或需兼顾人工可读性时，可用带固定分隔符的结构化文本格式：
log_format enhanced '$time_iso8601|$remote_addr|$remote_user|$request|$status|$body_bytes_sent|'
'$http_referer|$http_user_agent|$http_x_forwarded_for|'
'$request_time|$upstream_response_time|$upstream_addr|$host|$scheme|$request_id';
说明：
- 用竖线
|分隔字段，避免 URL 中空格、引号干扰； -
$time_iso8601比$time_local更利于时序对齐与跨时区处理； - 字段顺序保持逻辑连贯（时间→客户端→请求→响应→上游→元数据），方便写 grok pattern；
- 建议在采集配置中统一指定该分隔符，并禁用默认的
combined格式以避免混用。
按业务场景定制的关键扩展字段
为支撑监控告警与排障，可在基础模板中补充以下字段（需提前定义变量）：
-
后端服务标识：
$upstream_http_x_service_name（由上游服务注入）或$proxy_host； -
API 路径分类：用
map提取一级路径，例如map $request_uri $api_group { ~^/v1/users/ user; ~^/v1/orders/ order; default other; }； -
认证状态：结合
$http_authorization或自定义变量（如$auth_status）标记是否鉴权成功； -
灰度标记：从请求头（如
$http_x_release_version）或 cookie 提取发布版本信息。
注意事项与最佳实践
部署前请确认：
- JSON 模板中禁止出现未转义的换行或控制字符（
escape=json可自动处理）； - 高并发场景下，避免在
log_format中调用耗时 Lua 函数（如 DNS 查询、HTTP 请求）； - 敏感字段（如
$args、$http_cookie）默认不应写入日志，确有需要应先脱敏； - 建议为不同 server 块或 location 设置独立 access_log + format，便于按服务切分索引或流；
- 上线新格式前，用
nginx -t校验语法，并抽样验证日志输出是否符合预期结构。
