消息系统上线只是开始，跑得好不好需要指标说话。多数团队的监控只盯"接口报没报错"，等发现问题时，故障往往已经发生几小时。这篇给一份消息链路的完整指标清单：四个层位、每个层位的核心指标和告警阈值的设计思路。

背景痛点

"客户说收不到消息了"是最贵的告警来源——因为它是客户替你做的监控。消息系统的问题大多不表现为"崩了"，而表现为"慢了、少了、堵了"，这类退化只有自己的指标能第一时间看见。

原理

所谓链路监控指标，是指对消息收发全链路分位观测的量化体系。链路分四个层位，各盯各的异常：

层位	观测对象	关键指标
发送层	调用发送接口	成功率、错误码分布、耗时 P95
接收层	Webhook 推送	到达量、验签失败数、处理延迟
队列层	待处理消息	积压深度、消费速率、重试占比
账号层	账号在线状态	在线账号数、掉线频次、顶号次数

四个层位的组合能定位绝大多数故障：发送成功率降加错误码集中某个码，是接口或账号问题；接收到达量掉零，是回调链路断了；队列积压上涨而消费速率平稳，是上游流量异常。

核心实现

发送层指标埋点（示例代码，需按官方文档校验）：

def send_and_observe(appid, payload):
    # 示例代码，需按官方文档校验
    start = time.monotonic()
    try:
        resp = api("/wx-api/api/message/sendText", {"appid": appid, **payload})
        metrics.incr(f"send.ok,{tags(appid)}")
        return resp
    except BizError as e:
        metrics.incr(f"send.biz_err,code={e.code},{tags(appid)}")  # 按错误码分布
        raise
    finally:
        metrics.timing("send.latency", time.monotonic() - start)

错误码分布是发送层最有诊断价值的指标：某个错误码占比突增，直接指向对应故障类型。账号层指标依赖掉线事件与探测结果，处置逻辑见错误码相关文档，掉线告警的架构见Webhook 文档。

踩坑

一、告警阈值用"同比自身"不用"绝对值"：消息量随业务波动，固定阈值要么天天误报要么形同虚设，环比昨天同时段的偏离度更可靠。

二、P95 而不是平均值：平均耗时被海量正常请求稀释，故障时的慢请求只有分位数能照出来。

三、掉线告警要设静默窗口：网络抖动导致的短暂掉线自动重连即恢复，每掉一次告警一次，值班同事一周后就学会忽略这个告警——告警被忽略等于没有告警。

四、指标要有 appid 维度：多账号系统里"整体成功率 99%"可能藏着"某账号持续失败"，聚合维度太粗是最常见的监控失明。

总结

监控体系的建设顺序：先账号层（在线是地基）、再接收层（回调断了什么都没了）、然后发送与队列。指标清单建完，"客户说收不到消息"这类最贵的告警来源就能基本消失。这篇基于Eyun 平台的企微接口整理，错误码语义与事件推送以官方文档为准，告警阈值上线后按实际误报率迭代两轮才算可用。