> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flashcat.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# 异常聚合

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

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

## 聚合流程

<Steps>
  <Step title="指纹匹配">
    获取错误事件的指纹，并与现有 Issue 的指纹比较
  </Step>

  <Step title="自动合并">
    如果新事件与现有某个 Issue 共享相同指纹，则自动归入该 Issue
  </Step>

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

## 默认指纹

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

<Tabs>
  <Tab title="集成 SDK">
    在 HTML 文件中引入 Flashduty Browser SDK：

    ```html theme={null}
    <script src="https://cdn.flashcat.com/rum-browser-sdk.js"></script>
    ```
  </Tab>

  <Tab title="初始化 SDK">
    初始化 SDK 时，指定应用 ID 和环境：

    ```javascript theme={null}
    window.FLASHCAT_RUM.init({
      applicationId: "rum-application-id",
      environment: "production",
      version: "1.0.0",
    });
    ```
  </Tab>
</Tabs>

### 指纹计算规则

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

| 属性              | 说明      |
| --------------- | ------- |
| `service`       | 错误发生的服务 |
| `env`           | 错误发生的环境 |
| `error.type`    | 错误的类型分类 |
| `error.message` | 错误的描述文本 |

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

## 自定义指纹

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

<Warning>
  自定义指纹的优先级高于默认指纹。
</Warning>

<Tabs>
  <Tab title="手动添加指纹">
    在手动报告错误时，通过 `addError` 添加自定义指纹：

    ```javascript theme={null}
    window.FLASHCAT_RUM.addError(new Error("My error message"), {
      source: "custom",
      fingerprint: "my-custom-grouping-fingerprint",
    });
    ```
  </Tab>

  <Tab title="使用 beforeSend 回调">
    通过 `beforeSend` 回调动态设置指纹：

    ```javascript theme={null}
    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;
      },
    });
    ```
  </Tab>
</Tabs>

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

## Web 特定注意事项

<AccordionGroup>
  <Accordion title="SourceMap 集成">
    上传 `sourcemap` 文件以解码压缩后的堆栈跟踪，确保聚合后的错误堆栈可映射到原始源代码。

    ```bash theme={null}
    flashcat-cli sourcemaps upload \
      --service my-service \
      --release-version 1.0.0 \
      --minified-path-prefix /assets \
      --api-key your-api-key \
      ./dist
    ```
  </Accordion>

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

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

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

## 查看聚合结果

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

每个 Issue 包含：

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

## 下一步

<Card title="Issue 状态" icon="circle-check" href="./issue-status">
  了解 Issue 状态流转机制
</Card>