Nginx 日志与排障——access/error、变量与调试日志开销

Nginx 系列 · 第 11/12 篇
上一篇：《访问控制与限流》 · 下一篇：《性能与生产清单》
参考：Configuring Logging、A debugging log、ngx_http_log_module

---

开头：502 时先看哪？

反代链路一长，问题可能在证书、location、上游超时、限流或磁盘满。运维默认顺序：error.log → access 状态码与 upstream 字段 → nginx -t / 进程 → 系统 ss/df。

---

一、默认日志位置（Ubuntu）

文件	用途
/var/log/nginx/access.log	每请求一行（可关可拆）
/var/log/nginx/error.log	启动、配置、上游失败等

sudo tail -f /var/log/nginx/error.log
sudo tail -f /var/log/nginx/access.log

日志切割后让 Nginx 重新打开文件：

sudo nginx -s reopen
# 或 systemctl kill -s USR1 nginx

---

二、自定义 access 格式（含上游）

# http 块
log_format main_ext '$remote_addr - $remote_user [$time_local] '
                    '"$request" $status $body_bytes_sent '
                    '"$http_referer" "$http_user_agent" '
                    'rt=$request_time '
                    'urt=$upstream_response_time '
                    'ucs=$upstream_cache_status '
                    'ups=$upstream_status '
                    'upa=$upstream_addr';

access_log /var/log/nginx/access.log main_ext;

变量	用途
$request_time	请求总耗时（秒）
$upstream_response_time	上游响应耗时
$upstream_status	上游 HTTP 状态
$upstream_addr	实际打到的上游
$upstream_cache_status	缓存命中情况

静态资源可 access_log off; 降磁盘 IO。

---

三、按状态码快速归类

状态	常见原因
400/404/405	客户端或 location/try_files
413	client_max_body_size
421/495/496	证书/SNI 相关（视场景）
429/503	限流或主动拒绝
502	上游不可连、协议错、过早关闭
504	proxy_read_timeout 等超时
500	少见来自 Nginx 自身；更多看上游

# 粗看状态分布（示例）
sudo awk '{print $9}' /var/log/nginx/access.log | sort | uniq -c | sort -rn | head

---

四、error 日志级别

error_log /var/log/nginx/error.log warn;  # 生产常用 warn/error

级别从低到高大致：debug < info < notice < warn < error < crit ...

临时排查某连接可用 debug_connection（需 debug 版二进制 或带 --with-debug 编译的包）：

error_log /var/log/nginx/error.log debug;
events {
    debug_connection 192.168.1.100;
}

官方：A debugging log。

---

五、原理/性能：日志不是免费的

做法	影响
全站详细 access	磁盘 IO、journaling；高峰可能拖延迟
debug 全局	日志量爆炸，严重拖慢，仅短时、限定 IP
同步写满盘	服务异常；监控 df -h /var
缓冲/条件日志	降压；注意排障时信息是否够

建议：生产默认 warn；access 用结构化字段但避免超长 $request_body；压测环境可关 access 对比基线。

---

六、排障清单（可收藏）

sudo nginx -t
sudo systemctl status nginx --no-pager
ps -ef | grep [n]ginx
sudo ss -tlnp | grep nginx
sudo tail -n 100 /var/log/nginx/error.log
curl -vH 'Host: your.site' http://127.0.0.1/path
df -h /var/cache/nginx /var/log

---

七、本篇小结

• error 看失败原因，access 看状态与耗时/上游。
• 自定义 log_format 加上 $upstream_* / $request_time。
• debug 仅限临时+定 IP；日志 IO 本身影响性能。

下一篇收官：事件模型、worker 调参与生产检查清单。