一、起源:应用层观测的盲区
1.1 只能看到接口慢,无法回答慢在哪一层
主机侧监控回答的是"机器是否正常",接入层与网关回答的是"请求量与错误率的整体水位",两者都不进入进程内部。当问题表现为单个接口变慢时,外部观测能给出的结论通常停留在"某几个接口变慢、影响面约多少",而处置需要的信息在进程内:
| 外部观测到的现象 | 外部能给出的结论 | 需要应用内信息才能回答的问题 |
|---|---|---|
| 接口 P99 上升 | 哪些接口变慢、整体影响面 | 耗时在自身计算、锁等待、GC 停顿还是下游调用 |
| 错误率上升 | 失败请求占比 | 失败集中在哪个异常类型、哪个下游、哪类参数 |
| 吞吐下降 | QPS 降幅 | 上游限流、自身拒绝、客户端超时放弃还是容量不足 |
| 单实例异常 | 某一台与其他不一致 | 该实例的线程池、连接池、GC、依赖连接是否偏离 |
| 长尾超时 | 少量请求超时 | 超时请求是否集中在特定接口、版本、下游或数据规模 |
这些问题的共同结构是缺少可下钻的维度。整体平均值只能说明"有事发生",把同一个数值按接口、状态码、下游服务、实例、版本拆分之后,才能看出问题是否集中。埋点的直接目的就是把这些维度预先写进数据,使下钻在故障发生时即可进行,而不必等到事后补代码再发布。
1.2 事后排查与实时告警的差别
两件事对数据的要求不同,容易混为一谈:
| 维度 | 事后排查 | 实时告警 |
|---|---|---|
| 触发方式 | 人工发起,或由告警引出 | 由规则周期性求值自动触发 |
| 时间尺度 | 分钟级至小时级,可接受查询耗时 | 秒级至分钟级,查询必须足够快 |
| 依赖数据 | 日志、追踪、快照、指标均可 | 以指标为主,需要可计算、可聚合的数值 |
| 对埋点的要求 | 字段完整、能还原现场 | 数值化、带标签、基数有界、可被表达式引用 |
| 失效后果 | 定位变慢,结论可能不完整 | 故障静默发生,发现延迟由业务反馈决定 |
日志很难直接充当告警条件:日志量随请求量线性增长,按文本匹配的判定既昂贵又脆弱,字段一旦改动规则即失效。追踪数据的采集本身就是采样的,不能作为告警的计数来源。因此"能否告警"对埋点提出了外部观测没有的要求——指标必须是可聚合的数值,标签必须可枚举且有界。
这条差别解释了为什么同一份埋点要区分两种用途:为了排查而埋的字段可以很细,为了告警而埋的指标必须克制。混淆两者会得到两种典型结果:字段很全但无法写出稳定的规则,或指标很干净但在定位时缺少上下文。
1.3 埋点缺失与埋点过度的两种失败
| 失败形态 | 表现 | 代价 | 典型成因 |
|---|---|---|---|
| 埋点缺失 | 告警只有"接口慢",定位只能靠复现或猜测 | 观测窗口被错过,不可复现问题无法复盘 | 只依赖框架默认埋点,未覆盖业务动作与资源池 |
| 埋点过度 | 指标数量庞大、看板无人看、告警频发 | 存储与查询成本上升、采集本身带来开销、噪声掩盖真实信号 | 按需求逐条添加、无退出机制、标签维度随意扩展 |
两类失败的判定标准是同一个:这条埋点是否指向一个具体问题与一个具体动作。能回答"出现异常时下一步看什么"的埋点在缺失时会造成损失;无法回答这个问题的埋点在存在时会造成成本。埋点缺失通常发生在业务动作、资源池水位、异常分类这些框架默认覆盖不到的角落;埋点过度通常发生在同一问题被多种指标重复表达、或指标被当成日志使用的地方。
一种常见的中间状态是"指标齐全但无法定位":采集了请求量、错误率、延迟分位,却没有按接口、下游、版本拆分,也没有资源池与业务动作的水位,结果是告警能触发但无法收敛到原因。本篇讨论的正是从数据到原因之间的这一层。
二、原理
2.1 三类信号的分工与关联
指标、日志、追踪各自回答不同的问题,不能互相替代:
| 信号 | 回答的问题 | 数据结构 | 成本特征 | 优势场景 |
|---|---|---|---|---|
| 指标 | 是否异常、程度如何、影响多少 | 数值加标签,结构固定 | 与时间点数量成正比,相对低廉 | 趋势判断、阈值告警、容量规划 |
| 日志 | 具体发生了什么、输入是什么 | 文本或结构化字段,结构自由 | 与事件数量成正比,通常最高 | 根因定位、事件明细、取证 |
| 追踪 | 请求经过了哪些环节、慢在哪一跳 | 带父子关系的 Span 树 | 与采样后的调用量成正比 | 链路与依赖分析、跨服务耗时拆解 |
关联字段是三类信号能互相跳转的前提。 没有统一的关联键,三类数据就是三座孤岛:
- 追踪标识:日志中必须携带 Trace ID 与 Span ID,才能由一次慢请求的链路定位到该请求在各服务中产生的日志;追踪上下文的传播格式(W3C Trace Context 与 B3)与采样策略见 Spring Cloud 微服务 第 2.7 节。
- 样本引用(exemplar):指标不携带请求标识,但可以在直方图桶上附带被观测请求的 Trace ID 样本,使"看到一个高延迟数据点"可以直接跳到"那一次请求的完整链路"。这是从指标到追踪最短的路径。
- 公共维度:服务名、实例标识、版本、时间窗是三类数据共有的检索键。它们在三类数据中的取值口径必须一致,否则跨数据源的筛选结果对不上。
- 跳转顺序:指标先定"什么时候、哪一类问题",追踪再定"哪个环节",日志最后定"具体原因与输入"。反向跳转只在需要确认某个异常是否影响了整体指标时使用。
日志侧的追踪标识生成、透传与 MDC 接入方式已在 Java 日志与常用类库规范 的链路关联一节给出,本篇不重复日志配置本身,只说明埋点侧需要保证的字段。
2.2 指标体系与命名
2.2.1 四种基本类型
指标按数值语义分为四类,选择依据是"这个量在时间上如何变化"以及"是否需要分布信息":
| 类型 | 语义 | 是否可直接取值 | 适用 | 主要陷阱 |
|---|---|---|---|---|
| 计数(Counter) | 只增不减的累计量 | 否,需取增量 | 请求数、错误数、调用次数、拒绝次数 | 直接看原始值无意义;误用计数器表达可增减的量 |
| 瞬时值(Gauge) | 某一时刻的瞬时量 | 是 | 活跃线程数、队列长度、连接占用、堆使用量 | 抖动明显,告警必须加持续时间;语义上不可增的池上限不要用瞬时值 |
| 分布(Histogram) | 由桶计数累积构成的分布 | 否,需按桶计算 | 请求耗时、报文大小、批次规模 | 桶边界设置不当导致分位精度下降;桶数量影响序列数 |
| 摘要(Summary) | 客户端预先计算的分位值 | 否 | 需要精确分位且不跨实例聚合的少量指标 | 分位值不可跨实例聚合;一经计算无法回溯原始分布 |
分布与摘要的核心差别在于能否聚合。 摘要在采集端算出分位并上报,跨实例对分位值求平均或求最大值在数学上都不成立;直方图上报的是桶计数,可以在任意维度上先求和再求分位,因此更适合多实例、多服务的场景。以 Prometheus 为存储的体系里,跨实例的分位计算只能由直方图完成。
2.2.2 命名与标签设计
命名规范。指标名是查询与告警中的标识,改动即导致既有查询与看板失效,因此需要在项目内统一:
- 结构固定为"域_对象_度量",全部小写,以点或下划线分隔,同一体系内只选一种;
- 计数器以
_total结尾,单位写在名称中并使用基本单位(秒、字节,而不是毫秒、兆字节); - 同名指标在所有模块中语义一致,不使用"某模块的耗时"与"另一模块的耗时"共用一个名字;
- 不使用缩写,除非是团队内已有共识且不可歧义的形式;
- 框架自动埋点的名称不做重命名,自定义指标不与框架名称冲突,避免语义被覆盖。
标签设计。标签决定了指标能否下钻,同时决定了成本,两者是一组取舍:能下钻的维度越多,时间序列数量越多。
| 设计要点 | 说明 | 反例 |
|---|---|---|
| 取值可枚举且数量有界 | 取值集合是有限且稳定的,例如接口、状态码、渠道 | 用户标识、订单号、请求标识 |
| 维度承载语义 | 每个标签回答"按什么视角拆分" | 为了调试加入的环境变量散值 |
| 避免把标识当标签 | 无界标识应作为日志字段或追踪属性 | 完整 URL 路径、SQL 语句、异常消息 |
| 标签数量克制 | 单个指标一般不超过 5 至 6 个标签,且不同时段取值集合稳定 | 同时按接口、下游、状态码、渠道、版本、区域拆分 |
判别一条维度能否作为标签的方法是:它的取值集合是否会随业务数据增长而增长。 URL 中的资源 ID、用户标识、商品编码、异常消息文本都属于会增长的一类,放进标签会造成序列数随数据无限膨胀。这类维度只适合出现在日志与追踪中,那里按事件存储,成本与查询方式都不依赖取值集合的大小。
2.2.3 单位与口径一致性
同一现象在不同来源必须有同一口径,否则数据之间无法互相验证:
- 耗时口径:服务端处理耗时(从收到请求到响应完成)不含客户端网络时间;客户端调用耗时含连接与网络。两者的差值即网络与排队开销,只有口径明确时这个差值才有意义。
- 分母口径:成功率的失败定义(是否包含超时、连接重置、客户端 4xx)与分母范围必须写进定义,改动需记录时间点,否则历史对比失去意义。
- 单位与精度:统一使用秒与字节,展示层再换算;避免同一指标在两个模块分别以毫秒与秒上报。
- 采样窗口口径:跨实例聚合时分位计算在单一数据源内完成,不对各实例的分位值做平均。
口径不一致的表现是"两个系统对同一件事给出不同数字",排查时会把时间大量消耗在解释差异上。
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 请求、下游调用、线程池、连接池、缓存 | 慢在哪个环节、哪个资源池饱和 | 框架自动埋点与客户端/池组件指标 |
| 业务层 | 业务动作计数与转化、业务异常分类 | 业务是否真的受影响、影响在哪个环节 | 业务代码显式埋点 |
分层后的三条判读纪律:
- 先上层后下层。业务层与框架层直接反映用户感知,主机与 JVM 层解释原因。出现业务指标异常时先按框架层拆分,再进入 JVM 与主机层找解释,而不是从 CPU 使用率开始。
- 层间不重复表达同一现象。主机层内存使用率与 JVM 层堆使用量是不同的量,两者同时告警时若都指向"内存不足",说明其中一层的阈值设置未针对本层语义。
- 跨层需要关联键。三层数据要按实例、服务、时间对齐才能拼接成一条证据链,实例标识的注入方式见 3.1。
2.4 埋点方式
2.4.1 自动埋点与手动埋点
| 维度 | 自动埋点 | 手动埋点 |
|---|---|---|
| 覆盖范围 | 框架已识别的边界:入站请求、客户端调用、部分池与 GC | 业务动作、领域内部状态、框架未覆盖的自定义路径 |
| 命名一致性 | 由框架统一,跨服务口径一致 | 依赖约定,容易在模块之间出现同义不同名 |
| 变更成本 | 随框架升级变动,需要跟随适配 | 随代码演进,需要与业务一起维护 |
| 主要局限 | 粒度停留在框架边界,不包含业务语义;对非标准路径可能漏采 | 覆盖不全、位置随意时形成重复与遗漏 |
实践中的分工是明确的:框架边界与资源池交给自动埋点,业务语义与领域内部状态交给手动埋点。 在框架已覆盖的位置手工重复埋点,得到的往往是同一现象的两套数字,且两者在异常路径上口径不同。
2.4.2 AOP 或拦截器统一埋点的适用条件
统一埋点把横切关注点(计时、计数、异常分类)从业务代码中提取出来,适用于满足以下条件的位置:
- 关注点是横切的:同一段逻辑需要在多个方法或请求上重复执行;
- 位置是稳定的:切点对应的类与方法在该层中不会频繁改名,或有测试与评审保证改名时同步更新;
- 维度可枚举:从入参或上下文能取出有界的标签取值,而不是把入参整体作为标签;
- 异常路径已考虑:埋点必须在异常抛出时同样记录结果标签,否则错误计数恒为零。
不适合使用统一切面的情况:
- 业务语义指标:下单成功数需要业务规则判定,切面无法在服务边界外得到结果;
- 需要领域内部数据:埋点落在领域方法内部才能拿到判定依据时,切面只能记录调用发生,不能记录业务结论;
- 切点范围过宽:以包或注解匹配大范围方法并在每次调用上计时计数,会把开销加到高频内部调用上;
- 需要精确控制时机的路径:异步提交、重试、批量操作等场景中,一次业务动作对应多次方法调用,切面计数会把调用次数当成业务次数。
使用切面时还需要注意代理方式带来的边界:基于接口的代理与基于子类的代理在自调用、final 方法、静态方法上的行为不同;同类内部方法调用不经过代理,可能造成同一类中部分方法被埋点而另一部分不被埋点。
2.4.3 异步与线程池场景的上下文传递
追踪上下文与日志上下文默认都绑定在当前线程上,进入线程池后不会被继承。这是异步化之后"链路断裂""日志串号""指标归属错误"的共同原因:
| 场景 | 上下文丢失的表现 | 处理方式 |
|---|---|---|
| 自定义线程池 | 子任务没有 Trace ID,日志无法归入链路 | 包装线程池或任务提交口,随任务复制上下文 |
| 框架异步执行 | 注解式异步方法与定时任务的执行线程无上下文 | 在任务入口显式建立上下文,出口清理 |
| 组合式异步调用 | 回调链在公共线程池上执行,上下文与调用方无关 | 由调用方显式传递,不依赖默认线程池 |
| 消息生产与消费 | 生产与消费两侧的日志分属两条链路 | 把标识写入消息属性,消费端恢复到上下文 |
两条约束:
- 传递必须成对。线程池中的线程被复用,任务执行完成后上下文若未清理,会残留给下一个任务,造成日志串号与指标归属错误。设置与清理需要在同一处成对出现,且清理放在
finally中。 - 共享线程池需要额外处理。多个业务共用同一个线程池时,任务之间上下文会互相污染;应为需要上下文的执行链路使用独立线程池或包装后的执行器。
线程与线程本地变量的语义、线程池的队列与拒绝行为见 Java 并发编程;日志上下文的复制与清理方式见 Java 日志与常用类库规范 的 MDC 一节。
2.4.4 埋点对性能与代码可读性的影响
埋点本身是热路径上的代码,其开销来源与调用次数相关:
| 开销来源 | 说明 |
|---|---|
| 计时 | 每次调用读取高精度时钟,高频调用下累计开销不可忽略 |
| 标签拼装 | 构造标签值时产生的字符串拼接与装箱,未命中缓存时成本更高 |
| 注册表访问 | 指标注册与查找通常带并发保护,高频调用时会产生竞争 |
| 直方图更新 | 每次记录需要定位桶并累加,桶数量多时成本上升 |
| 快照导出 | 采集时的快照序列化会短暂占用锁,指标数量多时更明显 |
由此得到三条实践约束:
- 高频内部方法不做精确埋点。耗时与调用次数成正比的埋点应限制在业务边界、外部调用与资源池上,而不是循环体与工具方法。
- 标签取值提前确定。标签值应从枚举或缓存中取得,避免在记录时构造字符串。
- 埋点代码统一收敛。散布在业务逻辑中的埋点语句会降低可读性并使口径难以统一,应通过统一切面或专用组件集中实现,业务代码只提供语义标识。
需要说明的是:埋点开销不是"是否有"的问题,而是"加在哪里、加多少"的问题。判断某处埋点是否值得保留,依据是它能否在故障时减少定位时间,而不是它的绝对开销数值。
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 与告警治理):
- 从用户可感知的行为出发(请求成功率、请求延迟、任务完成时延),而不是从资源使用率出发;
- 能从现有指标直接计算,不需要人工统计;
- 分母范围明确并写入定义;
- 每个服务保留少数几个核心 SLI,数量过多会互相牵制;
- 目标不高于关键依赖的可用性上限。
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
引入时需确认三件事:
- 端点只暴露一次:多个监控组件各自暴露端点会造成重复采集与口径分裂,也增加暴露面。
- 指标注册表进程内唯一:重复注册同名指标会抛出异常或静默失效,自定义指标名需要先检索既有名称。
- 自动配置的覆盖范围:框架自动埋点的粒度停留在边界上,业务语义与资源池水位需要按 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);
}
}
要点:
- 实例标识取编排环境中的稳定标识(Pod 名、容器实例标识),不要取进程号或启动时间戳,它们会随重启变化且无法与日志、追踪对齐;
- 版本标签是发布验证的基础,灰度与金丝雀期间需要按版本对比指标,缺少该标签则只能靠时间窗近似;
- 标签数量要克制,实例、版本、区域之外的维度应在方法级标签上体现,避免公共标签抬升全部指标的序列数;
- 同一批标识要注入日志与追踪,三类数据的实例取值一致才能互相跳转。
3.1.4 与编排环境探针的配合
| 事项 | 要点 |
|---|---|
| 探针使用的端点 | 存活与就绪探针使用健康端点,不要复用指标端点作为探针依据 |
| 探针超时 | 必须大于应用的最长合法停顿,否则一次较长的 GC 停顿会被判定为不健康 |
| 探针与采集端权限 | 两者可能位于不同网络区域,鉴权与防火墙规则需要分别放行 |
| 优雅停机 | 停机前先让就绪状态失败并摘除流量,再等待在途请求完成,期间指标仍需可采集,便于确认水位回落 |
探针配置的完整说明与优雅终止的流程见 Kubernetes 集群运维;容器内的资源限额与 JVM 视图差异见 Java 应用诊断与部署调优 的容器化一节。
3.2 应用指标埋点实践
3.2.1 HTTP 请求指标
框架自动埋点通常已经覆盖入站请求,需要确认的是维度与分布口径是否满足下钻与目标计算:
| 指标 | 类型 | 必要维度 | 用途 |
|---|---|---|---|
| 请求计数 | 计数 | 接口(路由模板)、方法、状态码、实例 | 请求量、错误率、SLI 分母 |
| 请求耗时 | 分布 | 接口、方法、状态码 | 分位延迟与"满足阈值占比" |
| 请求体与响应体大小 | 分布 | 接口 | 大报文与带宽问题定位 |
| 进行中请求数 | 瞬时值 | 实例 | 请求堆积与线程占用 |
要点:
- 接口维度使用路由模板而不是真实路径,否则带资源标识的路径会使序列数随数据增长;
- 状态码按类与按码分别可用:错误率用 5xx 聚合,定位时下钻到具体码;
- 健康检查与探针请求需要显式处理:默认计入会稀释错误率,排除时需要在 SLI 定义中写明,避免口径变化;
- 超时与客户端断开的记录方式要统一,否则同一现象在一处计为错误、在另一处计为成功。
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。维度设计的三条约束:
- 维度取业务上有意义且数量有界的枚举(渠道、业务类型、结果),不取用户、商户、商品等无界标识;
- 同一动作的指标名在所有服务中一致,跨服务的业务流转按同一名称关联;
- 指标名不使用内部系统代号,避免业务视图与系统重构绑定。
3.3.4 埋点位置的选择
| 位置 | 适用 | 风险 |
|---|---|---|
| 服务边界(控制器、消息消费入口) | 请求级与流转级指标,与 SLI 口径一致 | 无法表达领域内部状态与重试后的最终结果 |
| 领域内部(领域服务、状态变更处) | 业务动作的最终结果与状态流转 | 埋在过深的位置会随重构频繁变动,且容易被重复计数 |
判定依据是"这个动作的业务含义在哪个层次是确定的"。下单成功这一事实在支付完成、库存扣减、订单落库都完成之后才成立,因此应在领域流程的终点埋点,而不是在控制器入口;而"请求进入系统"这一事实在入口即确定,适合在边界埋点。同一动作在边界与领域内部各埋一次属于重复埋点,只有在两者确实表达不同含义(如"请求量"与"有效业务量")时才保留,并在命名上明确区分。
3.4 追踪埋点实践
3.4.1 入口与出口的自动埋点
追踪上下文在框架边界上自动建立与传播:入站请求解析请求头中的传播载体并创建 Span,出站调用把上下文写入请求头或消息属性。需要确认的边界有三处:
- 全部入口都被覆盖:HTTP 入口、消息消费入口、定时任务与批处理入口。后两类没有请求头,需要由调度标识或任务实例标识建立根 Span,否则链路无法串起。
- 全部出口都被覆盖:HTTP 客户端、消息生产者、数据库与缓存客户端。未覆盖的出口会表现为"链路中缺少某一跳",看起来像下游没处理。
- 传播格式统一:跨语言、跨协议时统一使用同一套传播载体,格式不一致会导致链路在边界处断裂。
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 告警与仪表盘的对应关系
每条告警都应能指向一个看板与一个面板。对应关系缺失时,告警接收方需要在多个看板之间寻找,响应时间被消耗在定位入口上。落地的做法是:
- 告警注解中携带服务、接口与时间窗,与看板中的筛选条件一致;
- 看板自身的变量以服务与实例为主,能够从告警通知中的标签直接定位;
- 告警使用的指标与看板使用的指标来自同一采集链路,避免两处数值不一致;
- 巡检发现的趋势项稳定后下沉为告警规则,看板保留趋势上下文,分工方式见 linux: 巡检与健康检查。
3.6 埋点治理
3.6.1 埋点清单与责任人
埋点需要像接口一样有清单:指标名称、类型、维度、采集方式(自动或手动)、代码位置、用途、责任人、引入时间。清单的价值在三处体现:删除无用指标时能确认没有规则依赖;定位指标异常时能直接找到代码位置;评审新增指标时能发现语义重复。
责任人按服务或模块划分,与告警责任方保持一致,避免出现"无人认领的指标"。
3.6.2 无用与重复指标的清理
| 类型 | 识别方式 | 处理 |
|---|---|---|
| 长期无查询与无告警引用的指标 | 统计查询日志与规则引用 | 下线,先在低峰观察一轮确认无依赖 |
| 语义重复的指标 | 清单中同语义不同名,或自动与手动埋点表达同一现象 | 保留口径正确的一处,删除另一处 |
| 已废弃功能对应的指标 | 清单中对应代码路径已下线 | 随代码一并删除 |
| 无任何下钻价值的聚合指标 | 只有总量、无维度 | 合并到有维度的指标,不单独保留 |
清理的触发时机是版本迭代与季度评估,而不是等到存储告警。
3.6.3 标签爆炸的识别与治理
识别信号有三类:序列数增速明显高于业务量增速;采集端抓取耗时上升或指标端点响应变慢;查询变慢并出现超时。
治理顺序为:先在代码侧修正标签取值(用枚举替换无界标识),再在采集端用丢弃规则止血,最后核对看板与告警规则在丢弃后是否仍可用。
高危 修改既有指标的标签结构(重命名标签、删除标签、改变标签取值含义、修改指标名)
- 影响范围:标签或指标名是指标的唯一标识,改动等价于删除旧序列并新建序列,历史数据与新增数据不再连续,趋势图会出现断裂;以旧标签为条件的告警规则、记录规则与看板查询会直接失效或恒不触发;记录规则与降采样链路中的聚合结果会被旧序列污染;改动若与采集端重写规则叠加,可能出现同一指标的两套标签并存,造成重复计数。
- 回滚方式:回滚需要在代码与采集端同时恢复原标签与指标名,恢复后历史断点仍需在图表中标注;已经丢失的序列无法补算,只能通过聚合规则近似补全,且不能覆盖分位类指标。
- 前置要求:新增维度与新增指标优先于修改既有结构;确需修改时采用"新增指标名或新标签 + 双写一段时间 + 迁移规则与看板 + 下线旧指标"的过渡方式,并在变更单中列出受影响的规则与看板清单。
3.6.4 埋点变更的评审与兼容
埋点变更属于需要评审的变更,评审项包括:
- 命名与维度是否符合规范,是否与既有指标语义重复;
- 标签基数是否可控,取值集合是否随业务数据增长;
- 是否影响既有规则与看板,是否需要同步调整;
- 采集与存储成本的增量,序列数增加多少;
- 是否具备退出条件,临时为某次排查添加的埋点需要约定清理时间。
兼容性方面遵循"只增不改"的优先级:新增标签、新增指标对既有查询无破坏;删除标签、删除指标、重命名属于破坏性变更,需要按 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 决定要埋什么;埋点清单管有无、覆盖率检查管漏挖,关采集、改标签、降采样、禁端点四类动作先报影响再动手。