Nginx可通过access_log的if参数实现条件日志记录，常用map配合$request_id或$msec哈希实现抽样，支持按状态码、请求头、变量等定向过滤，需避免昂贵变量和语法错误。
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 或错误响应的请求：
Web Accessibility (WCAG 2 AA))
下载
将 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组合哈希，提升分布均匀性。
