第 19 章 —— 通过可观测信号定位副本差异
本章目标： 本章完成后，开发者能够把 diagnostics、低基数 metrics 和 trace 组合成可证伪的排障假设，而不是只盯着一个「同步失败」计数器。
学习目标
- 从
RuntimeDiagnostics读取身份、状态、成员视图与集合摘要。 - 用 outcome/reason 指标区分成员、传播、repair、Lease 和消费者问题。
- 用 trace context 关联一次跨节点传播。
- 避免高基数标签与无边界的诊断快照。
前置条件
- 已完成第 12 章 repair 和第 13 章背压。
- 已完成第 18 章证据分层。
- 理解诊断数据是观察，不是新的权威事实源。
案例进度
node-b 的 route hint 比 node-a
陈旧。团队不再直接重启节点，而是先确认 Runtime 是否
RUNNING、成员是否可见、目标 locator 是否注册、是否有 message drop/repair
outcome，再用 trace 关联该次传播。
三个观察面组成诊断循环
Diagnostics：现在是什么状态
runtime.diagnostics() 返回不可变快照，包括
RuntimeInfo、生命周期状态、cluster
view、总条目数、各集合诊断、Lease
专属诊断和最后错误。它适合回答「当前这个节点看见什么」，不提供历史趋势。
Metrics：哪类结果正在累积
DsmMetrics 记录 sync latency、cluster
size、认证失败、消息丢弃、repair outcome、Lease
acquire/renew/transfer/release、fencing reject、ChangeStream overflow
等。reason 与 outcome 应保持低基数，才能用于聚合和告警。
Trace：这一次动作经过哪里
TraceContextHolder 让 outbound platform envelope
携带当前 trace context；两节点集成测试验证 register delta 能传播
trace。Trace 用于关联一次路径，不替代 metrics 的趋势或 diagnostics
的当前快照。
一条可执行排障路径
| 步骤 | 问题 | 首选信号 |
|---|---|---|
| 1 | Runtime 是否准备好 | state、isReady、lastErrorMessage |
| 2 | 节点是否在正确通信域 | cluster view、service/cluster mismatch metric |
| 3 | locator 是否注册且 schema 匹配 | collection diagnostics、message dropped reason |
| 4 | 在线 delta 是否到达 | sync latency、REMOTE_DELTA、trace |
| 5 | repair 是否发现并处理差异 | digest/repair outcome、replay/snapshot reason |
| 6 | 只是观察者落后吗 | ChangeStream overflow/callback timeout |
每一步都能生成下一条可证伪假设。例如「成员正常、delta drop 增加、后续 repair success」支持在线漏失而非 locator 配错。
高基数是另一种故障
把任意 entryKey、异常全文或 traceId 放进 metrics
tag，会让时间序列数量随业务数据增长。DsmMetrics
的文档明确要求稳定 reason/outcome；具体 key
和异常上下文进入结构化日志、审计或 trace，而不是第一层指标维度。
反例与故障注入
- 让 ChangeStream 容量溢出，确认集合 diagnostics 仍可显示当前条目，而 overflow metric 增长。
- 注入 50% 控制面丢失，确认后续 repair outcome 可见。
- 在 trace context 下执行 register put，确认 outbound envelope 带 trace。
- 把随机 entryKey 作为 tag 写进练习资产，观察 cardinality 审查拒绝。
实验
cd submodule/dsm
mvn -q -pl dsm-runtime,dsm-sync,dsm-metrics-micrometer,dsm-integration-test -am \
-Dtest=DefaultDsmRuntimeTest,MicrometerDsmMetricsTest,TraceContextHolderTest,RuntimePlatformSyncServiceTest,ChaosIntegrationTest \
-Dsurefire.failIfNoSpecifiedTests=false test使用 diagnostic-runbook.json 为四类症状填写
snapshot、metric、trace 与下一条假设。
实验验收卡
| 字段 | 内容 |
|---|---|
| 运行命令 | 上述 Runtime/metrics/trace/chaos 聚焦测试；书籍资产测试 |
| 输入或故障 | 陈旧副本、消息丢失、repair、overflow、trace context |
| 可观察结果 | 当前状态、结果趋势和单次链路能互相印证但不互相替代 |
| 证据等级 | E2 观察面实现 + E3 受控多节点 trace/chaos |
| 本实验未证明 | 指标后端容量、告警阈值、生产 trace 采样率或值班流程有效 |
回顾
- Diagnostics 回答当前快照，metrics 回答趋势，trace 回答单次路径。
- 排障从 identity/locator/reason 开始，不从重启开始。
- 指标使用低基数 outcome/reason，具体 key 留给日志和 trace。
- 观察一致不等于业务事实正确。
下一步
第 20 章让每条远端消息在进入 sync/collection route 前经过准入、验签、解密、防重放和限流。