Flutter RUM 监控实践：还原 AI 应用一次等待的完整现场

AI 时代，用户说“页面一直在转圈”，先别急着归因接口

在 Flutter 应用里，用户反馈“页面一直在转圈”“点击按钮后没有反应”“内容加载到一半卡住了”，研发第一反应往往是去看接口耗时、错误日志或崩溃堆栈。但线上问题很少只停留在单点：一次等待可能跨越用户操作、页面状态、网络请求、端上渲染、异常处理和原生能力调用。

如果只看某一类日志，很容易得到片面的结论：

• 只看接口日志，可能忽略端上渲染和状态更新阻塞。
• 只看 Dart 异常，可能看不到前置点击和网络请求。
• 只看页面埋点，可能无法判断用户到底卡在哪一步。
• 只看崩溃或错误，可能无法还原问题发生前的完整路径。

围绕这些问题，阿里云云监控 CMS 的 Flutter SDK 提供了面向 Flutter 应用的接入能力，并通过 alibabacloud_rum_flutter_plugin 在 Dart 层采集页面、网络、Action、LongTask、异常、资源快照和业务自定义字段等上下文，再交由原生 RUM SDK 上报和关联。这里的 RUM 指真实用户监控（Real User Monitoring）。本文将结合这些工程实现，讨论如何把一次用户等待还原成可追踪、可验证的线上现场。

要还原 AI 应用的一次等待，先把链路拆回 Flutter 各层

一个常见的 Flutter 交互链路，大致可以拆成下面几个阶段：

用户点击按钮
-> Flutter Action 识别
-> 业务状态机更新
-> 网络请求或本地任务执行
-> 响应返回
-> 页面内容刷新
-> 列表、富文本或图片渲染
-> 页面进入稳定状态

用户最终看到的可能只是“等了很久”，但研发真正需要回答的是：慢在点击前、请求前、请求中、响应后，还是端上渲染阶段。

传统排查方式很难回答这个问题，主要有几个断点。

因此，Flutter RUM 的重点不是“多采集几类 SDK 事件”，而是围绕一次真实用户体验建立可关联的时间线：

只有这些事件进入同一个 RUM Session，研发才有机会把“页面一直在转圈”拆解成几个可验证的候选方向。

线索散落在各层，先打通从 Dart 到 Native 的采集链路

Flutter 应用的可观测链路天然跨层。Dart 层知道 Widget、Route、Zone、Dio 和业务状态；Android、iOS、HarmonyOS Native SDK 更适合承接平台侧上报、网络追踪配置和最终数据落地。

从工程结构看，Flutter RUM SDK 可以分为三层：

Dart 采集层负责保留 Flutter 语义，例如 Dart Zone 异常、Route 生命周期、Widget 点击、Dio 请求和主 Isolate 阻塞；Native SDK 侧负责承接标准化事件并完成平台落地。

这种分工的价值在复杂 Flutter 场景里会更明显：Flutter 侧保留“用户做了什么、页面处于什么状态、内容如何刷新”的语义，Native 和 RUM 侧负责把这些数据放入统一的会话视角。

第一条线索从点击开始：Action 是否进入当前会话

“点击后无响应”是线上反馈里很常见的一类问题。它可能有几类原因：

• 按钮被禁用或业务状态机没有进入下一步。
• 点击触发了请求，但网络层失败或被重试。
• 请求发出后主 Isolate 被同步任务阻塞，页面没有及时刷新。
• 自动化流程或系统任务触发了重复操作，导致业务状态错乱。

排查这类问题，第一步不是直接看接口，而是确认用户行为是否进入了同一个会话。

Flutter 的用户行为不是原生 Button 点击，也不是 Web DOM 点击。一次操作首先是指针事件和坐标，SDK 需要回到 Flutter 的 HitTest、Widget、Element、RenderObject 体系里识别语义。

Action 自动识别不是仅调用 start() 就能完成，需要业务将目标组件树包裹在 AlibabaCloudActionCapture 下：

AlibabaCloudActionCapture(
  child: MaterialApp(
    navigatorObservers: [
      AlibabaCloudRUMNavigationObserver(enablePagePerf: true),
    ],
    home: HomePage(),
  ),
);

对于关键业务操作，建议不要只依赖默认控件识别，而是通过 ActionAnnotation 补充业务语义：

ActionAnnotation(
  description: 'Submit Button',
  attributes: {
    'screen': 'order_detail',
    'action': 'submit_order',
    'actor_type': 'human',
  },
  child: ElevatedButton(
    onPressed: _submitOrder,
    child: Text('Submit'),
  ),
);

如果操作来自业务自动化流程，它并不一定会产生 Flutter 可感知的标准指针事件。比如业务直接调用方法、触发后台任务或执行规则引擎时，SDK 无法仅通过 tap 识别完整语义；如果是系统无障碍或坐标模拟点击，则可能仍会表现为一次普通 tap。因此，业务最好在关键流程中主动上报 Action 或自定义事件，并补充 actor_type 等上下文。

这样分析“点击后无响应”时，RUM 看到的就不只是一次 tap，而是可以结合 Action、业务事件、后续 Resource、LongTask 和 Error，还原这次操作背后的行为主体和执行链路。

点击之后请求去了哪里：Resource 把网络接回用户现场

用户说“页面一直在加载”，不一定是接口慢。至少要拆成几个阶段：

1. 点击操作到请求发出。
2. 请求发出到响应返回。
3. 响应返回到页面完成更新。
4. 页面更新后是否进入可交互状态。

Flutter RUM SDK 在网络层提供两类入口：直接使用 dart:io 时，通过 HttpOverrides 包装全局 HttpClient；使用 Dio 时，通过 AlibabaCloudRUMDioInterceptor 接入。

final dio = Dio();
dio.interceptors.add(
  AlibabaCloudRUMDioInterceptor(
    onProvideSnapshots: (requestOptions, response, error) {
      return ResourceSnapshots(
        requestHeaders: {
          'content-type': requestOptions.headers['content-type'] ?? '',
        },
        responsePayload: response?.data is Map
            ? {
                'code': response?.data['code'],
                'requestId': response?.data['requestId'],
              }.toString()
            : null,
      );
    },
  ),
);

对 Flutter 应用来说，网络监控的价值不是记录一条请求耗时，而是把接口请求、用户操作和页面状态放回同一条体验链路里。用户说“页面一直在转圈”时，研发需要知道：请求有没有发出、接口是否超时、服务端链路是否异常、响应返回后页面是否及时更新，以及这些问题发生在哪个页面、哪个版本、哪次会话中。

在业务允许的范围内，RUM 可以帮助端上请求和服务端链路形成关联，让排障从“看一条孤立接口日志”变成“还原一次用户等待的完整路径”。同时，涉及第三方域名、敏感接口和用户输入的请求，仍需要遵循业务安全策略和数据合规要求。

仅有 Resource 耗时还不够。对于关键业务链路，建议补充一些能帮助定位的业务字段：

这些字段不是 SDK 默认承诺采集的内置字段，而是面向业务排障时建议补充的上下文。SDK 提供的是稳定的采集、上报和会话关联底座，业务语义仍需要研发结合自己的链路和合规要求进行设计。

请求已经返回，页面为何还在卡：LongTask 记录端上压力

Flutter 页面在内容刷新时，可能会触发状态更新、富文本渲染、图片加载、长列表 diff 或 JSON 解析。如果这些逻辑占用过多端上资源，用户会看到“页面一顿一顿的”，但服务端日志可能完全正常。

Flutter RUM SDK 会关注 Dart 主 Isolate 长时间无法及时响应的情况。当文本渲染、列表更新或复杂布局占用过多端上资源时，SDK 可以记录一次 LongTask 事件，并把阻塞持续时间、发生页面和用户会话等上下文放到同一条时间线上。

对研发来说，这里的重点不是理解底层检测算法，而是让“服务端已经返回内容，但端上渲染跟不上”这类问题留下证据。这样用户反馈“页面卡住了”时，就不必只在服务端或网络接口里寻找原因，也可以回到 Flutter 端上的渲染和状态更新链路里继续排查。

这类事件的价值，是把“服务端已经返回了”之后的端上体验补齐。例如同一个会话里可以看到：

Action: Submit
-> Resource: /api/order/submit 200
-> Custom: business_stage = render_result
-> LongTask: 236ms
-> LongTask: 410ms
-> View: OrderResultPage

这时研发可以形成一个候选判断：接口返回不慢，但页面刷新过程中主 Isolate 压力较高。后续再结合数据量、列表长度、富文本节点数量、设备型号和页面结构继续验证。

因此，LongTask 更适合作为用户体验排障中的一个信号：它可以提示端上渲染或状态更新可能存在压力，再结合会话时间线中的 Action、Resource、Error 和业务字段，帮助研发判断问题是否发生在端上处理阶段。比如接口已经返回，但 LongTask 集中出现在页面刷新期间，就可以优先检查列表刷新、布局计算、状态更新频率等端侧逻辑。

卡顿之后又出现异常：Error 需要回到前后事件

很多 Flutter 异常单看堆栈并不难理解，但难点在于：它为什么在这个用户、这个页面、这个操作之后发生。

例如一次状态异常，可能来自：

用户点击提交
-> 请求发出
-> 服务端返回异常结构
-> Dart 解析逻辑进入异常分支
-> Flutter 状态更新失败
-> Error 上报

如果只看异常堆栈，很难判断是参数不合法、业务接口失败、Native 能力异常，还是 Flutter 状态机处理失败。

Flutter 异常采集不能只靠一个入口。初始化过程中，SDK 会围绕异常链路处理几类路径：

• 通过 runZonedGuarded 捕获 Zone 内未处理异常。
• 接管 FlutterError.onError，处理 Flutter Framework 同步异常。
• 接管 PlatformDispatcher.instance.onError，处理平台分发层未捕获异常。
• 保留原有 handler 调用链，降低对业务已有错误处理逻辑的侵入。
• 提供 onRUMErrorCallback，让业务决定是否继续上报。
• 通过 setDumpError 控制是否继续向控制台输出 Flutter 错误。

标准场景可以直接使用 start()：

void main() {
  AlibabaCloudRUM().start(MyApp());
}

如果业务需要自己控制 runApp() 时机，也可以先执行 initialize()：

void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await AlibabaCloudRUM().initialize();
  runApp(MyApp());
}

需要注意，如果业务选择 initialize() 自行控制 runApp()，部分依赖应用启动后状态的能力需要在合适时机额外开启。例如需要 LongTask 检测时，可以在 runApp() 后按当前公开 API 调用：

await AlibabaCloudRUM().initLongTaskDetection();

对于业务排障，仅有异常还不够，建议业务补充以下语义：

这样，当 Error 出现时，它不再只是 Dart 堆栈，而是可以和前置 Action、Resource、页面状态和业务阶段放在一起分析。

线索仍然不够：用资源快照补上下文，也守住数据边界

排查接口问题时，研发往往希望看到更多上下文，例如错误码、requestId、服务端返回状态、关键参数是否缺失。但 Header 和 Payload 可能包含用户输入、鉴权信息或业务敏感字段，不能默认全量采集。

因此，SDK 采用显式 Provider 机制：

• 默认不采集任何 Header/Payload。
• 只有业务设置 ResourceSnapshotProvider 或 Dio 的 onProvideSnapshots 后才采集。
• 用户负责过滤、脱敏和合规处理。
• SDK 在 Dart 层 Provider 或 Dio 回调返回后执行大小限制：Header 按 JSON UTF-8 大小判断，超过 64KB 时丢弃；Payload 按 UTF-8 字节计算，超过 150KB 时截断。

对于关键请求，建议只保留能帮助诊断且不包含敏感内容的字段，例如：

ResourceSnapshots(
  requestHeaders: {
    'content-type': requestOptions.headers['content-type'] ?? '',
  },
  responsePayload: response?.data is Map
      ? {
          'code': response?.data['code'],
          'requestId': response?.data['requestId'],
        }.toString()
      : null,
);

资源快照用于补充排障上下文，但大小限制不能替代业务脱敏和合规审核。接入时应优先保留错误码、请求标识等最小诊断字段，避免上传用户输入或完整业务响应。

这是一种明确的设计权衡：SDK 提供采集和上报通道，但不主动读取业务 Body，避免因为监控逻辑影响业务数据流或引入合规风险。

AI 对话页何时真正可用：用 View 指标区分页面慢和任务慢

Flutter 页面通常不是一次性加载完成的静态页面。用户进入订单、支付、内容详情或工作台页面后，应用可能需要先展示页面容器，再加载接口数据、渲染列表或富文本，最后让提交、刷新、筛选等关键操作可用。因此，页面指标更适合用来回答几个业务问题：页面是否及时出现、关键内容是否可见、主要操作是否可用，以及用户能否尽快完成当前任务。

Flutter RUM SDK 通过 AlibabaCloudRUMNavigationObserver 采集标准路由场景：

MaterialApp(
  navigatorObservers: [
    AlibabaCloudRUMNavigationObserver(
      ignoreRoutes: ['/splash'],
      enablePagePerf: true,
    ),
  ],
  home: HomePage(),
);

对于 IndexedStack、PageView、Tab 容器等非标准页面结构，也可以使用手动 API：

AlibabaCloudRUM().startView('OrderDetailPage');
AlibabaCloudRUM().stopView('OrderDetailPage');

页面性能采集围绕一次 Route 生命周期展开，主要关注以下指标：

需要注意，Flutter 里的 FP、FCP、TTI 是基于 Flutter 渲染和页面结构的估算口径，和浏览器页面指标的解释方式不同；在 PlatformView、自绘组件或复杂页面容器中，业务仍需要结合页面结构校验指标解释。页面性能数据会在 View 事件退出时随扩展字段上报，最终可查询字段以 View 扩展 map 和各平台 SDK 支持情况为准。

对于复杂页面，建议把页面指标和业务阶段放在一起看。例如：

View: OrderDetailPage
-> FP / FCP / TTI
-> Action: Submit
-> Resource: /api/order/submit
-> Custom: business_stage = render_result
-> LongTask: page render

这样就能区分“页面本身打开慢”和“页面打开后业务处理慢”。

证据进入 RUM 后：让 STAROps 回答“AI 为什么一直在等”

当 RUM 数据进入平台后，排障方式不应该停留在手写查询语句上。更合理的方式是从问题意图进入，由可观测平台辅助组织分析路径。

在 CMS 2.0 的相关能力开放范围内，STAROps 可以作为这类辅助分析入口之一。这里的 CMS 2.0 指云监控新一代控制台能力体系，STAROps 指面向可观测数据的辅助分析入口；两者均按当前产品命名和开放范围使用，具体可用入口以控制台支持情况为准。

对于 Flutter 应用，可以提出的问题不再是“查询某张表”，而是更接近线上排障语言：

过去 1 小时，哪些页面等待时间异常？
点击提交按钮后无响应的会话，是否同时出现 LongTask 或慢请求？
接口错误是否集中在某个版本或某类设备？
某个版本升级后，页面 Resource 错误和 TTI 是否同时上升？

STAROps 的价值在于辅助把这些自然语言问题组织成分析路径：

1. 从现象进入。 先描述“页面一直转圈”“点击无响应”“接口失败”等问题。
2. 辅助圈定范围。 按应用版本、系统、设备、页面、地域、时间窗口等维度收敛影响面。
3. 关联会话事件。 将同一用户会话中的 Action、页面性能、Resource、Error、LongTask 和业务事件串起来。
4. 形成候选方向。 例如端上阻塞、接口慢、链路重试、页面渲染异常、资源错误集中在某个版本等。
5. 进入样本下钻。 回到具体会话、页面路径、请求链路和异常上下文，验证判断是否成立。

STAROps 的能力范围、可用入口和分析效果以当前控制台支持情况为准，分析结果也依赖底层 RUM 数据的完整性。如果页面命名不规范、Action 缺少业务语义、资源快照没有按需脱敏补充，或者链路追踪没有打通，辅助分析也只能看到局部。因此，SDK 侧的自动采集和业务侧的语义补充仍然是基础。

把排障路径落到 SDK：先从一个关键页面跑通

如果一开始就试图覆盖所有 Flutter 页面、所有网络请求和所有业务流程，接入成本和口径设计都会变复杂。更推荐的方式是先选择一个典型关键页面，跑通最小闭环。

1. 先让 RUM 跑起来

标准场景：

void main() {
  AlibabaCloudRUM().start(MyApp());
}

自定义启动流程：

void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await AlibabaCloudRUM().initialize();
  runApp(MyApp());
}

2. 再接入页面、网络和行为

• 使用 AlibabaCloudRUMNavigationObserver 或 startView/stopView 标记关键页面。
• 使用 AlibabaCloudRUMDioInterceptor 或 HttpOverrides 采集核心业务请求。
• 使用 AlibabaCloudActionCapture 和 ActionAnnotation 识别提交、刷新、返回、重试等关键操作。

3. 基础数据接入后，再补上业务语义

完成 View、Action、Resource、LongTask 和 Error 接入后，RUM 已经能够记录用户做了什么、请求是否成功、页面是否卡顿以及是否发生异常。

但这些技术事件还不能完全解释业务过程。例如，研发仍然需要知道它们属于哪一次流程、用户正在等待哪个阶段，以及这次操作最终如何结束。业务侧只需要围绕这些问题补充必要上下文：

在 AI 对话场景中，flow_id 也可以对应一次对话或任务，business_stage 可以用来区分请求模型、流式返回和页面渲染等阶段。字段名称和取值应由业务根据实际链路设计，它们不是 Flutter RUM SDK 默认提供的内置字段。

字段设计以能够解释问题为准，不需要覆盖每一次状态变化。补充这些语义后，下一步就是验证它们能否与 View、Action、Resource、LongTask 和 Error 一起出现在同一个 Session 中。

4. 最后验证一条会话是否完整

接入后，不要只看单个指标是否出现，而要验证一条用户现场是否完整：

View: OrderDetailPage
-> Action: Submit
-> Resource: /api/order/submit
-> Custom: business_stage / result_status
-> LongTask: page render
-> Error: optional

如果这条链路能在 RUM 里被串起来，再逐步扩展到更多页面、更多业务流程和更多业务语义。

回到开头：不是增加更多日志，而是还原一次等待

Flutter 应用的线上体验问题，往往不是一个接口、一段堆栈或一次点击能解释清楚的。一次“页面一直在转圈”，可能包含端上交互、网络请求、服务端处理、页面渲染、主 Isolate 阻塞和异常处理。只看服务端日志，看不到端上的页面和渲染；只看 Flutter 异常堆栈，也看不到前置 Action 和请求链路。

Flutter RUM SDK 的价值，是把这些分散事件放回同一个用户会话：用户做了什么、请求是否发出、接口是否异常、页面是否卡顿、异常是否发生在同一条路径里。这样，研发面对的就不再是一堆孤立日志，而是一个可以被追踪、关联和复盘的用户现场。

目前这套思路已经在阿里云 RUM Flutter SDK 的工程实现中落地。具体 API、字段和平台支持范围以正式发布版本和接入文档为准。后续还可以继续在复杂手势识别、LongTask 分析、业务字段标准化、资源快照合规策略和跨端字段一致性等方向持续优化。

对移动端研发来说，观测的目标不是让数据更多，而是把一次真实等待拆成可以验证的链路，让问题更快被理解。