Nginx 日志模块源码与开发实战指南

typedef struct ngx_log_s   ngx_log_t;
struct ngx_log_s {
    ngx_uint_t           log_level;        // 当前日志级别
    ngx_open_file_t     *file;             // 日志文件描述符信息
    ngx_atomic_uint_t    connection;       // 连接数，用于限制日志输出频率
    time_t               disk_full_time;   // 磁盘写满时间戳
    ngx_log_handler_pt   handler;          // 自定义日志处理函数
    void                *data;             // handler 的上下文
    ngx_log_writer_pt    writer;           // 写入函数指针（默认 ngx_log_write）
    void                *wdata;            // writer 的上下文
    char                *action;           // 当前动作描述，如 "request line"
    ngx_log_t           *next;             // 下一个日志对象（链表）
};

typedef struct {
    ngx_fd_t              fd;
    ngx_str_t             name;
    u_char               *buffer;         // 日志写入缓冲区
    u_char               *pos;
    u_char               *last;
    // … 其他 flags 等
} ngx_open_file_t;

#define ngx_log_error(level, log, ...)    \
    if ((log)->log_level >= level)        \
        ngx_log_error_core(level, log, __VA_ARGS__)
void ngx_log_error_core(ngx_uint_t level, ngx_log_t *log, ...);

static ngx_int_t
ngx_http_example_handler(ngx_http_request_t *r)
{
    ngx_log_t  *log;
    log = r->connection->log;
    ngx_log_error(NGX_LOG_INFO, log, 0,
                  "example module: request to \"%V\" started", &r->uri);
    // 业务逻辑 …
    ngx_log_error(NGX_LOG_ERR, log, 0,
                  "example module: something went wrong, status=%d",
                  r->headers_out.status);
    return NGX_OK;
}

2024/08/20 09:52:03 [error] 2345#0: *1024 connect() failed (111: Connection refused) while connecting to upstream, client: 192.168.1.1, server: localhost, request: "GET / HTTP/1.1", upstream: "http://127.0.0.1:8080/", host: "localhost"

typedef struct {
    ngx_array_t           *logs;           // ngx_http_log_t 数组（支持多个日志文件）
    ngx_open_file_cache_t *open_file_cache;
    ngx_uint_t             off;            // 是否关闭 access_log
} ngx_http_log_loc_conf_t;

typedef struct {
    ngx_open_file_t       *file;           // 打开的日志文件
    ngx_http_log_script_t *script;         // 日志格式编译后的脚本
    time_t                 disk_full_time;
    time_t                 error_log_time;
    ngx_http_log_fmt_t    *format;         // 日志格式定义（if= 条件等）
    ngx_log_t             *log;            // 指向 error log（用于日志输出错误）
    unsigned               error:1;
    unsigned               filter:1;       // 是否启用过滤
} ngx_http_log_t;

typedef struct {
    ngx_chain_t          *op;              // 编译后的操作链
    ngx_array_t           ops;             // 原始操作数组
    ngx_array_t           args;            // 参数（变量名等）
    // ...
} ngx_http_log_fmt_t;

typedef struct {
    ngx_http_log_op_t          *op;        // 当前操作
    ngx_str_t                  *name;      // 变量名称
    ngx_http_variable_value_t  *value;     // 运行时变量值
    uintptr_t                   text;      // 常量字符串指针
    size_t                      len;
} ngx_http_log_script_t;
typedef enum {
    ngx_http_log_op_text = 0,      // 固定文本
    ngx_http_log_op_var,           // 变量
    ngx_http_log_op_filter         // 过滤条件
} ngx_http_log_op_t;

log_format combined '$remote_addr - $remote_user [$time_local] '
                    '"$request" $status $body_bytes_sent '
                    '"$http_referer" "$http_user_agent"';

127.0.0.1 - frank [20/Aug/2024:09:52:03 +0800] "GET /api HTTP/1.1" 200 2326 "https://example.com" "Mozilla/5.0 ..."

worker_processes  1;
error_log  logs/error.log  warn;   # 全局仅输出警告及以上
events {
    worker_connections  1024;
}
http {
    log_format timing '$remote_addr - $remote_user [$time_local] '
                      '"$request" $status $body_bytes_sent '
                      '"$http_referer" "$http_user_agent" '
                      'rt=$request_time uct="$upstream_addr"';
    access_log  logs/access.log  timing;
    server {
        listen       80;
        server_name  example.com;
        # 为当前虚拟主机打开 info 级别错误日志
        error_log  logs/example_error.log  info;
        location / {
            root   html;
            index  index.html;
        }
        location /api {
            proxy_pass  http://backend;
            # 仅记录状态码 >= 400 的请求到独立文件
            access_log  logs/api_error.log  timing  if=$status >= 400;
        }
    }
}

http {
    log_format vhost '$host $remote_addr - $remote_user [$time_local] '
                     '"$request" $status $body_bytes_sent';
    server {
        listen       80;
        server_name  example.com www.example.com;
        # 利用 $host 变量自动分离日志文件
        access_log  logs/access_$host.log  vhost;
        error_log   logs/error_$host.log   warn;
    }
    server {
        listen       80;
        server_name  api.example.com;
        access_log  logs/access_api.log  vhost;
        error_log   logs/error_api.log   info;
    }
}