Nginx 工程实践 -- 11. 日志与可观测性
日志回答"发生了什么",指标回答"现在怎么样"。前者是排障的线索,后者是发现问题的眼睛。Nginx 提供了 access_log(谁请求了什么、结果如何)、error_log(哪里出错了)和 stub_status(实时连接/请求计数)三层观测能力,再多接一个 exporter 就能接入 Prometheus 生态。
flowchart LR
subgraph Nginx
A["access_log
访问日志"] --> B["缓冲 / 压缩"]
C["error_log
错误日志"]
end
B --> D["采集器
Filebeat / Promtail"]
C --> D
D --> E[("Loki / Elasticsearch")]
E --> F["Grafana / Kibana"]
一、两类日志与记录时机
| 日志 | 内容 | 默认级别 |
|---|---|---|
access_log | 每个请求一行:来源、方法、URI、状态码、字节数、耗时等 | — |
error_log | 运行错误与告警:配置错误、upstream 故障、权限问题等 | error |
access_log 在 location 处理结束时记录;如果中途发生内部重定向,最终记在重定向后的 location 上(见第 14 篇)。
二、log_format:定义自己的字段
内置 combined 格式是常见基线,但生产上通常需要补上耗时、上游、转发信息:
1 | |
escape=json:变量按 JSON 规则转义("、\、控制字符),比default的\xXX更适合直接喂给日志系统;log_format只能放在http块;- 一行太长会影响可读性,按采集端要求取舍。
三、常用变量速查
| 变量 | 含义 |
|---|---|
$remote_addr / $remote_user | 客户端地址 / 认证用户 |
$time_local / $time_iso8601 | 本地时间(CLF / ISO 8601) |
$msec | 带毫秒的秒级时间戳 |
$request / $request_method / $request_uri | 完整请求行 / 方法 / URI(含参数) |
$status | 响应状态码 |
$body_bytes_sent / $bytes_sent | 响应体字节 / 总发送字节(含头) |
$request_time | 请求总耗时(从读第一个字节到发完最后一个字节) |
$upstream_addr / $upstream_status | 上游地址 / 上游状态码 |
$upstream_connect_time / $upstream_header_time / $upstream_response_time | 与上游建连 / 收到响应头 / 收到响应 的耗时 |
$upstream_cache_status | 缓存状态(MISS/HIT/STALE 等) |
$http_referer / $http_user_agent | Referer / UA |
$host / $server_name / $scheme / $server_port | 主机 / 匹配的 server_name / 协议 / 端口 |
$connection / $connection_requests | 连接序号 / 该连接上的请求数 |
$request_id | 请求唯一 ID,用于全链路串联 |
$http2 / $http3 | 协商到的协议(h2 / h3) |
$gzip_ratio | 压缩比 |
$arg_xxx / $cookie_xxx | 查询参数 / Cookie |
$sent_http_xxx | 发给客户端的响应头 |
四、access_log 进阶
1 | |
要点:
buffer/gzip会缓冲写入,降低 IO 次数,但故障时可能丢最后几条(flush控制);- 路径含变量时不支持缓冲,且每次写都要打开文件,用
open_log_file_cache缓解; if=的条件为0或空时不记录,可用来做"采样/只记异常"。
五、error_log 级别
1 | |
级别从低到高:debug → info → notice → warn → error → crit → alert → emerg。生产常用 warn 或 error;排查时临时开到 info/debug,用完记得调回(debug 量极大)。
六、请求耗时分解
$request_time 是黑盒总时长,拆开看才有定位价值:
sequenceDiagram
participant C as 客户端
participant N as Nginx
participant U as 上游
C->>N: 请求
Note over N,U: $upstream_connect_time
N->>U: 建立连接
Note over N,U: $upstream_header_time
U-->>N: 响应头
Note over N,U: $upstream_response_time
U-->>N: 响应体
N-->>C: 响应
Note over N: $request_time
$upstream_response_time大、$upstream_connect_time小 → 后端处理慢;$upstream_connect_time大 → 建连慢(网络/上游 accept 队列);$request_time远大于上游时间 → Nginx 到客户端之间慢(带宽、客户端、响应体大)。
七、实时指标:stub_status 与 exporter
1 | |
输出(需编译 --with-http_stub_status_module):
1 | |
Active connections:当前活跃连接(含 Waiting);accepts/handled:接受 / 处理完成的连接数,二者差距通常意味着触达了worker_connections限制;requests:总请求数;Reading/Writing/Waiting:读请求头 / 写响应 / 空闲等待。
更完整的指标(连接、请求、SSL 握手、upstream 等)可用社区 nginx-prometheus-exporter 采集 stub_status / Nginx Plus API,交给 Prometheus + Grafana。它只读状态页,不侵入配置。
八、日志轮转与留存
日志文件改名后,Nginx 仍持有旧句柄,需要发 USR1 重开:
1 | |
配合 logrotate 时,把 postrotate 写成 nginx -s reopen;留存策略(天数/大小/压缩)交给 logrotate 或采集端。
九、排错
| 现象 | 原因 / 处理 |
|---|---|
| 日志文件里没有新记录 | 未 nginx -s reopen;或 access_log off 覆盖了上级 |
日志里全是 \xXX | 用了 default 转义;需要 JSON 就改 escape=json |
| 日志量爆炸 | 静态资源未关日志;加 access_log off 或 if= 条件 |
上游字段是 - | 请求没走代理(命中静态/缓存);属正常 |
| 时间对不上 | 时区配置不一致;用 $time_iso8601 统一 |
| stub_status 404 | 模块未编译;allow/deny 拦了来源 IP |
参考链接
- Nginx 官方文档:ngx_http_log_module ——
log_format/access_log/open_log_file_cache; - Nginx 官方文档:ngx_http_stub_status_module —— 状态字段含义与
$connections_*变量; - Nginx 官方文档:ngx_http_core_module($request_id) —— 请求唯一 ID;
- Nginx 官方文档:ngx_http_upstream_module($upstream_*) —— 上游相关变量;
- Nginx 官方文档:Controlling nginx(USR1 重开日志);
- nginx-prometheus-exporter —— 指标接入 Prometheus;
- RFC 8259:JSON 字符串转义。
小结
access_log记结果、error_log记错误、stub_status记实时状态,三者互补;- 用
log_format+escape=json定义可采集的结构化字段,把$request_id带上做全链路; $request_time要拆成 connect/header/response 三段看,才能分清是后端慢还是链路慢;buffer/flush/if=用来控量,open_log_file_cache解决变量路径日志;- 日志轮转后
nginx -s reopen;指标用 stub_status + exporter 接入监控。
系列导航
Nginx 工程实践 -- 11. 日志与可观测性
https://bubao.github.io/posts/b1c2d3e4.html
