三步搭好 Apollo 配置监控与告警体系

【免费下载链接】apolloApollo is a reliable configuration management system suitable for microservice configuration management scenarios.项目地址: https://gitcode.com/gh_mirrors/apoll/apollo

凌晨十一点，值班群消息："Apollo 里的 timeout 改了，客户端怎么还是旧值？"你翻日志，发现既说不清推送发没发出去，也说不清客户端还在不在拉取。这就是缺了 Apollo 监控的后果。Apollo 是分布式配置管理系统，推送链路是"发布 → 发布消息 → 长轮询通知 → 客户端取新配置"，任何一环卡住都没有数据可依。本文分三步搭起一套能直接上手的 Apollo 监控与告警体系。

先睹成品：面板长什么样

先看目标效果。搭好后，你可以在 Prometheus 里直接查到任意客户端实例的指标，服务端的缓存、接口 QPS、JVM 指标也落在同一处。

建成后的价值就两句话：客户端说"配置没生效"时，你第一件事是看服务端推没推、客户端状态如何，而不是靠日志猜；大促前发布，扫一眼面板就能判断推送量和失败率是否仍在正常范围。

效果摆在这，落地则按下面三步走。

第1步：把关键指标暴露出来

先想清楚采什么。不必全量，三组就够：

• 服务端接口：/notifications/v2（长轮询通知入口）与/configs的 QPS 和响应时间
• 缓存：ConfigService 三个 Guava 缓存的命中率与驱逐数
• 推送结果：长轮询通知链路的成功/失败计数，也就是配置推送成功率指标的基础

再加在哪？先开通端点。仓库公共配置 application.yaml 已默认把 info、health、metrics、prometheus 四个 Actuator 端点（Spring 内置的"体检接口"）暴露出来，且 base-path 是/，直接访问http://IP:port/prometheus即可拿到指标。

关键在服务端缓存的两个开关，定义于 BizConfig：

# 开启后 ConfigService 的缓存才会构建，GuavaCacheMetrics 自动注册命中率等指标 config-service.cache.enabled=true config-service.cache.stats.enabled=true # 长轮询推送的批大小，是评估推送压力的固定参照 apollo.release-message.notification.batch=500

推送成功/失败计数补一个小切面即可。Micrometer 的 MeterRegistry 已被注入 ConfigService（见 ConfigServiceAutoConfiguration 源码），拿来就用，织入长轮询入口 NotificationControllerV2：

@Aspect @Component public class PushMetricsAspect { private final MeterRegistry registry; @Around("execution(* com.ctrip.framework.apollo.configservice.controller.NotificationControllerV2.pollNotification(..))") public Object around(ProceedingJoinPoint pjp) throws Throwable { try { Object r = pjp.proceed(); registry.counter("apollo.notification.poll", "result", "ok").increment(); return r; } catch (Throwable e) { registry.counter("apollo.notification.poll", "result", "fail").increment(); throw e; } } }

注册生效后，Prometheus 里能看到apollo_notification_poll_total{result="ok|fail"}，按 result 标签一除就是失败率。计数器名可按团队命名规范调整。

数据暴露完了，下一个问题是：怎么把它变成值班时顺手就能看的画面。

第2步：让数据看得见

面板分四块，每块只打一个点，建议用表格形式管理"块 → 看什么 → 对应指标"的关系：

第一版别贪多，一块 2~3 张图即可。客户端那块的前提是 SDK 开了监控开关：apollo.client.monitor.enabled=true，再用apollo.client.monitor.external.type=prometheus对外导出，完整配置见 Java SDK 用户指南 的"启用客户端监控"一节。

看得见了，还得有人盯着——这就是给指标设红线的事。

第3步：给指标设上红线

Apollo 告警配置的核心是分级：告警响了，值班的人要立刻知道按哪套流程处理。阈值建议分两档：

• P1（立即响应，15 分钟内）：配置推送失败率 >1% 且持续 5 分钟；客户端长轮询连接数 10 分钟内骤降 50% 以上——这两个都是链路断裂的信号
• P2（工作日内响应）：/configs的 p95 耗时 >500ms；cache.hit.rate<80%；数据库连接池使用率 >80%

规则写在 Prometheus 的 rules 文件里，P1 的推送失败率规则示例：

- alert: ApolloPushFailureRate # 失败率 >1% 持续 5 分钟触发，避免单次抖动误报 expr: sum(rate(apollo_notification_poll_total{result="fail"}[5m])) / sum(rate(apollo_notification_poll_total[5m])) > 0.01 for: 5m labels: { severity: "P1" }

通知渠道走 Alertmanager 转发到值班群 webhook。配完务必用一条"必定触发"的临时规则实测送达，否则真出事时渠道本身才是第一个故障点。

📌 红线只是兜底。日常排障靠的是会读数字，下面挑三个最常用的。

数据怎么读：三个必会指标

1. /notifications/v2请求速率断崖下跌：说明一批客户端停止长轮询了，通常是网络或 meta 地址配错。下一步查：先按 dataCenter/集群标签看是不是单点分布，再核对这些客户端的apollo.meta是否指到了正确的 ConfigService。
2. cache.hit.rate从 0.99 掉到 0.8 以下：说明缓存在被高频失效，多数情况是有人在频繁发布，把缓存反复 invalidate。下一步查：到 Portal 的发布历史里锁定频繁发布的 namespace；若是合理的批量变更（如大促压测），属正常，临时调宽该窗口告警即可。
3. 客户端侧apollo_client_namespace_timeout从 0 开始增长：说明有客户端拉配置超时。下一步查：对比该实例的首次加载耗时和服务端/configs的 p95——两边同时涨是服务端问题，只有客户端涨查它自己的网络与 DNS。

读会了数据，还有两个真实环境里最容易踩的坑要提前避开。

两个容易踩的坑

⚠️ 坑一和坑二，都按"现象 → 根因 → 处理"拆开讲。

推送延迟先查谁

现象：Portal 显示已发布，客户端两分钟还没拿到新值。

根因：Apollo 的推送是"写 ReleaseMessage 记录 → ReleaseMessageScanner 批量扫描 → 唤醒对应客户端的长轮询"。最常见的断点是客户端 meta 地址与发布环境不匹配——它的长轮询挂在另一台服务上，通知根本送不到。

处理：先查服务端/notifications/v2的访问日志，确认该客户端有没有在长轮询；没有就查客户端 meta；有则核对 ReleaseMessage 记录是否生成，再不行看 scanner 日志。顺序别反，否则会浪费时间怀疑代码。

缓存命中率掉了，别急着重启

现象：config_cache 的命中率突然从 0.99 掉到 0.5。

根因：每条发布消息到达时，ConfigServiceWithCache 都会对对应 key 做 invalidate 并重新预热。发布频繁 → 失效频繁 → 命中率低。此时重启服务只会清空全部缓存、制造冷启动，雪上加霜。

处理：先查发布历史，找出高频发布的 namespace 推动合并发布；确认是合理的批量窗口，就把 P2 阈值在该时段临时放宽，而不是动服务。

坑讲完了。在把这套 Apollo 监控体系切到生产之前，用下面这份清单过一遍。

上线前核对清单

✅ 逐项勾选，全部通过再撤掉临时观察规则：

• 每个组件curl http://IP:port/prometheus返回 200，且能看到缓存与接口指标
• config-service.cache.enabled、config-service.cache.stats.enabled已开启，cache.hit.rate有值
• 客户端apollo.client.monitor.enabled=true且external.type=prometheus，apollo_client_*指标可见
• P1/P2 规则就位，均设置了for时长（P1 建议不低于 5 分钟）
• Alertmanager 到值班群的 webhook 已用临时规则实测送达
• 记录了基线：正常时长轮询 QPS、缓存命中率、/configsp95，供异常时对比
• 面板四块齐全，每块都有数据在走

一句话收束：Apollo 监控的价值不在指标多少，而在出问题时手里有数可读——先暴露，再看见，最后设红线。

• Java SDK 用户指南（客户端监控一节）
• 分布式部署指南
• Apollo 设计文档

【免费下载链接】apolloApollo is a reliable configuration management system suitable for microservice configuration management scenarios.项目地址: https://gitcode.com/gh_mirrors/apoll/apollo