直接用 log_format + map 就能替代大部分“自定义模块”需求，因其无需编译依赖、不降吞吐，即可实现状态码分类打标与聚合；真正需模块开发的仅两类：读取 upstream 原始响应头或实时共享内存毫秒计数，而90%属过度设计。
为什么直接用 log_format + map 就能替代大部分“自定义模块”需求
绝大多数所谓“高性能状态码监控”场景，根本不需要写 C 模块。Nginx 原生的 log_format 和 map 指令组合，就能在不引入额外编译依赖、不降低请求吞吐的前提下，把 $status 分类打标、按需聚合。真正需要模块开发的，只有两类：一是要读取 upstream 的原始响应头（比如 X-Backend-Status），二是要实时写入共享内存做毫秒级计数——而这两种情况，90% 都是过度设计。
实操建议：
- 用
map把$status映射为业务语义标签，例如：map $status $status_type { ~^[23] success; ~^4[0-9]{2} client_error; ~^5[0-9]{2} server_error; default unknown; } - 在
log_format中直接引用$status_type，后续用 Filebeat + Loki 或 Fluentd + Prometheus pushgateway 做下游解析和告警 - 避免在
map中使用正则捕获组（如$1），会触发 PCRE JIT 回退，实测 QPS 下降 12%～18%
ngx_http_upstream_module 的 upstream_status 变量才是真实异常源头
只看 $status 会漏掉大量上游异常：超时、连接拒绝、502/503 来自 proxy_pass 而非后端应用本身。Nginx 提供了 $upstream_status，它是一个空格分隔的字符串，记录每次 upstream 尝试的真实状态码（如 "502 504"）。
实操建议：
- 必须配合
proxy_next_upstream_tries和proxy_next_upstream_timeout使用，否则$upstream_status可能只含一个值 - 用
split_clients或 Lua 的string.gmatch解析该字段成本高，推荐用log_format直接输出原始字符串，交由日志系统做 pattern match - 注意：当启用
proxy_cache且命中时，$upstream_status为空字符串——这是正常行为，不是 bug
真要写模块？绕开 ngx_http_log_handler_pt，改用 ngx_http_top_body_filter
很多教程教你在 log_handler 阶段统计，但这个阶段无法获取响应体长度（$body_bytes_sent 是最终值，但此时连接可能已关闭），也无法判断是否被 gzip 过滤器修改过内容。更稳的钩子是 body_filter，它在响应流经所有 filter 后、写入 socket 前触发。
实操建议：
- 在
body_filter中通过r->headers_out.status获取最终状态码，比log_handler更可靠 - 用
ngx_shmtx_lock+ngx_slab_alloc操作共享内存时，务必检查返回值是否为NULL，OOM 时 Nginx 不会 crash，但计数会静默丢失 - 不要在 filter 中调用
ngx_http_send_special(r, NGX_HTTP_LAST)，这会破坏 pipeline，导致 keepalive 失效
用 stub_status 搭配 nginx-module-vts 快速验证指标有效性
自己写的模块或日志方案有没有漏统计？最简单的验证方式，是对比 stub_status 的 Active connections / Reading/Writing/Waiting 和你采集的请求数、错误数是否数量级一致。如果偏差超过 5%，说明要么丢了 early close 请求，要么没覆盖所有 server block。
实操建议：
-
nginx-module-vts的/status/format/json接口比原生stub_status多出 per-location 状态码分布，适合快速定位是某个 path 引发 499 还是全局问题 - 开启
server_tokens off后，vts的upstream.response.time字段仍可读，但upstream.response.version会变成空——这不是数据丢失，是 Nginx 主动隐藏 - 别用
curl -I频繁轮询/status，它会创建新连接，干扰Waiting计数；改用netstat -ant | grep :80 | wc -l辅助观察
真正难的不是怎么统计，而是定义清楚“异常”的边界：是只要 $status >= 400 就告警，还是只关注 upstream_status 里出现两次以上的 504？后者需要解析空格分隔字符串并做频次判断，前者一行 map 就搞定。多数团队卡在这一步，而不是技术实现上。
