异常聚合

了解 Flashduty RUM 的异常聚合机制，提高 Issue 定位效率。

当新错误事件发生时，Flashduty 采用三步聚合策略将错误聚合为 Issue，有效减少需要处理的错误数量。

​

聚合流程

1. 指纹匹配

   获取错误事件的指纹，并与现有 Issue 的指纹比较

2. 自动合并

   如果新事件与现有某个 Issue 共享相同指纹，则自动归入该 Issue

3. 相似度分析

   如果指纹未匹配，则利用机器学习模型分析错误相似度，将事件归入相似度最高的 Issue，或在相似度过低时创建新的 Issue。

   Android NDK 原生崩溃例外： NDK 原生崩溃（source_type 含 ndk 或堆栈中存在应用层原生帧）会跳过此步骤的机器学习相似度分析，完全依赖步骤一的确定性指纹进行聚合。这是因为 NDK 崩溃的错误消息（如 signal: SIGSEGV）几乎完全相同，若走相似度分析会将来自不同代码位置的崩溃错误地合并为同一 Issue；而帧感知指纹能够精确区分不同的崩溃点。

​

默认指纹

Flashduty 默认启用异常聚合，无需额外配置即可开始工作。Browser SDK 会自动收集错误数据并进行聚合。

集成 SDK

在 HTML 文件中引入 Flashduty Browser SDK：

<script src="https://cdn.flashcat.com/rum-browser-sdk.js"></script>

初始化 SDK

初始化 SDK 时，指定应用 ID 和环境：

window.FLASHCAT_RUM.init({
  applicationId: "rum-application-id",
  environment: "production",
  version: "1.0.0",
});

​

指纹计算规则

当错误事件没有携带指纹时，Flashduty 基于以下错误属性自动计算指纹：

属性	说明
service	错误发生的服务
env	错误发生的环境
error.type	错误的类型分类
error.message	错误的描述文本。对于 Android NDK 原生崩溃，此分量会附加堆栈中最顶层的应用层原生帧信息，格式为 <message>|native:<library>:<symbol+offset>（例如 signal: SIGSEGV|native:libmyapp.so:crash_func+48）。系统库帧（libc.so、libart.so 等）和伪映射（[vdso]、[stack]）会被跳过，以确保同一崩溃位置在不同运行时始终产生相同指纹。

为提高聚合准确性，Flashduty 会去除堆栈帧中的变量属性，如版本号、ID、日期等动态参数。

​

自定义指纹

若默认聚合无法满足需求，您可以通过提供自定义指纹（fingerprint）完全控制错误的聚合行为。

自定义指纹的优先级高于默认指纹。

手动添加指纹

在手动报告错误时，通过 addError 添加自定义指纹：

window.FLASHCAT_RUM.addError(new Error("My error message"), {
  source: "custom",
  fingerprint: "my-custom-grouping-fingerprint",
});

使用 beforeSend 回调

通过 beforeSend 回调动态设置指纹：

window.FLASHCAT_RUM.init({
  applicationId: "rum-application-id",
  environment: "production",
  beforeSend: (event) => {
    if (event.type === "error") {
      event.error.fingerprint = "my-custom-grouping-fingerprint";
    }
    return true;
  },
});

• 自定义 fingerprint 必须为字符串类型
• 相同服务中具有相同 fingerprint 的错误将被归入同一 Issue
• 不同服务的错误即使 fingerprint 相同也会被归入不同 Issue
• beforeSend 回调还可用于过滤无关错误（如第三方脚本错误）

​

Web 特定注意事项

SourceMap 集成

上传 sourcemap 文件以解码压缩后的堆栈跟踪，确保聚合后的错误堆栈可映射到原始源代码。

flashcat-cli sourcemaps upload \
  --service my-service \
  --release-version 1.0.0 \
  --minified-path-prefix /assets \
  --api-key your-api-key \
  ./dist

第三方脚本错误过滤

默认情况下，Flashduty 会过滤来自浏览器扩展或第三方脚本的错误（如 network 来源），以减少噪声。

可通过 beforeSend 进一步自定义过滤规则：

beforeSend: (event) => {
  if (
    event.error.source === "network" &&
    event.error.message.includes("ThirdPartyScript")
  ) {
    return false; // 丢弃该错误
  }
  return true;
};

​

查看聚合结果

在 Flashduty 平台，导航至「异常追踪」，查看聚合后的 Issue 列表。

每个 Issue 包含：

内容	说明
错误消息和堆栈跟踪	若上传了 sourcemap，会显示原始源代码位置
用户会话时间线	触发错误的操作路径
元数据	浏览器类型、版本号等

​

下一步

Issue 状态

了解 Issue 状态流转机制