一、起源:应用层观测的盲区

1.1 只能看到接口慢,无法回答慢在哪一层

主机侧监控回答的是"机器是否正常",接入层与网关回答的是"请求量与错误率的整体水位",两者都不进入进程内部。当问题表现为单个接口变慢时,外部观测能给出的结论通常停留在"某几个接口变慢、影响面约多少",而处置需要的信息在进程内:

外部观测到的现象 外部能给出的结论 需要应用内信息才能回答的问题
接口 P99 上升 哪些接口变慢、整体影响面 耗时在自身计算、锁等待、GC 停顿还是下游调用
错误率上升 失败请求占比 失败集中在哪个异常类型、哪个下游、哪类参数
吞吐下降 QPS 降幅 上游限流、自身拒绝、客户端超时放弃还是容量不足
单实例异常 某一台与其他不一致 该实例的线程池、连接池、GC、依赖连接是否偏离
长尾超时 少量请求超时 超时请求是否集中在特定接口、版本、下游或数据规模

这些问题的共同结构是缺少可下钻的维度。整体平均值只能说明"有事发生",把同一个数值按接口、状态码、下游服务、实例、版本拆分之后,才能看出问题是否集中。埋点的直接目的就是把这些维度预先写进数据,使下钻在故障发生时即可进行,而不必等到事后补代码再发布。

1.2 事后排查与实时告警的差别

两件事对数据的要求不同,容易混为一谈:

维度 事后排查 实时告警
触发方式 人工发起,或由告警引出 由规则周期性求值自动触发
时间尺度 分钟级至小时级,可接受查询耗时 秒级至分钟级,查询必须足够快
依赖数据 日志、追踪、快照、指标均可 以指标为主,需要可计算、可聚合的数值
对埋点的要求 字段完整、能还原现场 数值化、带标签、基数有界、可被表达式引用
失效后果 定位变慢,结论可能不完整 故障静默发生,发现延迟由业务反馈决定

日志很难直接充当告警条件:日志量随请求量线性增长,按文本匹配的判定既昂贵又脆弱,字段一旦改动规则即失效。追踪数据的采集本身就是采样的,不能作为告警的计数来源。因此"能否告警"对埋点提出了外部观测没有的要求——指标必须是可聚合的数值,标签必须可枚举且有界。

这条差别解释了为什么同一份埋点要区分两种用途:为了排查而埋的字段可以很细,为了告警而埋的指标必须克制。混淆两者会得到两种典型结果:字段很全但无法写出稳定的规则,或指标很干净但在定位时缺少上下文。

1.3 埋点缺失与埋点过度的两种失败

失败形态 表现 代价 典型成因
埋点缺失 告警只有"接口慢",定位只能靠复现或猜测 观测窗口被错过,不可复现问题无法复盘 只依赖框架默认埋点,未覆盖业务动作与资源池
埋点过度 指标数量庞大、看板无人看、告警频发 存储与查询成本上升、采集本身带来开销、噪声掩盖真实信号 按需求逐条添加、无退出机制、标签维度随意扩展

两类失败的判定标准是同一个:这条埋点是否指向一个具体问题与一个具体动作。能回答"出现异常时下一步看什么"的埋点在缺失时会造成损失;无法回答这个问题的埋点在存在时会造成成本。埋点缺失通常发生在业务动作、资源池水位、异常分类这些框架默认覆盖不到的角落;埋点过度通常发生在同一问题被多种指标重复表达、或指标被当成日志使用的地方。

一种常见的中间状态是"指标齐全但无法定位":采集了请求量、错误率、延迟分位,却没有按接口、下游、版本拆分,也没有资源池与业务动作的水位,结果是告警能触发但无法收敛到原因。本篇讨论的正是从数据到原因之间的这一层。


二、原理

2.1 三类信号的分工与关联

指标、日志、追踪各自回答不同的问题,不能互相替代:

信号 回答的问题 数据结构 成本特征 优势场景
指标 是否异常、程度如何、影响多少 数值加标签,结构固定 与时间点数量成正比,相对低廉 趋势判断、阈值告警、容量规划
日志 具体发生了什么、输入是什么 文本或结构化字段,结构自由 与事件数量成正比,通常最高 根因定位、事件明细、取证
追踪 请求经过了哪些环节、慢在哪一跳 带父子关系的 Span 树 与采样后的调用量成正比 链路与依赖分析、跨服务耗时拆解

关联字段是三类信号能互相跳转的前提。 没有统一的关联键,三类数据就是三座孤岛:

  1. 追踪标识:日志中必须携带 Trace ID 与 Span ID,才能由一次慢请求的链路定位到该请求在各服务中产生的日志;追踪上下文的传播格式(W3C Trace Context 与 B3)与采样策略见 Spring Cloud 微服务 第 2.7 节。
  2. 样本引用(exemplar):指标不携带请求标识,但可以在直方图桶上附带被观测请求的 Trace ID 样本,使"看到一个高延迟数据点"可以直接跳到"那一次请求的完整链路"。这是从指标到追踪最短的路径。
  3. 公共维度:服务名、实例标识、版本、时间窗是三类数据共有的检索键。它们在三类数据中的取值口径必须一致,否则跨数据源的筛选结果对不上。
  4. 跳转顺序:指标先定"什么时候、哪一类问题",追踪再定"哪个环节",日志最后定"具体原因与输入"。反向跳转只在需要确认某个异常是否影响了整体指标时使用。

日志侧的追踪标识生成、透传与 MDC 接入方式已在 Java 日志与常用类库规范 的链路关联一节给出,本篇不重复日志配置本身,只说明埋点侧需要保证的字段。

2.2 指标体系与命名

2.2.1 四种基本类型

指标按数值语义分为四类,选择依据是"这个量在时间上如何变化"以及"是否需要分布信息":

类型 语义 是否可直接取值 适用 主要陷阱
计数(Counter) 只增不减的累计量 否,需取增量 请求数、错误数、调用次数、拒绝次数 直接看原始值无意义;误用计数器表达可增减的量
瞬时值(Gauge) 某一时刻的瞬时量 是 活跃线程数、队列长度、连接占用、堆使用量 抖动明显,告警必须加持续时间;语义上不可增的池上限不要用瞬时值
分布(Histogram) 由桶计数累积构成的分布 否,需按桶计算 请求耗时、报文大小、批次规模 桶边界设置不当导致分位精度下降;桶数量影响序列数
摘要(Summary) 客户端预先计算的分位值 否 需要精确分位且不跨实例聚合的少量指标 分位值不可跨实例聚合;一经计算无法回溯原始分布

分布与摘要的核心差别在于能否聚合。 摘要在采集端算出分位并上报,跨实例对分位值求平均或求最大值在数学上都不成立;直方图上报的是桶计数,可以在任意维度上先求和再求分位,因此更适合多实例、多服务的场景。以 Prometheus 为存储的体系里,跨实例的分位计算只能由直方图完成。

2.2.2 命名与标签设计

命名规范。指标名是查询与告警中的标识,改动即导致既有查询与看板失效,因此需要在项目内统一:

  1. 结构固定为"域_对象_度量",全部小写,以点或下划线分隔,同一体系内只选一种;
  2. 计数器以 _total 结尾,单位写在名称中并使用基本单位(秒、字节,而不是毫秒、兆字节);
  3. 同名指标在所有模块中语义一致,不使用"某模块的耗时"与"另一模块的耗时"共用一个名字;
  4. 不使用缩写,除非是团队内已有共识且不可歧义的形式;
  5. 框架自动埋点的名称不做重命名,自定义指标不与框架名称冲突,避免语义被覆盖。

标签设计。标签决定了指标能否下钻,同时决定了成本,两者是一组取舍:能下钻的维度越多,时间序列数量越多。

设计要点 说明 反例
取值可枚举且数量有界 取值集合是有限且稳定的,例如接口、状态码、渠道 用户标识、订单号、请求标识
维度承载语义 每个标签回答"按什么视角拆分" 为了调试加入的环境变量散值
避免把标识当标签 无界标识应作为日志字段或追踪属性 完整 URL 路径、SQL 语句、异常消息
标签数量克制 单个指标一般不超过 5 至 6 个标签,且不同时段取值集合稳定 同时按接口、下游、状态码、渠道、版本、区域拆分

判别一条维度能否作为标签的方法是:它的取值集合是否会随业务数据增长而增长。 URL 中的资源 ID、用户标识、商品编码、异常消息文本都属于会增长的一类,放进标签会造成序列数随数据无限膨胀。这类维度只适合出现在日志与追踪中,那里按事件存储,成本与查询方式都不依赖取值集合的大小。

2.2.3 单位与口径一致性

同一现象在不同来源必须有同一口径,否则数据之间无法互相验证:

  1. 耗时口径:服务端处理耗时(从收到请求到响应完成)不含客户端网络时间;客户端调用耗时含连接与网络。两者的差值即网络与排队开销,只有口径明确时这个差值才有意义。
  2. 分母口径:成功率的失败定义(是否包含超时、连接重置、客户端 4xx)与分母范围必须写进定义,改动需记录时间点,否则历史对比失去意义。
  3. 单位与精度:统一使用秒与字节,展示层再换算;避免同一指标在两个模块分别以毫秒与秒上报。
  4. 采样窗口口径:跨实例聚合时分位计算在单一数据源内完成,不对各实例的分位值做平均。

口径不一致的表现是"两个系统对同一件事给出不同数字",排查时会把时间大量消耗在解释差异上。

2.2.4 分位数与平均值的选择

指标 反映的内容 局限 适用
平均值 单位请求的平均耗时 被大量快请求拉低,掩盖长尾 粗略判断整体水位,不作为目标
P50 典型用户的体验 不反映最差情况 交互式服务的常规体验
P95 / P99 较慢用户的体验 对极少量的极端请求不敏感 延迟目标的主要依据
P99.9 与最大值 最差情况 样本少时不稳定 排查长尾与超时原因

平均值与分位数不可互相替代。 一次涉及 1% 请求的严重卡顿可以让 P99 翻倍,而对平均值几乎没有影响。反向地,整体水位缓慢上升会先反映在平均值与 P50 上,P99 可能被少量超时样本的波动掩盖。

两类派生指标各有用途:

  • 分位数适合做趋势与目标,用于观察"用户体验在变化"。
  • **"满足阈值的请求占比"**适合做 SLO 与服务品质计算,直接由直方图桶得到,含义明确且不依赖插值精度。

使用直方图计算分位时,桶边界需要覆盖目标值邻域:目标阈值落在两个桶之间时,分位数由桶边界插值得到,误差会显著放大。设置方式通常是围绕 SLO 阈值定义若干显式桶(例如 100ms、300ms、1s),而不是使用一组均匀的大跨度边界。

2.3 指标分层

指标按观测对象分层,每一层只回答该层能回答的问题。分层的作用是让下钻有固定顺序,避免"用 JVM 指标解释下游超时"这类方向性错误。

层 主要指标 回答的问题 采集来源
主机层 CPU、内存、磁盘空间与 I/O、网络、文件句柄 机器资源是否触顶,是否被限额或节流 主机采集组件,见 linux: 监控与告警
JVM 层 各代容量与使用量、GC 次数与停顿、线程数、类加载数、直接内存 问题是否落在 GC、内存或线程模型上 JVM 内建指标与 GC 日志,见 JVM 内存结构与垃圾回收
应用框架层 HTTP 请求、下游调用、线程池、连接池、缓存 慢在哪个环节、哪个资源池饱和 框架自动埋点与客户端/池组件指标
业务层 业务动作计数与转化、业务异常分类 业务是否真的受影响、影响在哪个环节 业务代码显式埋点

分层后的三条判读纪律:

  1. 先上层后下层。业务层与框架层直接反映用户感知,主机与 JVM 层解释原因。出现业务指标异常时先按框架层拆分,再进入 JVM 与主机层找解释,而不是从 CPU 使用率开始。
  2. 层间不重复表达同一现象。主机层内存使用率与 JVM 层堆使用量是不同的量,两者同时告警时若都指向"内存不足",说明其中一层的阈值设置未针对本层语义。
  3. 跨层需要关联键。三层数据要按实例、服务、时间对齐才能拼接成一条证据链,实例标识的注入方式见 3.1。

2.4 埋点方式

2.4.1 自动埋点与手动埋点

维度 自动埋点 手动埋点
覆盖范围 框架已识别的边界:入站请求、客户端调用、部分池与 GC 业务动作、领域内部状态、框架未覆盖的自定义路径
命名一致性 由框架统一,跨服务口径一致 依赖约定,容易在模块之间出现同义不同名
变更成本 随框架升级变动,需要跟随适配 随代码演进,需要与业务一起维护
主要局限 粒度停留在框架边界,不包含业务语义;对非标准路径可能漏采 覆盖不全、位置随意时形成重复与遗漏

实践中的分工是明确的:框架边界与资源池交给自动埋点,业务语义与领域内部状态交给手动埋点。 在框架已覆盖的位置手工重复埋点,得到的往往是同一现象的两套数字,且两者在异常路径上口径不同。

2.4.2 AOP 或拦截器统一埋点的适用条件

统一埋点把横切关注点(计时、计数、异常分类)从业务代码中提取出来,适用于满足以下条件的位置:

  1. 关注点是横切的:同一段逻辑需要在多个方法或请求上重复执行;
  2. 位置是稳定的:切点对应的类与方法在该层中不会频繁改名,或有测试与评审保证改名时同步更新;
  3. 维度可枚举:从入参或上下文能取出有界的标签取值,而不是把入参整体作为标签;
  4. 异常路径已考虑:埋点必须在异常抛出时同样记录结果标签,否则错误计数恒为零。

不适合使用统一切面的情况:

  • 业务语义指标:下单成功数需要业务规则判定,切面无法在服务边界外得到结果;
  • 需要领域内部数据:埋点落在领域方法内部才能拿到判定依据时,切面只能记录调用发生,不能记录业务结论;
  • 切点范围过宽:以包或注解匹配大范围方法并在每次调用上计时计数,会把开销加到高频内部调用上;
  • 需要精确控制时机的路径:异步提交、重试、批量操作等场景中,一次业务动作对应多次方法调用,切面计数会把调用次数当成业务次数。

使用切面时还需要注意代理方式带来的边界:基于接口的代理与基于子类的代理在自调用、final 方法、静态方法上的行为不同;同类内部方法调用不经过代理,可能造成同一类中部分方法被埋点而另一部分不被埋点。

2.4.3 异步与线程池场景的上下文传递

追踪上下文与日志上下文默认都绑定在当前线程上,进入线程池后不会被继承。这是异步化之后"链路断裂""日志串号""指标归属错误"的共同原因:

场景 上下文丢失的表现 处理方式
自定义线程池 子任务没有 Trace ID,日志无法归入链路 包装线程池或任务提交口,随任务复制上下文
框架异步执行 注解式异步方法与定时任务的执行线程无上下文 在任务入口显式建立上下文,出口清理
组合式异步调用 回调链在公共线程池上执行,上下文与调用方无关 由调用方显式传递,不依赖默认线程池
消息生产与消费 生产与消费两侧的日志分属两条链路 把标识写入消息属性,消费端恢复到上下文

两条约束:

  1. 传递必须成对。线程池中的线程被复用,任务执行完成后上下文若未清理,会残留给下一个任务,造成日志串号与指标归属错误。设置与清理需要在同一处成对出现,且清理放在 finally 中。
  2. 共享线程池需要额外处理。多个业务共用同一个线程池时,任务之间上下文会互相污染;应为需要上下文的执行链路使用独立线程池或包装后的执行器。

线程与线程本地变量的语义、线程池的队列与拒绝行为见 Java 并发编程;日志上下文的复制与清理方式见 Java 日志与常用类库规范 的 MDC 一节。

2.4.4 埋点对性能与代码可读性的影响

埋点本身是热路径上的代码,其开销来源与调用次数相关:

开销来源 说明
计时 每次调用读取高精度时钟,高频调用下累计开销不可忽略
标签拼装 构造标签值时产生的字符串拼接与装箱,未命中缓存时成本更高
注册表访问 指标注册与查找通常带并发保护,高频调用时会产生竞争
直方图更新 每次记录需要定位桶并累加,桶数量多时成本上升
快照导出 采集时的快照序列化会短暂占用锁,指标数量多时更明显

由此得到三条实践约束:

  1. 高频内部方法不做精确埋点。耗时与调用次数成正比的埋点应限制在业务边界、外部调用与资源池上,而不是循环体与工具方法。
  2. 标签取值提前确定。标签值应从枚举或缓存中取得,避免在记录时构造字符串。
  3. 埋点代码统一收敛。散布在业务逻辑中的埋点语句会降低可读性并使口径难以统一,应通过统一切面或专用组件集中实现,业务代码只提供语义标识。

需要说明的是:埋点开销不是"是否有"的问题,而是"加在哪里、加多少"的问题。判断某处埋点是否值得保留,依据是它能否在故障时减少定位时间,而不是它的绝对开销数值。

2.5 采集与暴露

2.5.1 拉取与推送

模式 工作机制 优点 缺点 适用
拉取(pull) 采集端按周期请求应用的指标端点 目标清单集中管理;可检测目标失联;应用不需要知道采集端地址 采集端需网络可达;短生命周期任务不易被稳定抓取 常驻服务、主机与中间件指标
推送(push) 应用主动把指标推送给接收端 适合短生命周期任务与网络不可达场景 无法区分"无数据"与"目标已消失";推送失败时静默丢数据 批处理任务、边缘网络、一次性作业

整体选择以拉取为主、推送为辅。应用侧的指标端点在拉取模式下成为被采集的常规目标,其可用性、鉴权与暴露范围是需要显式设计的一部分(见 3.1)。使用推送模式时必须配置数据过期机制,否则任务结束后旧指标会长期驻留并持续触发告警。

2.5.2 暴露端点与采集频率

  • 端点职责单一:对外暴露的指标端点只做序列化输出,不做聚合与计算,也不与业务接口共用路径与鉴权逻辑。
  • 采集频率与分辨率:频率决定能观察到的最短事件,也决定存储量。短时尖峰在间隔较长时会被平均掉,因此对延迟敏感的指标需要更短的间隔,容量类指标可以用更长的间隔。
  • 抓取超时小于间隔:避免采集任务叠加造成同一目标被并发抓取,进而放大端点处的开销。
  • 端点开销与指标数量相关:指标数量与序列数越大,序列化耗时与响应体越大,单次抓取的开销也越高。端点响应时间本身应作为被监控对象,它的劣化通常意味着指标数量失控。

2.5.3 标签基数与存储成本

时间序列数量由指标与其标签取值组合决定:

序列数 ≈ Σ(每个指标的标签取值组合数)
存储量 ≈ 序列数 × 采样点数 × 每样本字节数

关键在于标签取值组合是相乘关系。一个按接口、下游、状态码、版本、区域拆分的指标,即使每个标签只有若干个取值,组合后也可能达到数万条序列;再叠加多实例与多服务,存储与查询成本会远超线性预期。

高基数来源 后果 替代方案
请求标识、用户标识、订单号作为标签 序列数随业务量增长 放入日志或追踪属性
完整 URL 路径含资源 ID 每个资源一条序列 使用路由模板(接口模式)作为标签
异常消息文本作为标签 序列数随异常种类增长 按异常类型分类,消息文本进日志
未收敛的自定义枚举 取值集合随版本变化不断扩张 在代码侧限制取值并在评审中检查
采集端未过滤的默认标签 引入与用途无关的维度 在采集端按规则丢弃或重写标签

治理的优先级是先在被采集端限制,再在采集端过滤:代码侧的标签设计是根本,采集端过滤只能减轻症状。基数已经过大时,采集端的丢弃规则可以在不改动应用的前提下快速止血,但需要评估丢弃后告警与看板是否仍可用。

2.5.4 聚合与降采样

  • 预聚合:常用的比率与分位由记录规则周期性计算并保存,告警规则只做比较,避免在每次求值时重复扫描原始序列。
  • 降采样:原始分辨率数据保留较短周期(用于定位),降采样数据保留较长周期(用于容量趋势)。两者的保留期需与磁盘容量匹配。
  • 聚合必然丢失维度,因此聚合规则需要明确保留哪些标签供下钻使用;把维度聚合掉之后再想按实例定位时,只能回到原始数据或追踪。
  • 分位数不能先分位再聚合:跨实例的分位只能由桶计数聚合后计算,这一点与 2.2.4 一致。

2.6 告警设计衔接

埋点的终点之一是可被规则引用的指标。从指标到告警规则的映射需要明确四件事:

要素 内容 常见错误
条件 指标表达式与阈值形态 直接对底层技术指标设阈值,与用户感知脱节
阈值 绝对基线或相对基线 写死绝对值,不同规格实例上误报或漏报
持续时间 条件需连续满足的时长 无持续时间,瞬时抖动直接通知
分级与路由 严重级别与接收方 无责任方标签,通知群发无人确认

阈值来源决定规则是否可用。 相对基线(例如"延迟超过基线的 1.5 倍且持续 5 分钟")在多规格实例与弹性伸缩场景下更稳定;绝对阈值只适用于语义明确的量(预算消耗速率、池上限占比)。

持续时间应按指标的恢复时间分布确定,而不是统一取值:突发故障类要短,缓变资源类要长,比率类至少覆盖一个业务周期。持续时间与统计窗口叠加后,实际发现延迟是两者之和。

分级与抑制的关系:分级决定响应要求与通知方式,抑制处理"一个根因引发多条通知"的问题。应用侧尤其需要处理三类连锁:实例级故障引发的多条派生告警、下游故障引发的上游调用告警、发布与扩缩容窗口内的资源类告警。抑制方向必须是从底层到上层,且匹配范围要精确到实例或服务。

必须区分"数据缺失"与"值为零"。采集失败时段若被查询函数按空值处理,曲线会显示为无异常,形成漏报;反之,应用重启后计数器归零也可能被误判为异常。这两类情况需要各自显式的规则。

告警分级与响应要求、抑制与静默的边界及治理手段见 linux: SLO 与告警治理;指标类型、采集模型与规则构成的配置语法见 linux: 监控与告警。

2.7 与 SLO 的关系

埋点的最终用途是支撑服务水平目标,而不是让报表更完整。两者的关系体现在两处:

SLI 的选取原则(细节与表达式形态见 linux: SLO 与告警治理):

  1. 从用户可感知的行为出发(请求成功率、请求延迟、任务完成时延),而不是从资源使用率出发;
  2. 能从现有指标直接计算,不需要人工统计;
  3. 分母范围明确并写入定义;
  4. 每个服务保留少数几个核心 SLI,数量过多会互相牵制;
  5. 目标不高于关键依赖的可用性上限。

SLI 的选取直接决定埋点的要求。 需要成功率就要有按状态码分类的请求计数器;需要延迟目标就要有桶边界覆盖目标值的耗时直方图;需要饱和度就要有池占用与上限两个量。反过来,埋点缺少这些数据时,要么无法定义 SLI,要么只能用近似口径替代,导致预算计算与真实体验不符。

错误预算的用法是把目标转换为可消耗的额度,用于决定发布节奏与处置优先级:预算充足时按正常节奏推进变更,消耗过快时暂停非必要变更并优先恢复,长期消耗不完说明目标过松。部署与发布中如何按预算调整灰度与回滚策略见 linux: 变更与发布管理。本篇不重复预算的计算与消耗速率规则。


三、实现

3.1 接入与配置

3.1.1 指标框架的引入与自动配置

以 Spring Boot 与 Micrometer 为例,引入依赖后框架会自动完成请求、JVM、数据源、部分客户端的指标注册;需要额外配置的是输出格式、公共标签与分布口径:

management:
  endpoints:
    web:
      exposure:
        include: health,info,prometheus
  endpoint:
    prometheus:
      enabled: true
    health:
      probes:
        enabled: true
  metrics:
    tags:
      application: order-service
      region: ${REGION:cn-east}
    distribution:
      # 需要按分位查询的指标开启直方图,并显式定义与目标相关的桶边界
      percentiles-histogram:
        http.server.requests: true
      sli:
        http.server.requests: 100ms,300ms,1s

引入时需确认三件事:

  1. 端点只暴露一次:多个监控组件各自暴露端点会造成重复采集与口径分裂,也增加暴露面。
  2. 指标注册表进程内唯一:重复注册同名指标会抛出异常或静默失效,自定义指标名需要先检索既有名称。
  3. 自动配置的覆盖范围:框架自动埋点的粒度停留在边界上,业务语义与资源池水位需要按 3.2 与 3.3 补充。

3.1.2 端点暴露与安全

指标端点包含实例标识、版本、接口名称、依赖地址等信息,属于内部数据,不应与业务接口同等对外暴露:

# 使用独立的管理端口,与业务端口分离,便于网络策略单独控制
management:
  server:
    port: 8081
    address: 127.0.0.1

对外发布的边界控制方式有三种,通常组合使用:仅监听内网或本地回环地址;在网络策略上只允许采集端与探针访问;在端点前加一层鉴权。同时需要保证探针与采集端不被鉴权阻断,否则会出现"指标采集全部失败"或"实例被误判为不健康"。配置完成后应先在实例上确认端点可访问且指标名称符合预期,再交给采集端:

# 在实例上核对端点可访问性与指标前缀(仅在受控环境执行)
curl -s http://127.0.0.1:8081/actuator/prometheus | head -n 20
curl -s http://127.0.0.1:8081/actuator/prometheus | grep -c '^jvm_'      # 核对 JVM 指标已注册
curl -s http://127.0.0.1:8081/actuator/health                            # 核对健康端点供探针使用

高危 关闭指标端点或停止指标采集(关闭 prometheus 端点、在采集端移除目标、为降低开销而禁用自动埋点)

  • 影响范围:指标端点关闭后,采集端立即出现数据断点,以该指标为条件的告警在持续时间耗尽后触发或静默;断点期间的故障无法被观测,也无法在事后回溯趋势;采集端移除目标的影响范围与端点关闭等价,且更容易被遗忘而未恢复;为降低开销而整体禁用自动埋点会同时丢失请求、JVM 与池类指标,恢复后历史区间的趋势无法补齐。
  • 回滚方式:恢复端点配置或采集目标,确认指标序列在下一个采集周期内重新出现,并核对断点起止时间已记录到变更单中;断点期间的故障记录需要单独标注,避免在趋势分析时被当作"无异常"。
  • 前置要求:确需临时降低采集开销时,优先缩短保留期、减少非核心指标、调整采集频率或扩大采集间隔,而不是整体关闭;任何关闭动作需要明确恢复时间与责任人。

高危 禁用探针依赖的端点(关闭健康端点、关闭存活或就绪探针所需的检查项、限制管理端口访问范围到探针不可达)

  • 影响范围:该动作的影响不止于可观测性。存活探针无法判定时会按失败处理并重启容器,形成重启循环;就绪探针无法判定时实例会被摘除流量,造成容量骤降;发布期间出现这一状态会把一次普通发布放大为一次可用性事件。管理端口仅对采集端放行而漏掉探针来源时,现象与之相同。
  • 回滚方式:恢复端点与网络策略,确认实例重新通过探针检查并接回流量;若已发生重启循环,需要在恢复探针可用后核对实例数量与版本是否与预期一致。
  • 前置要求:修改管理端口的监听地址或访问策略前,列出采集端、探针与人工排查三类访问来源并逐一确认可达;变更后立刻核对实例的健康状态与就绪状态,而不是只看采集是否恢复。

3.1.3 多实例标签注入

指标需要按实例区分才能定位"只有某一台不正常"这类问题,实例标签需要由运行环境注入而不是写死在代码中:

@Configuration
public class MetricsConfig {

    @Bean
    MeterRegistryCustomizer<MeterRegistry> commonTags(
            @Value("${spring.application.name}") String appName,
            @Value("${POD_NAME:unknown}") String instanceId,
            @Value("${APP_VERSION:unknown}") String version) {
        return registry -> registry.config().commonTags(
                "application", appName,
                "instance", instanceId,
                "version", version);
    }
}

要点:

  1. 实例标识取编排环境中的稳定标识(Pod 名、容器实例标识),不要取进程号或启动时间戳,它们会随重启变化且无法与日志、追踪对齐;
  2. 版本标签是发布验证的基础,灰度与金丝雀期间需要按版本对比指标,缺少该标签则只能靠时间窗近似;
  3. 标签数量要克制,实例、版本、区域之外的维度应在方法级标签上体现,避免公共标签抬升全部指标的序列数;
  4. 同一批标识要注入日志与追踪,三类数据的实例取值一致才能互相跳转。

3.1.4 与编排环境探针的配合

事项 要点
探针使用的端点 存活与就绪探针使用健康端点,不要复用指标端点作为探针依据
探针超时 必须大于应用的最长合法停顿,否则一次较长的 GC 停顿会被判定为不健康
探针与采集端权限 两者可能位于不同网络区域,鉴权与防火墙规则需要分别放行
优雅停机 停机前先让就绪状态失败并摘除流量,再等待在途请求完成,期间指标仍需可采集,便于确认水位回落

探针配置的完整说明与优雅终止的流程见 Kubernetes 集群运维;容器内的资源限额与 JVM 视图差异见 Java 应用诊断与部署调优 的容器化一节。

3.2 应用指标埋点实践

3.2.1 HTTP 请求指标

框架自动埋点通常已经覆盖入站请求,需要确认的是维度与分布口径是否满足下钻与目标计算:

指标 类型 必要维度 用途
请求计数 计数 接口(路由模板)、方法、状态码、实例 请求量、错误率、SLI 分母
请求耗时 分布 接口、方法、状态码 分位延迟与"满足阈值占比"
请求体与响应体大小 分布 接口 大报文与带宽问题定位
进行中请求数 瞬时值 实例 请求堆积与线程占用

要点:

  1. 接口维度使用路由模板而不是真实路径,否则带资源标识的路径会使序列数随数据增长;
  2. 状态码按类与按码分别可用:错误率用 5xx 聚合,定位时下钻到具体码;
  3. 健康检查与探针请求需要显式处理:默认计入会稀释错误率,排除时需要在 SLI 定义中写明,避免口径变化;
  4. 超时与客户端断开的记录方式要统一,否则同一现象在一处计为错误、在另一处计为成功。

3.2.2 客户端调用指标

客户端调用是定位"慢在自身还是慢在下游"的关键。指标应围绕被调用的下游目标组织:

public <T> T callWithMetrics(MeterRegistry registry, String target, String method, Supplier<T> call) {
    Timer timer = Timer.builder("client.requests")
            .tag("target", target)          // 下游服务名,枚举取值
            .tag("method", method)          // 调用方法或接口,枚举取值
            .tag("result", "success")       // 结果标签需与错误路径配合
            .publishPercentileHistogram()
            .register(registry);
    return timer.record(call);
}
指标 类型 维度 用途
调用计数 计数 下游服务、接口、结果(成功/失败/超时) 依赖可用性与错误率
调用耗时 分布 下游服务、接口 区分自身排队与下游处理慢
重试次数 计数 下游服务、触发原因 判断重试是否掩盖了下游劣化
熔断状态与被拒绝请求数 瞬时值、计数 下游服务 判断熔断是否误触发或未生效

结果标签必须覆盖全部失败形态,包括超时、连接被拒、熔断拒绝与业务错误,否则错误率会显著低于实际。超时与业务错误需要分开统计,两者的处置方向不同:前者指向容量与超时配置,后者指向下游逻辑。

3.2.3 线程池与连接池指标

资源池饱和是"接口整体变慢但 CPU 不高"最常见的成因,且池的容量问题无法从外部观测中得到:

指标 类型 判读
活跃线程数 瞬时值 长期等于最大线程数说明容量或下游耗时是瓶颈
队列长度 瞬时值 持续增长说明处理能力不足;有界队列触顶后会转为拒绝
队列剩余容量 瞬时值 与队列长度配合判断剩余缓冲
拒绝任务数 计数 大于零即为必须处置项
完成任务数与执行耗时 计数、分布 判断处理能力的实际水平
连接池活跃连接 瞬时值 长期等于上限说明持有时间过长
等待获取连接的线程数 瞬时值 大于零说明存在获取竞争
获取连接超时次数 计数 直接反映容量不足或下游变慢

线程池指标的注册方式需要注意生命周期:注册表与应用生命周期绑定,池被销毁后应注销,否则残留指标会持续上报旧值。

连接池的指标通常由池组件自身暴露,其参数含义、池上限与数据库最大连接的核算方式见 Java 持久层。容器与主机侧的线程数与内存水位解释见 Java 应用诊断与部署调优 的诊断流程一节。

3.2.4 缓存指标

缓存指标需要同时表达"缓存本身是否有效"与"缓存失效对下游的压力":

指标 类型 维度 判读
读请求计数 计数 缓存名、结果(命中/未命中) 命中率 = 命中 ÷ 总读请求
写入与失效计数 计数 缓存名、操作类型 判断失效风暴与写入量
加载耗时 分布 缓存名 未命中后的回源耗时
回源计数 计数 缓存名、来源 未命中造成的下游压力
空值缓存计数 计数 缓存名 穿透防护是否生效

命中率单独看无意义:键被淘汰、数据批量过期、访问模式变化都会造成命中率下降,需要与键数量、淘汰计数、下游回源量一起判读。缓存失效与穿透的处理方式见 缓存基础;缓存实例侧的指标清单与判读方式见 Redis 运维与监控。

3.3 业务指标埋点实践

3.3.1 核心业务动作的计数与转化

业务指标回答的是"业务是否真的受影响",其维度来自业务的流转环节而不是技术结构:

// 动作计数:按渠道与结果拆分,取值均为枚举
registry.counter("business.order.created",
        "channel", channel,       // app / web / miniapp
        "result", result)         // success / rejected / failed
        .increment();

// 转化:同一批请求在各环节的通过数量,用同一分母计算通过率
registry.counter("business.payment.finished", "stage", "paid").increment();
指标 用途
关键动作计数(下单、支付、登录、发券) 判断业务量变化与功能可用性
分环节通过数 计算各环节通过率,定位流失发生在哪一步
处理时长(业务视角) 端到端业务耗时,与技术耗时口径区分
业务错误分类计数 区分参数错误、状态不允许、库存不足等可预期失败

转化类指标的要点是分子与分母来自同一批请求,且分母定义与 SLI 定义一致,否则通过率无法解释。常见错误是用"某接口的请求数"作分母、用"下游的动作数"作分子,两者之间存在重试与合并,比值会失真。

3.3.2 业务异常的分类计数

业务异常是流程的正常组成部分,需要与技术异常分开计数,否则会污染错误率并掩盖系统级失败:

类别 例子 定级与用途
参数与格式错误 参数缺失、格式非法 不计入系统错误率,用于评估上游质量
业务规则拒绝 库存不足、状态不允许、限额超限 单列计数,用于业务监控与规则评估
依赖不可用 下游超时、连接被拒 计入错误率,指向依赖与容量
系统异常 空指针、序列化失败、资源耗尽 计入错误率并直接触发告警

分类需要收敛到有限集合:按异常类型或预定义的错误码分类,不按异常消息分类。异常的原始信息属于日志的职责,指标只保留类别与发生位置。

3.3.3 命名与维度设计

业务指标的命名要让不具备实现细节的人也能读懂,通常需要包含"业务对象 + 动作/状态"两段,例如 business.order.created、business.payment.failed。维度设计的三条约束:

  1. 维度取业务上有意义且数量有界的枚举(渠道、业务类型、结果),不取用户、商户、商品等无界标识;
  2. 同一动作的指标名在所有服务中一致,跨服务的业务流转按同一名称关联;
  3. 指标名不使用内部系统代号,避免业务视图与系统重构绑定。

3.3.4 埋点位置的选择

位置 适用 风险
服务边界(控制器、消息消费入口) 请求级与流转级指标,与 SLI 口径一致 无法表达领域内部状态与重试后的最终结果
领域内部(领域服务、状态变更处) 业务动作的最终结果与状态流转 埋在过深的位置会随重构频繁变动,且容易被重复计数

判定依据是"这个动作的业务含义在哪个层次是确定的"。下单成功这一事实在支付完成、库存扣减、订单落库都完成之后才成立,因此应在领域流程的终点埋点,而不是在控制器入口;而"请求进入系统"这一事实在入口即确定,适合在边界埋点。同一动作在边界与领域内部各埋一次属于重复埋点,只有在两者确实表达不同含义(如"请求量"与"有效业务量")时才保留,并在命名上明确区分。

3.4 追踪埋点实践

3.4.1 入口与出口的自动埋点

追踪上下文在框架边界上自动建立与传播:入站请求解析请求头中的传播载体并创建 Span,出站调用把上下文写入请求头或消息属性。需要确认的边界有三处:

  1. 全部入口都被覆盖:HTTP 入口、消息消费入口、定时任务与批处理入口。后两类没有请求头,需要由调度标识或任务实例标识建立根 Span,否则链路无法串起。
  2. 全部出口都被覆盖:HTTP 客户端、消息生产者、数据库与缓存客户端。未覆盖的出口会表现为"链路中缺少某一跳",看起来像下游没处理。
  3. 传播格式统一:跨语言、跨协议时统一使用同一套传播载体,格式不一致会导致链路在边界处断裂。

3.4.2 跨线程与跨服务上下文传播

跨服务传播由框架完成,跨线程传播需要在应用侧处理,与 2.4.3 的方法一致:

// 包装执行器,使任务提交时复制上下文、执行结束后清理
ExecutorService traced = ContextExecutorService.wrap(
        Executors.newFixedThreadPool(8),
        Context.current());
场景 传播方式 常见遗漏
自定义线程池 包装执行器或任务装饰器 直接用原生线程池提交任务
组合式异步调用 由调用方显式传递上下文 依赖默认线程池,回调线程无上下文
消息生产与消费 标识写入消息属性,消费端恢复 只传业务字段,未传追踪上下文
定时任务与批处理 以任务实例标识建立根 Span 任务内不产生追踪数据或全部是孤立 Span

3.4.3 采样策略与成本控制

采样是追踪成本的主要控制手段,策略包括按比例采样、错误加权采样与按接口差异化采样。选择原则是保证"单位时间内被采样的异常链路数量足以支撑定位",而不是追求固定百分比。

高危 调整线上追踪采样率(下调采样比例、切换采样策略、关闭追踪上报)

  • 影响范围:采样率下调后,短时故障与低频错误可能不再被采集到,定位重新回到"只有指标没有链路"的状态;按比例采样在低比例下对低频接口的覆盖极差;切换采样策略会使采样前后数据不可比,历史链路的统计口径发生变化;关闭追踪上报会同时中断上下文传播的产物,日志中虽仍有标识但无法在追踪系统中查询;这些改动通常是为了降低存储与上报压力,若未同步调整保留期与索引配置,成本不会真正下降。
  • 回滚方式:恢复原采样配置并观察采集量恢复;需要重新采集已丢失的链路时只能复现问题,无法补采;采样率变更需要记录时间点,作为后续对比链路的取样区间边界。
  • 前置要求:优先通过缩短保留期、降低非核心接口的采样、开启尾部采样保留异常链路来降低开销;调整前评估当前采样量与被采集的错误链路数量,确认调整后仍能覆盖低频接口;变更在低峰执行并核对采集量与存储增长。

3.4.4 追踪与指标、日志的关联查询

三者的关联查询依赖 2.1 中的关联字段,实际使用时的路径是:

1. 由告警得到服务、接口与时间窗
2. 在指标上按该维度确认异常区间与影响面
3. 从直方图桶的样本引用(exemplar)跳到具体链路,或按时间窗筛选慢链路
4. 由链路中的 Trace ID 检索该请求在各服务中的日志
5. 由日志定位到具体输入与分支,回到代码确认

两处容易失效:日志未输出追踪标识(或使用了与追踪系统不同的标识),以及采样率过低导致异常请求未被采集。前者需要统一字段来源,后者需要在采集策略上保证错误链路优先。

3.5 仪表盘组织

3.5.1 分层仪表盘的设计

仪表盘按 2.3 的分层组织,每层解决一类问题,避免把全部指标堆在一个看板上:

层 关心的问题 主要面板
入口概览 现在是否正常,影响面多大 请求量、错误率、延迟分位、进行中请求数、错误预算消耗
依赖与中间件 慢在哪一跳 各下游调用量与延迟、超时与重试、熔断状态、缓存命中与淘汰
资源池 是否资源不足 线程池活跃与队列、连接池占用与等待、GC 次数与停顿
主机与 JVM 原因在机器还是进程 CPU、内存、磁盘 I/O、堆使用与回收后占用、线程数
业务核心 业务是否受影响 关键动作计数、分环节通过率、业务异常分类

3.5.2 常用面板与判读顺序

每个面板需要包含的要素:指标表达式、时间范围、聚合维度、用于对照的基线与当前阈值。示例面板定义(以通用结构描述):

{
  "title": "入口延迟分位与满足阈值占比",
  "panels": [
    {
      "title": "P50 / P95 / P99",
      "expr": "histogram_quantile(0.95, sum(rate(http_server_requests_seconds_bucket{application=\"order-service\"}[5m])) by (le, uri))",
      "unit": "seconds"
    },
    {
      "title": "300ms 内完成占比",
      "expr": "sum(rate(http_server_requests_seconds_bucket{application=\"order-service\",le=\"0.3\"}[5m])) by (uri) / sum(rate(http_server_requests_seconds_count{application=\"order-service\"}[5m])) by (uri)",
      "unit": "percent"
    }
  ]
}

判读顺序固定为先看影响面,再看环节,最后看资源:入口概览确认是否真的异常以及影响范围,依赖与资源池把影响面拆分到环节,主机与 JVM 解释环节异常的成因。业务核心看板用于确认技术指标正常时业务是否仍有问题。

3.5.3 告警与仪表盘的对应关系

每条告警都应能指向一个看板与一个面板。对应关系缺失时,告警接收方需要在多个看板之间寻找,响应时间被消耗在定位入口上。落地的做法是:

  1. 告警注解中携带服务、接口与时间窗,与看板中的筛选条件一致;
  2. 看板自身的变量以服务与实例为主,能够从告警通知中的标签直接定位;
  3. 告警使用的指标与看板使用的指标来自同一采集链路,避免两处数值不一致;
  4. 巡检发现的趋势项稳定后下沉为告警规则,看板保留趋势上下文,分工方式见 linux: 巡检与健康检查。

3.6 埋点治理

3.6.1 埋点清单与责任人

埋点需要像接口一样有清单:指标名称、类型、维度、采集方式(自动或手动)、代码位置、用途、责任人、引入时间。清单的价值在三处体现:删除无用指标时能确认没有规则依赖;定位指标异常时能直接找到代码位置;评审新增指标时能发现语义重复。

责任人按服务或模块划分,与告警责任方保持一致,避免出现"无人认领的指标"。

3.6.2 无用与重复指标的清理

类型 识别方式 处理
长期无查询与无告警引用的指标 统计查询日志与规则引用 下线,先在低峰观察一轮确认无依赖
语义重复的指标 清单中同语义不同名,或自动与手动埋点表达同一现象 保留口径正确的一处,删除另一处
已废弃功能对应的指标 清单中对应代码路径已下线 随代码一并删除
无任何下钻价值的聚合指标 只有总量、无维度 合并到有维度的指标,不单独保留

清理的触发时机是版本迭代与季度评估,而不是等到存储告警。

3.6.3 标签爆炸的识别与治理

识别信号有三类:序列数增速明显高于业务量增速;采集端抓取耗时上升或指标端点响应变慢;查询变慢并出现超时。

治理顺序为:先在代码侧修正标签取值(用枚举替换无界标识),再在采集端用丢弃规则止血,最后核对看板与告警规则在丢弃后是否仍可用。

高危 修改既有指标的标签结构(重命名标签、删除标签、改变标签取值含义、修改指标名)

  • 影响范围:标签或指标名是指标的唯一标识,改动等价于删除旧序列并新建序列,历史数据与新增数据不再连续,趋势图会出现断裂;以旧标签为条件的告警规则、记录规则与看板查询会直接失效或恒不触发;记录规则与降采样链路中的聚合结果会被旧序列污染;改动若与采集端重写规则叠加,可能出现同一指标的两套标签并存,造成重复计数。
  • 回滚方式:回滚需要在代码与采集端同时恢复原标签与指标名,恢复后历史断点仍需在图表中标注;已经丢失的序列无法补算,只能通过聚合规则近似补全,且不能覆盖分位类指标。
  • 前置要求:新增维度与新增指标优先于修改既有结构;确需修改时采用"新增指标名或新标签 + 双写一段时间 + 迁移规则与看板 + 下线旧指标"的过渡方式,并在变更单中列出受影响的规则与看板清单。

3.6.4 埋点变更的评审与兼容

埋点变更属于需要评审的变更,评审项包括:

  1. 命名与维度是否符合规范,是否与既有指标语义重复;
  2. 标签基数是否可控,取值集合是否随业务数据增长;
  3. 是否影响既有规则与看板,是否需要同步调整;
  4. 采集与存储成本的增量,序列数增加多少;
  5. 是否具备退出条件,临时为某次排查添加的埋点需要约定清理时间。

兼容性方面遵循"只增不改"的优先级:新增标签、新增指标对既有查询无破坏;删除标签、删除指标、重命名属于破坏性变更,需要按 3.6.3 的方式过渡。

3.6.5 埋点覆盖率检查

覆盖率检查用于发现"以为埋了实际没埋"的位置,检查方式是把关键清单与现有指标对照:

检查项 判据
入口覆盖 每个对外接口都出现在请求指标中,且可通过同一接口维度查询
出口覆盖 每个下游依赖都有调用耗时与错误计数
入口与出口的埋点是否贯通 请求指标与调用指标的时间窗与数量关系是否合理
资源池覆盖 每个业务线程池与连接池都有水位与拒绝计数
业务动作覆盖 核心流转的每个环节都有计数,分子分母可对
追踪覆盖 每个服务都有 Span 上报,跨服务链路能串成一条
关联字段覆盖 日志、指标、追踪三处的服务名与实例标识一致

覆盖率检查的时机是新增服务或新增大依赖时,以及每次架构调整之后;检查结果记录在清单中,与责任人绑定。

3.7 常见问题与排查

3.7.1 指标缺失或出现断点

现象 常见原因 排查入口
全部指标缺失 端点未暴露、端口未放行、采集端目标配置错误 直接访问指标端点确认是否有输出;确认采集端的目标列表与抓取错误信息
部分指标缺失 自动配置未覆盖该客户端、指标注册失败、名称冲突 端点上检索指标名;查看启动日志中的注册异常
数据出现断点 采集中断、应用重启、实例被替换后标识变化 对照实例标识的变化与采集端的失联记录
数值恒为零 埋点位置在异常路径之后、标签取值不匹配、刷新机制未生效 确认埋点是否在 finally 或结果确定之后;核对标签取值集合
数值翻倍 重复注册、同一现象被两处埋点、多实例聚合时未按实例区分 检查注册点数量与聚合表达式中的维度

"值为零"与"无数据"必须区分:前者说明采集正常但事件未发生或埋点未生效,后者说明采集链路本身有问题。查询函数在两种情况下返回不同结果,告警规则需要分别定义。

3.7.2 标签基数暴涨导致存储与查询变慢

现象是存储增长加快、指标端点响应变慢、查询超时。定位顺序:

1. 找出序列数增长最快的指标名
2. 逐个标签统计取值数量,定位无界维度(用户标识、资源 ID、异常消息)
3. 确认是否为近期变更引入(新增埋点、升级后的默认标签、框架自动添加的标签)
4. 在代码侧修正标签取值,或在采集端添加丢弃规则止血
5. 核对看板与告警在丢弃后是否仍可用,评估是否需要重新设计该指标

需要重点检查的隐蔽来源:框架或客户端库在新版本中自动添加的标签;采集端在重写规则中使用了上游标签;日志或追踪数据被误当作指标上报;异常处理路径把异常消息写入了标签。

3.7.3 埋点导致接口变慢

原因 表现 处置
在极高频路径上记录精确耗时与分布 接口耗时整体上升,CPU 上升,火焰图出现埋点框架栈 移除该位置埋点或改为低位采样,合并到边界指标
标签值在记录时构造 字符串拼接与装箱消耗明显 标签值预先计算或使用枚举
直方图桶数量过多 单次记录耗时上升 精简桶边界,只保留与目标相关的桶
指标注册表并发竞争 多线程同时注册同一指标 在启动阶段完成注册,运行期只做记录
追踪全量采集与同步上报 请求耗时随上报延迟上升 改为异步批量上报并设置本地缓冲上限

区分"埋点开销"与"业务变慢"的方法是:埋点开销随调用次数线性放大,且集中在埋点框架的调用栈上;业务变慢通常集中在业务代码帧或等待状态。采样剖析的判读方式见 Java 应用诊断与部署调优 的剖析与转储一节。

3.7.4 追踪断链

断链位置 原因 处置
服务之间 传播载体格式不一致、网关未透传请求头 统一传播规范并确认中间层不丢弃相关请求头
线程之间 使用原生线程池,上下文未复制 包装执行器或任务装饰器,成对设置与清理
消息生产与消费 未把上下文写入消息属性 在生产者附加、消费者恢复
定时任务与批处理 无入站请求头,未建立根 Span 以任务实例标识建立根 Span,并透传到下游
链路被采样丢弃 采样率过低,或各服务采样决策不一致 采用头部传播的采样决策或统一采样配置,保证同一链路内决策一致

排查顺序是从链路中已存在的最后一个 Span 往下游检查,确认该服务是否生成了下一个 Span,再判断问题在出口埋点、网络中间层还是下游入口。

3.7.5 告警误报与漏报的定位

类型 常见原因 定位方式
误报 阈值脱离基线、无持续时间、正常业务波峰被当作异常 对照同时段历史分布与业务周期;核对是否有变更
误报 分位数由不合理桶边界插值、跨实例分位被平均 检查桶定义与聚合表达式
误报 重试或客户端取消被计为错误 核对结果标签的判定条件
漏报 指标未覆盖该故障维度、埋点位置不产生数据 用清单做覆盖率检查
漏报 数据缺失被当作正常、计数器重置被忽略 为缺失与重置分别定义规则
漏报 持续时间过长,故障发生在窗口内已结束 缩短持续时间并与恢复时间分布对照
漏报 静默或抑制范围过宽 审计活跃静默与抑制规则

告警有效性以误报率、漏报数与处理时长趋势衡量,治理手段与评估方法见 linux: SLO 与告警治理;基线的采集与对照方法见 linux: 压测与性能基线。


四、总结

应用层观测的盲区来自维度的缺失,而不是数据的数量。 外部监控能回答"哪个接口慢、影响面多少",无法回答"慢在自身计算、锁等待、GC 停顿还是下游调用"。埋点的作用是把接口、状态码、下游服务、实例、版本这类维度预先写进数据,使下钻在故障发生时即可进行。

三类信号分工明确且必须能被互相定位。 指标定"什么时候、哪一类问题",追踪定"哪个环节",日志定"具体原因与输入"。关联依赖三个字段:日志中的 Trace ID 与 Span ID、指标直方图桶上的样本引用、以及三类数据共有的服务名与实例标识与时间窗。缺少关联字段时,三类数据各自成立却无法拼接。

指标体系的核心是四种基本类型与命名标签规范。 计数只增不减需取增量,瞬时值抖动需加持续时间,分布可跨实例聚合,摘要不可跨实例聚合;跨实例分位只能由直方图桶计算。"满足阈值的请求占比"比平均值更能表达服务水平;平均值与分位数不可互相替代。命名遵循固定结构与单位后缀,标签要求取值可枚举且数量有界——判别方法是看它的取值集合是否会随业务数据增长。

指标分四层:主机、JVM、应用框架、业务。 每层只回答该层的问题,判读顺序是业务与框架层先定影响面与环节,主机与 JVM 层后解释成因。分层不重复表达同一现象,跨层依靠实例与服务标识对齐。

埋点的分工是框架边界交给自动埋点、业务语义与领域状态交给手动埋点。 统一切面适用于横切、稳定、维度可枚举且异常路径已考虑的位置,不适用于业务语义指标与需要领域内部数据的场景。异步与线程池场景中上下文不会自动继承,传递必须成对设置与清理,避免线程复用造成串号。埋点开销与调用次数成正比,高频内部方法不做精确埋点。

采集以拉取为主、推送为辅,成本由标签基数决定。 序列数由各标签取值组合相乘得到,一个无界标签即可让存储与查询成本非线性增长。治理顺序是先修正代码侧标签设计,再在采集端过滤止血,最后核对告警与看板是否仍可用。聚合必然丢失维度,分位数不能先分位再聚合。

从指标到告警需要明确条件、阈值、持续时间与分级路由四件事。 阈值优先使用相对基线,持续时间按指标的恢复时间分布确定,抑制方向必须从底层到上层,且必须区分"数据缺失"与"值为零"。SLI 的选取直接决定埋点要求:要成功率就要按状态码分类的计数器,要延迟目标就要桶边界覆盖目标值的直方图。

落地上,应用指标围绕 HTTP 请求、客户端调用、线程池与连接池、缓存四类组织,业务指标围绕关键动作计数与分环节通过率组织,追踪埋点补齐入口出口与跨线程跨服务传播。 仪表盘按层组织,判读顺序是先影响面、再环节、最后资源;每条告警都应能指向一个看板与一个面板。

治理的抓手是清单、审查与覆盖率检查。 埋点清单记录名称、维度、位置、用途与责任人,使清理与定位都有依据;标签爆炸通过序列数增速与查询耗时变化识别;埋点变更遵循"只增不改",破坏性变更采用新增与过渡再下线的方式;覆盖率检查在新增服务与新增大依赖时执行。

四类破坏性操作需要显式管控: 关闭指标端点或停止采集(断点期间故障不可观测,且可能与健康检查耦合导致实例被摘除)、修改既有指标的标签结构(等价于重建序列,使历史断裂、规则与看板失效)、下调追踪采样率(低频异常不再被采集,历史区间不可比)、禁用端点(同时中断采集与探针依据)。这类动作的统一要求是:明确影响范围、给出回滚方式、记录起止时间、并在恢复后核对数据是否真正回来。

一句话记忆:指标定趋势、日志定细节、追踪定环节,三者靠追踪标识与实例标签互跳;命名带单位、标签要有界,分位看桶不看平均;框架边界自动埋、业务语义手动埋,异步上下文要成对传递与清理;拉取为主推送为辅,成本由基数决定;告警先定基线再定持续,SLI 决定要埋什么;埋点清单管有无、覆盖率检查管漏挖,关采集、改标签、降采样、禁端点四类动作先报影响再动手。