6.2 调试与可观测性

6.2 调试与可观测性

本节摘要：flatMap 十层变换后堆栈只剩 MonoFlatMap 抽象类名——时间不可见性是调试鸿沟。Reactor checkpoint、log()、Micrometer 与逐步完善的 OpenTelemetry 集成是主要武器。

本节导航

1. 使用 log() 与 checkpoint("标签") 定位断点
2. 列举 Micrometer 中 reactor.flow.duration 类指标
3. 说明 SOURCE 提到的 OTel 对 span 边界难点

一、链内诊断

return flux
    .checkpoint("after-parse", true)
    .flatMap(this::rpc)
    .doOnEach(signal -> log.debug("signal {}", signal))
    .log("user-pipeline");
​

• checkpoint：在组装异常中注入可读位置（有性能成本，生产慎用深链）
• doOnEach：观察 onNext/onError/onComplete 完整信号
• Hooks.onOperatorDebug：开发期全局装配追踪（勿长期开生产）

响应式调试的难点本质是**「执行栈」在订阅时刻就断掉了**：flatMap 链在 subscribe() 之前只是一张组装图，运行时错误发生后，堆栈只能回溯到当前算子，看不到「这张流图是谁搭的」。checkpoint("标签") 在组装时记录位置，错误发生时把标签附加进异常堆栈——相当于在流水线上每道工序钉一块名牌，坏在哪一工序一眼可见。

// checkpoint 的效果：异常堆栈中出现可读标签
reactor.core.Exceptions$ReactiveException: ...
	Assembly trace from producer [reactor.core.publisher.FluxFlatMap] :
		Flux.flatMap ⇢ at com.example.UserService.load(loadUsers.java:42)
	Error has been observed at the following site(s):
		*__checkpoint ⇢ after-parse
​

log() 则是「信号级监视器」：它订阅源并在每个信号到达时打日志，显示 onSubscribe/request/onNext/onComplete 与当前线程。对比 doOnEach——log() 偏「打印全部信号」，doOnEach 偏「程序化处理每个信号」——前者调试用，后者做埋点/审计用。

二、指标与追踪

Micrometer + Prometheus 可采集 Reactor 流 duration、活跃订阅数。SOURCE 挑战：OpenTelemetry 对 Mono/Flux 的 span 起止难与业务语义对齐——需在 flatMap 边界手动 span 命名。

// Micrometer 采集流指标
Flux<T> instrumented = Flux.just("a", "b")
    .name("user.pipeline")                    // 命名
    .tag("env", "prod")
    .metrics();                               // 挂上 Micrometer 指标

// Reactor 自动暴露的指标（Micrometer 维度）
// reactor_user_pipeline_subscribed_total
// reactor_user_pipeline_flow_duration_seconds
// reactor_user_pipeline_on_next_delay_seconds
​

响应式系统的指标与传统系统有一个关键差异：「在途量」与「背压水位」比平均延迟更重要。on_next_delay 反映元素在算子间滞留的时间——它突然变大，说明下游处理不过来、上游还在推，即背压堆积的开始。因此监控响应式系统，要看流级指标（每个命名流的 duration、request、cancel），而不只是 JVM 全局指标。

OpenTelemetry 对响应式的支持仍在完善：问题在于 Mono/Flux 的「异步完成」没有显式的 span 边界，OTel 无法自动知道一段流处理何时开始、何时结束。SOURCE 建议在 flatMap 边界手动创建命名 span——把业务语义（如「读取用户画像」「调用评分服务」）标进追踪，而不是依赖框架自动推断。规范对齐（第 3 章）不等于可观测性就绪，追踪边界需要人工设计。

三、IDE 与未来

IntelliJ Reactor 插件可部分可视化流生命周期。SOURCE 展望 流图级可观测性：运行时暴露拓扑、背压水位与「时间旅行」回放——尚未成为默认开箱能力。

可观测性检查清单

四、日志、指标、追踪的协同

可观测性的三个支柱在响应式世界里各有侧重：

三者不是替代关系而是互补：指标告诉你「某段延迟突增」，日志告诉你「具体是哪条流」，追踪告诉你「这次请求的路由」。响应式系统的排障流程通常是：指标发现异常 → 追踪定位链路 → 日志定位算子 → checkpoint 确认边界。

// 一个可观测的响应式链完整示例
public Flux<Event> process(Flux<Event> input) {
    return input
        .name("event.pipeline")                        // 指标命名
        .metrics()                                     // 暴露 Micrometer
        .checkpoint("event.process", true)             // 组装追踪
        .doOnEach(sig -> log.debug("sig={}", sig))     // 信号日志
        .flatMap(this::enrich)                         // 业务处理
        .doOnError(e -> log.error("pipeline error", e));
}
​

这条链同时具备三层可观测性：metrics() 让运维看到吞吐与延迟分布，checkpoint 让错误堆栈带上可读的组装位置，doOnEach/doOnError 输出信号级日志。「可观测」不是加一个日志就完事，而是让问题在三个维度都能被定位。

流图级可观测性的挑战

SOURCE 展望的「流图级可观测性」之所以尚未成为默认能力，有三个技术难点：

1. 组装与执行分离：subscribe() 之前流只是图，运行时才执行——观测要横跨这两个阶段；
2. 无显式时间边界：每个算子的处理时长无法自动切分，只能靠手动埋点；
3. 背压水位难观测：队列内部的实时水位缺乏标准暴露接口。

理解这些难点，你就明白为什么 OTel 集成「逐步完善」而不是「开箱即用」——响应式的时间不可见性是结构性困难，不是实现疏漏。工程上可行的应对是：在关键边界主动埋点（name().metrics() + 手动 span），把不可见变成可见。

本章回顾

• 异步调试靠信号日志 + 检查点，不靠单步断点 alone
• 指标需关联负载模型（SOURCE 反对无上下文的 P99）
• 追踪要在算子边界显式命名 span

一句话总结：响应式可观测性 = checkpoint 定位 + log 看信号 + 流指标看水位 + 追踪看因果——四件套齐备，生产事故才从「猜」变成「查」。