如何配置 access_log 的 if 参数实现有选择性的抽样请求记录-Nginx-PHP中文网

Nginx可通过access_log的if参数实现条件日志记录，常用map配合$request_id或$msec哈希实现抽样，支持按状态码、请求头、变量等定向过滤，需避免昂贵变量和语法错误。

如何配置 access_log 的 if 参数实现有选择性的抽样请求记录

Nginx 的 access_log 指令支持 if 参数，可用于条件化地记录请求——不是“全记”或“不记”，而是按指定条件（如状态码、请求头、变量值等）决定是否写入日志。抽样记录本质上就是一种概率性或规则性的条件过滤，关键在于构造一个可复用、低开销、符合抽样意图的判断条件。

最常用的是基于 $request_id 或 $msec 做哈希取模，实现近似均匀抽样。Nginx 本身不提供随机函数，但时间戳或唯一 ID 的低位变化足够随机：

1% 抽样（约）：log_format sample '...'; access_log /var/log/nginx/sample.log sample if=$sample_flag;，再在 http 或 server 块中定义：
map $msec $sample_flag { ~^(\d+\.\d{3})(\d)$ "$2"; default ""; } # 取毫秒小数点后第 3 位数字（0–9），再用 map 映射为 1 或空
更稳妥的做法是：
map $request_id $sample_flag { ~^[0-9a-f]{2} $request_id; default ""; } # 利用 request_id 前两位十六进制字符，约 1/256 概率命中
注意：map 中不能直接写 if ($arg_debug = "1") 这类语法，必须用正则或精确匹配；且 if 参数只接受变量名（非表达式），所以所有逻辑需提前在 map 中完成。

适合调试特定接口、用户或异常场景，例如只记录带调试头、特定 UID 或错误响应的请求：

将 WCAG 2 AA 无障碍标准应用于设计系统、UI 组件和网页——通过可运行的验证器进行对比度计算，采用设计 token 模式使颜色天生可访问，设定排版和焦点状态规则，并提供语义检查清单。适用于构建或审查 UI。

下载

记录含 X-Debug: true 的请求：
map $http_x_debug $log_if_debug { "true" 1; default 0; }
access_log /var/log/nginx/debug.log main if=$log_if_debug;
只记录 5xx 响应：
map $status $log_if_error { ~^5 1; default 0; }
记录某类用户（如 UID 在 header 中）：
map $http_x_uid $log_if_target_user { ~^100[0-9]{3}$ 1; default 0; }（匹配 UID 100000–100999）

多个条件需合并到单个 map 变量中，不能链式使用多个 if=；同时注意性能和语义边界：

AND 条件示例（debug 头 + 非健康检查路径）：
map $http_x_debug $tmp_debug { "true" 1; default 0; }
map $request_uri $tmp_health { ~^/healthz 1; default 0; }
map "$tmp_debug:$tmp_health" $log_if_combined { "1:0" 1; default 0; }
避免在 map 中使用昂贵操作：如 $args 或 $request_body（后者需开启 lua 或 perl 模块，且影响性能）；优先用 $http_*、$arg_*、$status 等轻量变量。
抽样不等于丢弃日志：未匹配 if 的请求完全不写入该 access_log 行，但其他日志（如 error_log）或全局 access_log 仍可能记录——确保你禁用了默认日志或明确分离了输出目标。

配置生效前务必测试变量值和匹配逻辑，防止误判导致“全不记”或“全记”：

临时加一条 log_format debug '$remote_addr - $request_id $http_x_debug $status $msec'; access_log /tmp/debug.log debug if=$log_if_debug;，用 curl -H "X-Debug:true" ... 触发并检查输出。
用 nginx -t 校验语法；用 nginx -T 输出完整展开配置，确认 map 和 access_log if= 关联正确。
抽样率不精确时，改用 $connection_requests（连接内请求数）或 $pid + $connection 组合哈希，提升分布均匀性。