1. 为什么我们需要自定义日志？

作为长期与Nginx打交道的开发者，你一定经历过这样的场景：半夜被报警电话惊醒，发现线上服务异常。当你火急火燎地打开access.log文件，看到的却是满屏的127.0.0.1 - - [15/Jul/2023:03:45:21 +0800] "GET /api/v1/user HTTP/1.1" 200 612这种"天书"，既没有请求耗时也没有业务标识，排查问题就像在黑暗中摸索。

这正是自定义日志格式的用武之地！通过定制化日志内容，我们可以：

  • 记录API响应时间，快速定位慢请求
  • 添加唯一请求ID，追踪全链路调用
  • 包含业务参数，分析用户行为模式
  • 采集环境变量，排查配置问题

2. OpenResty的日志配置秘籍

（技术栈：OpenResty 1.21.4 + LuaJIT 2.1.0-beta3）

2.1 基础配置三连击

打开你的nginx.conf文件，找到http块，添加以下配置：

http {
    # 定义名为custom_format的日志格式
    log_format custom_format '$time_iso8601|$remote_addr|$request_method|'
                             '$status|$request_time|$http_user_agent|'
                             '$http_x_request_id|$host$request_uri';

    access_log /var/log/nginx/access.log custom_format;
}

这段配置实现了：

  • $time_iso8601：ISO标准时间格式
  • $remote_addr：客户端真实IP
  • $request_method：HTTP请求方法
  • $status：响应状态码
  • $request_time：请求处理时间（秒级精度）
  • $http_user_agent：用户代理信息
  • $http_x_request_id：自定义请求ID头
  • $host$request_uri：完整请求路径

2.2 进阶：Lua加持的魔法日志

想让日志包含业务数据？试试Lua变量注入：

server {
    location /api {
        access_by_lua_block {
            -- 生成唯一请求ID
            ngx.var.request_id = ngx.var.http_x_request_id or 
                                ngx.md5(ngx.now()..ngx.var.remote_addr)
        }

        log_format custom_adv_format '$time_iso8601|$remote_addr|$request_id|'
                                    '$upstream_response_time|$bytes_sent|'
                                    '$request_length|$server_protocol';
    }
}

这个配置的亮点在于：

  • 自动生成请求ID，避免日志关联困难
  • 记录上游服务响应时间
  • 包含请求/响应体积数据
  • 捕获HTTP协议版本

3. 实战中的经典场景

3.1 API性能监控

当我们的RESTful接口出现性能抖动时，通过$request_time和$upstream_response_time的差值，可以快速判断问题出在Nginx层还是上游服务。比如：

2023-07-15T09:23:45+08:00|112.84.25.67|GET|200|0.347|...

这里的0.347秒如果明显高于上游服务耗时，说明可能遇到了Nginx配置问题或服务器资源瓶颈。

3.2 安全审计追踪

通过组合$remote_addr、$http_user_agent和自定义的请求ID，可以完整还原攻击者的行为路径。当发现异常请求时，用请求ID即可追溯所有相关日志。

3.3 灰度发布验证

在AB测试场景下，可以在日志中注入$http_x_api_version之类的自定义头，配合日志分析系统统计不同版本接口的成功率和性能指标。

4. 技术方案的优劣分析

4.1 优势亮点

  • 灵活定制：支持200+内置变量和自定义变量
  • 性能无损：日志格式化在请求处理结束后异步执行
  • 多维度关联：通过请求ID串联Nginx日志与应用日志
  • 无缝集成：兼容ELK、Splunk等主流日志系统

4.2 潜在短板

  • 存储膨胀：详细日志可能使文件体积增长5-10倍
  • 敏感信息泄露：不当记录Cookie、Authorization头会有安全风险
  • 时区问题：默认使用UTC时间，需要显式配置$time_local
  • 精度限制：时间类变量只到毫秒级，不适合纳秒级监控

5. 避坑指南：七个必须知道的注意事项

  1. 变量选择原则：每个字段都应明确用途，避免"以防万一"式记录
  2. 性能红线：单个日志行建议控制在1KB以内
  3. 时间格式：优先使用$time_iso8601保证可读性
  4. 敏感字段：切忌记录$args或$request_body
  5. 缓冲区设置：适当配置buffer=32k flush=5s提升性能
  6. 日志轮转：推荐使用logrotate每日切割
  7. 格式验证：新增日志格式后，务必执行nginx -t测试

6. 最佳实践总结

经过多个项目的实战检验，推荐采用分层日志策略：

# 基础层：精简的运维监控日志
log_format ops_format '$remote_addr - $time_iso8601 "$request" $status';

# 业务层：包含核心业务指标
log_format biz_format '$request_id|$uid|$product_id|$action_type|$http_referer';

# 调试层：全量日志（仅在需要时开启）
log_format debug_format '$remote_addr - $http_cookie [$request_body]';

通过多日志文件+差异化的记录级别，既能满足日常监控需求，又能在排查复杂问题时拥有足够的信息量。记住，好的日志系统不是记录所有，而是聪明地记录必要信息。

7. 写在最后

配置自定义日志就像给你的服务器安装行车记录仪——既要确保关键信息不丢失，又要避免存储无用数据消耗资源。经过本文的讲解，你现在应该能够：

  • 根据业务需求设计合理的日志格式
  • 避免常见的配置陷阱
  • 利用日志分析提升排障效率

不妨打开你的OpenResty配置，从添加第一个自定义字段开始，打造属于你的"日志望远镜"吧！当有一天你通过自制的日志格式快速定位了一个隐蔽的Bug时，一定会感谢今天认真学习的自己。