Zabbix监控Nginx实战：7.0与agent2新配置方法解析

先说明一点用 zabbix 监控 nginx真正靠的不是 zabbix 自己去分析 nginx 日志而是先让 nginx 暴露一个 /nginx_status 页面再由 zabbix agent 定时抓取这个页面上的连接数、请求数、读写状态等指标最后汇总到 zabbix server 做绘图和告警。链路本身不复杂但如果你用的是 zabbix 7.0 或者已经切换到 agent2会发现配置方式和很多老教程不一样了这就是标题里说“和过去有一点不同”的来源。这篇文章按我最近一次实测的顺序来写先配 nginx status 页面再处理 agent 采集然后导入模板、关联主机、验证数据最后把最容易出现的无数据和 key 报错问题一起梳理清楚。打算用 zabbix 监控 nginx 的人可以直接照着走一遍。1. 先看 nginx status 页面到底能暴露哪些指标再决定监控方案1.1 一个 status 页面能看到什么nginx 的 stub_status 模块启用后访问指定 URL 会返回几行纯文本内容大致长这样Active connections: 1 server accepts handled requests 5 5 5 Reading: 0 Writing: 1 Waiting: 0第一次看到这几行数据的人经常不知道应该重点盯哪几个数。实际上 zabbix 监控 nginx主要靠的就是这几个Active connections当前活动连接数。accepts从启动到现在累计接受的连接总数。handled累计处理的连接总数。requests累计请求总数。Reading正在读取请求头的连接数。Writing正在写响应数据的连接数。Waiting处于空闲等待状态的连接数。注意一下accepts、handled、requests 这三个数字是 nginx 启动后的累计值会一直往上增长。zabbix 自带模板里通常不会直接拿这个数字去画线而是会做差值或变化率得到每秒新增请求数、每秒新增连接数这类更直观的指标。1.2 这些指标分别适合用来发现什么问题如果只是把页面里的数字取出来却不清楚业务含义后面配置告警阈值时会很被动。Active connections 适合观察“当前压力”。这个数字突然涨到很高说明请求正在堆积或者有大量长连接没有释放。但要注意长连接应用里这个值天然会比短连接高不能拿一套阈值套所有业务。accepts 和 handled 的差值可以判断 nginx 是否出现了连接处理失败。正常情况下 accepts 和 handled 应该大致相等。如果 handled 明显小于 accepts说明有连接在建立阶段被中断或资源不足这种情况通常伴随系统文件描述符耗尽。requests 适合计算请求速率。连续取两次 requests相减再除以时间间隔就能得到每秒请求数。这个值对接口服务、静态资源站点都有参考意义。Reading、Writing、Waiting 三个值更像“当前状态”。Writing 长期居高不下可能说明后端响应慢大量响应堆积在 nginx 上等待发送。Waiting 高则通常代表 Keep-Alive 连接多不一定是坏事。1.3 为什么不能只盯着连接数很多老教程喜欢让人只看 Active connections因为配置简单。但实际上只有把“连接数、请求速率、读写状态”组合起来看才能判断故障阶段。比如 Active connections 很高但同时 Writing 也很高问题大概率出在后端响应慢。如果 Active connections 很高但 requests 速率没有明显变化更像是连接被占住不释放会有大部分连接卡在 Waiting。所以我的建议是第一次做监控时别急着只做一两个指标直接把 agent2 模板或手动采集的常用 key 全部接上先跑几天拿基线再去决定哪些指标需要告警。2. 环境准备zabbix 版本、agent 类型、nginx 模块三件事先对齐2.1 zabbix 7.0 带来的一个明显变化你打开 zabbix 前端在“数据采集 - 模板”里搜 nginx会看到模板名称和老版本不一样。6.x 时代常见的模板名是 Template App Nginx而新版本里通常是 Nginx by Zabbix agent 2 或 Nginx by Zabbix agent。如果你是用 zabbix 7.0 部署可能还会注意到默认 agent 变成了 agent2不再建议安装老的 zabbix-agent。这个变化带来的影响很直接老教程里让你手写 UserParameter、再从模板页面填一堆自定义 key 的方法很多在 agent2 环境里已经不需要了。agent2 自带了 nginx 插件只要在 agent2 配置里把 status 页面地址填好前端模板就能自动拉取数据。如果你还在用 zabbix 5.x、6.x也没关系。老 agent 加 UserParameter 的方式完全能跑只是配置链路长一点。后面会单独说两者的差别。2.2 先确认 nginx 是否带 stub_status 模块在 nginx 所在机器上执行nginx -V 21 | grep stub_status如果命令行有输出说明当前 nginx 已经编译了 stub_status 模块。没有输出则表示未编译该模块后面的 status 页面配置会直接失败。处理方式有三种如果你的 nginx 是用发行版自带安装包装的比如 apt 或 yum 安装大概率已经带了 stub_status 模块。可以先用 nginx -V 确认。如果是自己编译安装并且当时没有加 --with-http_stub_status_module就需要重新编译一次或者在编译参数里补上这个模块。实在不想折腾编译可以考虑直接用反向代理方式让另一台保留模块的 nginx 转发请求但会增加不必要的复杂度不建议为监控专门引入一层代理。这里提醒一点重新编译 nginx 不仅耗时而且容易在动态加载模块或平滑升级时出问题。最好在最初安装 nginx 阶段就确认模块是否齐全省得以后补。2.3 系统、权限和 curl 依赖zabbix agent 抓取 nginx status 页面时最常见的工具是 curl。所以 nginx 所在机器上要能正常执行 curl并且 curl 能访问到本机的 /nginx_status 路径。如果 agent 不在 nginx 本机而是在另一台机器上就需要保证 agent 所在主机到 nginx 所在主机的网络是通的同时在 nginx 的 allow 配置里放行 agent 所在主机的 IP。还有一个容易被忽略的点zabbix agent 的配置目录通常只有 root 或者 zabbix 用户有读取权限。如果你手动创建自定义配置文件要注意目录权限是否正确否则 agent 启动时会跳过某些配置文件表现出来就是部分 key 没有任何数据。3. nginx 侧配置status 页面到底怎么开才安全3.1 推荐的最小配置编辑 nginx 配置文件在 server 块内加入一个 locationlocation /nginx_status { stub_status; allow 127.0.0.1; allow 192.168.1.0/24; deny all; }这里有几个细节值得展开说。location 后面的等号表示精确匹配。这样做是为了避免其他 location 规则把 /nginx_status 拦截掉。如果你不写等号某些带正则的 server 配置可能会把请求匹配到别的路径上结果永远是 404 或跳转。stub_status; 就是开启状态页面的指令。nginx 1.8 之后这个模块一直保留写法没有变化。allow 和 deny 必须写。很多人测试时为了方便直接把 allow 注释掉改成全网可访问结果把 nginx 运行状态暴露到了公网。这属于信息泄漏尤其是 status 页面可以看到连接数、请求数长期暴露容易被外部扫描到并利用。稳妥的做法是只放行 zabbix agent 所在主机的内网 IP。如果 agent 就在本机写 127.0.0.1 就够了。3.2 检查配置并 reload修改完配置后先执行nginx -t看到 syntax is ok 和 test is successful 后再 reloadnginx -s reload使用 reload 而不是 restart原因很简单reload 是平滑重载不会中断现有连接很适合生产环境。restart 会短暂断开服务哪怕只有几百毫秒高峰期也可能产生报错。如果你的 nginx 是通过 systemd 启动的也可以使用systemctl reload nginx效果类似。3.3 用 curl 验证 status 页面在 zabbix agent 所在机器上执行curl http://127.0.0.1/nginx_status如果能返回类似Active connections: 1 server accepts handled requests 5 5 5 Reading: 0 Writing: 1 Waiting: 0就说明页面已经正常返回。如果返回 403先检查 allow 和 deny 的 IP 是否覆盖了请求来源。如果返回 404先确认 location 是否精确匹配以及是否有其他 server 块干扰。如果页面一直转圈或超时可能是防火墙拦截了端口或者 nginx 没有监听该端口。我实测时遇到过一种奇怪情况nginx 本机 curl 返回正常但 zabbix server 上用 zabbix_get 测不到数据。后来发现是 agent 装在了容器里容器内访问 127.0.0.1 和宿主机不是同一个网络栈最后改成 agent 配置里写宿主机内网 IP 才解决。如果你也用容器部署 agent这一点要特别留意。4. zabbix agent 配置老方法与 agent2 新方法的取舍4.1 传统 UserParameter 写法如果你还在用老版本 zabbix agent并且前端模板也是 Template App Nginx那通常需要自己在 agent 配置目录下写 UserParameter。比如在 /etc/zabbix/zabbix_agentd.conf.d/ 下新建一个 nginx.confUserParameternginx.status[*],/usr/bin/curl -s http://127.0.0.1/nginx_status | awk $1Active:{print $NF}这条自定义 key 的意思是通过 agent 执行 curl 抓取 status 页面再用 awk 提取 Active 这一行的最后一个字段也就是当前活动连接数。如果要多取几个指标可以继续追加UserParameternginx.requests[*],/usr/bin/curl -s http://127.0.0.1/nginx_status | awk NR3{print $3} UserParameternginx.reading[*],/usr/bin/curl -s http://127.0.0.1/nginx_status | awk NR4{print $2} UserParameternginx.writing[*],/usr/bin/curl -s http://127.0.0.1/nginx_status | awk NR4{print $4} UserParameternginx.waiting[*],/usr/bin/curl -s http://127.0.0.1/nginx_status | awk NR4{print $6}这里的 NR 行号是基于前面 curl 返回的多行文本。不同发行版、不同 nginx 版本的 status 页面格式基本一致但为了稳妥建议先手动 curl 一次数清楚字段位置再写 awk 表达式。写完配置后需要重启 agentsystemctl restart zabbix-agent这种方式的优点是兼容性好老环境基本都能跑缺点是每加一个指标就要写一行文本解析逻辑而且如果 status 页面字段顺序有变化awk 按位置取字段很容易错位。4.2 agent2 的 nginx 插件方式如果你用的是 zabbix agent2流程会简单不少。agent2 自带 nginx 插件只需要在插件配置里指定 status 页面地址。在 /etc/zabbix/zabbix_agent2.d/ 下创建 nginx.conf内容参考如下Plugins.Nginx.Status.Host127.0.0.1 Plugins.Nginx.Status.Port80 Plugins.Nginx.Status.Path/nginx_status这里的含义是agent2 会去访问 http://127.0.0.1:80/nginx_status并解析页面里的指标。配置完成后重启 agent2systemctl restart zabbix-agent2此时 agent2 内部会注册一批以 nginx 开头的 key比如 nginx.connections.active、nginx.requests、nginx.reading、nginx.writing 等。前端模板里的监控项可以直接用这些 key 获取数据不需要再单独定义。有一点需要说明不同 zabbix 小版本里 agent2 插件的配置参数名可能略有差异。建议落地时先查看当前环境下的插件配置示例或者先看模板里的宏名称再对应修改。不要直接照搬网上的配置。4.3 用 zabbix_get 先做一次链路验证无论你选了哪种方式在进入 zabbix 前端配置之前都建议先在 zabbix server 上执行一次远程采集测试。老 agent 测试zabbix_get -s 192.168.1.10 -k nginx.status[active]agent2 测试zabbix_get -s 192.168.1.10 -k nginx.connections.active如果返回一个数字说明 agent 能成功采集到数据。如果返回空、报错或者显示 Not supported就不要急着去前端里关联模板先回去检查 agent 配置和 nginx status 页面。这一步相当于把链路拆成了两段先在 agent 侧确认 status 页面正常、key 正确再到 zabbix 前端确认模板和宏配置。拆开排查会快很多。5. 导入模板与关联主机新版模板宏和旧文档对不上时怎么办5.1 找到正确模板在 zabbix 前端左侧找到“数据采集 - 模板”搜索 nginx一般会出现多个结果。比较常见的是Nginx by Zabbix agent 2Nginx by Zabbix agent选哪一个取决于你的 agent 类型。如果主机用的是老 zabbix agent模板要选 agent 版本如果主机用的是 agent2就选 agent2 版本。选错的话前端会一直显示不支持或无数据。有些环境里还会看到 Template DB MySQL、Template App Nginx 这类老模板如果搜索出来的名字不太一样优先看模板描述里是否提到 agent2。以你实际环境中的模板列表为准。5.2 关联主机并修改宏找到模板后进入“主机 - 模板”把对应模板链接到目标主机上。接着要检查模板自带的宏。在 agent2 模板里通常会有一个类似 {$NGINX.STUB_STATUS.URL} 的宏默认值可能是 http://127.0.0.1/nginx_status。如果你的 nginx 不在 agent 本机或者监听了非 80 端口就需要修改这个宏。宏的修改位置在“主机 - 宏”里把默认的 URL 改成 agent2 实际能访问到的地址。比如http://192.168.1.10:8080/nginx_status这里要特别提醒宏里写的地址是 zabbix agent 或 agent2 所在机器能访问的地址不是 zabbix server 能访问的地址。如果两者不是同一台机器要按 agent 所在机器的网络视角来写。5.3 没有合适模板时的后备方案如果你所在环境比较老找不到 agent2 模板或者模板里很多监控项和你的 nginx 版本不对应可以手动创建监控项。手动创建时item 类型选择“Zabbix agent”key 写成nginx.status[active]或者写成 agent2 支持的原生 keynginx.connections.active这种方式适合少数几台机器或者只是为了临时验证。缺点很明显模板里的图形、触发器都要自己创建批量维护的成本很高。如果是几十台 nginx 的场景还是尽量把官方模板导入进来更省事。6. 验证数据、配置告警和排查链路6.1 怎么确认数据已经进 zabbix完成模板关联后进入“监测 - 最新数据”在主机筛选框里选择目标主机再看是否有 nginx 相关监控项在持续产生数据。正常情况是等待一个采集周期后就能看到连接数、请求数等指标的值。zabbix 前端的数据刷新有延迟不要刚关联完模板就去刷新页面等一两分钟再检查。如果看到了数字说明链路已经通。接着可以把几个关键指标加到“监测 - 图形”里看一下曲线是否平滑。6.2 配置连接数和请求速率的触发器数据稳定之后再做告警。我个人建议从下面几个方向开始不要一开始就设大量阈值。第一活动连接数异常突增。你可以通过模板自带触发器或者手动创建一个触发器表达式检测 nginx 活动连接数在短时间内快速上升。阈值怎么定要结合业务先跑一段时间看基线不能拍脑袋写一个“超过 100 就告警”。第二Writing 持续偏高。如果 Writing 长时间大于某个值说明响应数据堆积后端可能已经不健康了。这种问题靠连接数告警不一定能发现需要单独监控 Writing 状态。第三请求速率异常下降。请求数突然掉到接近 0有可能是 nginx 宕机也可能是入口流量异常。如果你有其他监控系统可以交叉验证比如看网卡流量是否同时下降。触发器表达式里可以先用模板自带的变量比如 {$NGINX.DROP_RATE.MAX.WARN} 这类。如果模板没有对应变量就需要手动定义一个宏再在表达式里引用。注意告警阈值不要照着网上抄不同业务的请求量、连接数完全不在一个量级。先跑数据再定阈值比一开始就精确设置更靠谱。6.3 无数据的排查顺序无数据是所有 nginx 监控配置里最高频的问题。遇到的时候按下面的顺序排查效率最高。第一步在 agent 所在机器上手动执行 curl确认 nginx status 页面能正常返回。curl http://127.0.0.1/nginx_status如果不能返回说明问题在 nginx 配置先回到第 3 章去看 status 页面是否正确开启。第二步在 zabbix server 上执行 zabbix_get确认 agent 能拿到对应 key。zabbix_get -s 192.168.1.10 -k nginx.connections.active如果返回 No such key说明 agent 侧没有启用对应 key检查 UserParameter 或 agent2 插件配置。第三步查看 agent 日志。老 agent 日志通常在 /var/log/zabbix/zabbix_agentd.logagent2 的日志通常是 /var/log/zabbix/zabbix_agent2.log。tail -f /var/log/zabbix/zabbix_agent2.log日志里会明确提示某一个 key 无法执行或者插件初始化失败。第四步检查前端模板关联和宏配置。模板有没有关联到正确主机URL 宏是否指向了 agent 可访问的地址宏里有没有写错端口或路径。第五步如果所有监控项都没有数据而且 zabbix_get 在 server 本机执行正常前端却看不到数据重点检查主机是否被停用、主机接口端口是否正确、IP 地址是否填写正确。大部分无数据问题最后都会回到三个点status 页面能否访问、agent 是否启用了对应 key、前端宏配置是否正确。不要一上来就怀疑模板导入坏了。6.4 数据有了但数值不对有时候数据能采到但数值明显不对比如连接数一直显示 0或者 requests 和实际请求量差距很大。先看解析逻辑是否正确。如果是自己写的 UserParameterawk 按字段位置取数可以和前端数据对比确认取的是不是目标字段。如果是 agent2 插件可以手动执行插件相关的 key返回值和 curl 页面里的原始数字进行对比。再看监控项的采集类型。zabbix 模板里有些监控项是被依赖的不是直接采集而是从某一个主监控项里二次计算出来的。如果你只配置了其中一个 item可能导致依赖它的数据展示为空。最后检查时间周期。模板里不同 item 的更新间隔不一样有的可能是 1 分钟有的可能是 5 分钟。刚关联模板的前几分钟部分 item 还没有数据是正常的。7. 几个容易忽略的细节直接影响最终效果7.1 nginx 是编译安装还是包安装用包安装的 nginx一般已经带有 stub_status 模块配置起来非常省事。编译安装的 nginx模块情况完全取决于编译参数所以在生产环境建议先确认。如果编译时没有加这个模块后来又想加常见做法是重新编译但要注意保留原有功能之前编译时用了哪些模块和参数最好先用 nginx -V 记录下来再补上新增模块避免模块丢失。7.2 docker 部署场景下的网络差异如果你是通过 docker 方式部署 zabbix agent或者是把 nginx 跑在容器里网络命名空间和宿主机不同。agent 容器里的 127.0.0.1 并不是宿主机的 127.0.0.1所以配置 status 页面地址时要写容器的网关 IP或者直接用宿主机 IP 做端口映射。如果 nginx 在容器里agent 在宿主机上通常需要把 nginx 容器的 80 端口映射到宿主机再让 agent 访问宿主机的映射端口。如果只配置了容器内部端口agent 从宿主机访问不到直接无数据。7.3 不要把 status 页面开放到公网这一点在配置里专门写了 allow 和 deny但还是要单独强调。status 页面会暴露 nginx 的请求数、连接数、读写状态虽然不算敏感业务数据但长期暴露会给外部扫描提供信息也增加了被尝试探测的风险。正确做法是只放行监控所需的主机。如果你的 zabbix server 和 agent 都通过内网通信那就在 allow 里写内网网段。如果有跳板机或者专线再把对应网段加进去。7.4 老 agent 的 UserParameter 容易踩权限坑在很多系统上zabbix agent 会以 zabbix 用户运行。如果你的自定义配置文件放在 /etc/zabbix/zabbix_agentd.conf.d/ 目录下需要确认 agent 用户能读取这个目录下的文件。文件权限不对时agent 启动不会报错只会忽略该文件导致 key 一直显示 not supported。遇到这种情况可以把文件权限改成 644目录权限改成 755再重启 agent。8. 最后留几个值得长期关注的方向单机 nginx 监控跑通之后如果后续规模变大我建议往这几个方向扩展。第一把 nginx 监控和业务告警分开。zabbix 负责采集和阈值告警但真正判断“服务是否可用”还要看接口探测结果。这两者可以配合不能互相替代。第二关注 agent2 插件的版本兼容。zabbix 官方模板更新比较频繁升级 zabbix 版本时模板里的 item 和 key 可能发生变化。升级前先在测试环境导入新模板对比一下旧模板的数据项再决定是否覆盖生产模板。第三多台 nginx 场景下不要每台机器都手动配一遍。可以用模板宏继承、主机组批量关联的方式把公共配置收敛到模板层。第四如果后面要接入 prometheus、夜莺、grafana 这类系统可以先把 zabbix 里已经采集到的指标通过 API 导出或者考虑直接单独部署采集器避免监控体系互相打架。回到最初的问题zabbix 监控 nginx 并不复杂关键在于把 nginx status 页面、agent 类型、模板版本这三者对齐。现在再回看这套流程真正值得留意的改动是 agent2 模板把很多手工 key 收进了插件里配置方式从“自己编 UserParameter”变成了“填插件参数”。这种变化对新手反而更友好但前提是你在导入模板之前先确认 agent 类型、插件是否启用、status 路径能不能被 curl 到。我实际踩过最多次的坑都不是监控项本身而是路径差了一个斜杠或者 allow 列表漏写了 zabbix agent 所在主机的 IP。建议第一次做的时候不管用老 agent 还是 agent2都先在 /nginx_status 上用 curl 跑通再用 zabbix_get 拿到数字最后才去前端折腾数据展示。链路通了后面加告警、加图形都是顺手的事。