> ## Documentation Index
> Fetch the complete documentation index at: https://test-8ad8522e-feat-ai-sre.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Issue 概览与详情

> 了解 Flashduty RUM 如何将相似错误聚合为 Issue，并查看发生记录、堆栈、影响用户和关联上下文。

错误上报后可在异常追踪模块查看 Issue。在 Flashduty RUM 中，一个 Issue 是由一组相似错误组成的，这些错误通常与同一个 bug 相关。

<Frame>
  <img src="https://docs-cdn.flashcat.cloud/imges/png/7eaffcd3d631d03ffb553f8956ff94ac.png" alt="Issue 列表" />
</Frame>

<Info>
  详细的聚合规则请参阅 [异常聚合](./error-aggregation)。
</Info>

## Issue 信息概览

<Frame>
  <img src="https://docs-cdn.flashcat.cloud/imges/png/5fb33aa6b0283515ca9f2427ae4aff27.png" alt="Issue 信息概览" />
</Frame>

Issue 浏览器中列出的每个条目包含以下信息：

| 信息项         | 描述                                                                        |
| ----------- | ------------------------------------------------------------------------- |
| 错误类型和错误消息   | Issue 的核心标识信息                                                             |
| 错误发生的文件路径   | 定位错误来源                                                                    |
| 服务名称        | 关联的服务                                                                     |
| 错误原因        | 系统推断的可能根因                                                                 |
| 优先级         | Issue 的优先级（`Critical`、`Warning`、`Info`），由告警分级规则或系统评分自动判定，历史数据可能为空并显示为 `—` |
| 问题是否有复现     | 标识已解决问题是否再次出现                                                             |
| 首次和最后出现时间   | Issue 生命周期信息                                                              |
| 发生次数图表      | 随时间变化的趋势                                                                  |
| 所选时间段内的发生次数 | 统计数据                                                                      |

<Note>
  Issue 列表支持按**优先级**排序，筛选条件默认包含「优先级」；每条 Issue 错误消息左侧的竖条颜色反映其优先级（`Critical` 为红色、`Warning` 为橙色、`Info` 为浅橙色，无优先级数据时为灰色）。优先级由告警分级规则或系统评分判定，不可手工修改；进入 Issue 详情页同样可在头部看到该优先级。
</Note>

## Issue 状态

Issue 有 4 种状态，流转方式如下：

<Frame>
  <img src="https://docs-cdn.flashcat.cloud/imges/png/d81cfab46793c24b044c8d87ef30402b.png" alt="Issue 状态流转" />
</Frame>

| 状态      | 说明          |
| ------- | ----------- |
| **待处理** | 新发现的问题，需要关注 |
| **处理中** | 已确认并正在修复的问题 |
| **已解决** | 问题已修复       |
| **已忽略** | 无需处理的问题     |

<Tip>
  问题复现相关流转逻辑请参阅 [Issue 状态](./issue-status)。
</Tip>

## 筛选与排序

<Tabs>
  <Tab title="时间范围">
    浏览器右上角显示时间轴，允许您显示在选定时间段内发生错误的 Issue。您可以：

    * 从下拉菜单中选择预设范围
    * 直接修改时间
    * 输入自然语言进行筛选
  </Tab>

  <Tab title="排序方式">
    | 排序选项  | 说明                  |
    | ----- | ------------------- |
    | 更新时间  | 根据问题更新时间排序（默认）      |
    | 创建时间  | 根据首次发现时间排序          |
    | 发生次数  | 根据所选时间范围内错误的总发生次数排序 |
    | 影响会话数 | 根据受影响的 RUM 会话数量排序   |
  </Tab>

  <Tab title="筛选器">
    Flashduty RUM 自动为您的 Issue 建立预定义的属性索引，并创建对应的筛选器。

    <Frame>
      <img src="https://docs-cdn.flashcat.cloud/imges/png/718ff0527731fd89465a3a7e0fb7c7ea.png" alt="筛选器" />
    </Frame>

    支持的属性包括：

    | 属性      | 描述                                 |
    | ------- | ---------------------------------- |
    | 错误原因    | 错误发生时可能的根因类型                       |
    | 环境      | Issue 上报时的 env 字段                  |
    | 服务      | Issue 上报时的 service 字段              |
    | 错误类型    | 上报的 error 事件中的 error.type 字段       |
    | 错误信息    | error 事件中的 error.message 字段，支持模糊匹配 |
    | IssueID | Issue 聚合时的 ID，多个 ID 之间可用逗号分割       |
    | 问题复现    | 已解决的问题如果再次发生，则 Issue 会被标记为复现       |
    | 指纹      | Issue 聚合时的指纹信息，多个指纹之间可用逗号分割        |
  </Tab>
</Tabs>

## 导出 Issue

Issue 列表右上角提供 **CSV** 导出按钮，导出内容与当前列表的筛选、排序条件保持一致。

点击 CSV 按钮后，可在弹层中选择导出内容：

| 选项         | 默认值 | 说明                                                                   |
| ---------- | --- | -------------------------------------------------------------------- |
| 包含错误样例     | 开   | 每条 Issue 附上最近一次上报的错误样例列（发生时间、版本、页面、会话 ID、设备、系统、浏览器、堆栈），前缀为 `sample_` |
| 同时包含最早一次样例 | 关   | 额外附上最早一次上报的错误样例列（`sample_first_*`），用于追查问题首次出现的版本；仅在「包含错误样例」开启时可勾选    |

<Note>
  错误样例只在错误数据保留期内存在，更早的 Issue 导出后样例列会为空。
</Note>

导出文件始终包含 Issue 的 18 个字段（问题 ID、问题链接、应用、服务、错误类型、错误信息、状态、优先级、是否崩溃、错误数、影响会话数、首次出现、首次出现版本、最近出现、最近出现版本、涉及版本、疑似原因、解决时间），样例列在「包含错误样例」开启后附加。

<Warning>
  * 单次最多导出 **100 条**。匹配数量超过 100 时，按钮上方会提示「最多可导出 100 条，请缩小时间范围或增加筛选条件」；导出完成后若文件被截断，页面会再次提示已导出的条数。
  * 时间列（首次出现 / 最近出现 / 解决时间 / 样例发生时间）的列头会附加时区标识（如 `首次出现 (Asia/Shanghai)`），列内值为该时区下的 `YYYY-MM-DD HH:mm:ss` 文本，便于电子表格按日期排序。
  * 样例堆栈截取前 20 行。完整堆栈可在 Issue 详情页查看（那里会按平台做符号化还原）；导出不做符号化，给出的是上报的原始帧。
  * 为防止公式注入，以 `=`、`+`、`-`、`@` 开头的单元格会被加上引号前缀。
</Warning>

## 错误原因分类

Flashcat 在每次创建 Issue 时会为其添加错误发生可能产生的错误原因分类，帮助提升故障定位的效率。

| 错误原因     | 说明                        |
| -------- | ------------------------- |
| 代码错误     | 由代码缺陷导致的错误                |
| 非法对象访问   | 代码访问了 null 或 undefined 对象 |
| 无效参数     | 使用无效参数调用函数                |
| 网络错误     | 服务器响应时间过长或网络速度慢           |
| API 请求失败 | API 端点返回了错误状态码            |
| 未知错误     | 无法定位该错误类型                 |

<Tip>
  当鼠标在错误原因分类上 hover 时，系统会结合 AI 能力进一步给出推断的根因和修复建议。
</Tip>

### 分类原理

系统采用两层分析机制对错误进行分类：

**第一层：模式匹配**

系统首先通过规则引擎按优先级依次检查错误类型和错误消息，首个匹配的规则决定分类结果：

| 检查顺序 | 匹配条件                                                               | 分类结果     |
| ---- | ------------------------------------------------------------------ | -------- |
| 1    | 错误消息包含 "Unexpected token ... is not valid JSON"                    | 无效参数     |
| 2    | 关联资源的 HTTP 状态码为 4xx 或 5xx                                          | API 请求失败 |
| 3    | 错误类型包含 "Network" 或 "AbortError"                                    | 网络错误     |
| 4    | 错误类型包含 "Syntax"、"Reference"、"Range"、"URI" 或 "Eval"                 | 代码错误     |
| 5    | 错误类型为 TypeError 且消息匹配空值访问模式（如 "Cannot read property of undefined"） | 非法对象访问   |
| 6    | 错误消息匹配无效参数模式（如 "invalid argument"、"unexpected token"）              | 无效参数     |
| 7    | 错误消息包含 "API ERROR:" 或许可证相关错误                                       | API 请求失败 |
| 8    | 错误消息包含网络连接相关关键词（如 "timeout"、"connection"、"dns"）                    | 网络错误     |
| 9    | 以上均未匹配                                                             | 未知错误     |

**第二层：AI 推断**

当模式匹配结果为「未知错误」时，系统会调用 AI 模型进行深度分析。AI 模型会结合以下信息进行判断：

* **错误消息**：错误的描述文本
* **堆栈信息**：完整的调用堆栈
* **平台类型**：浏览器/JavaScript、Android/Kotlin/Java、iOS/Swift/Objective-C、微信小程序等

AI 会输出错误分类和简要的原因解释（不超过 100 字）。推断结果在 Issue 卡片上以 hover 提示的形式展示，帮助您快速理解错误的根因。

## 问题复现

问题复现（Regression）指的是之前修复的 bug 再次出现。

<Frame>
  <img src="https://docs-cdn.flashcat.cloud/imges/png/489e8b51c598fc2ef0a248508dd546d6.png" alt="问题复现" />
</Frame>

<Warning>
  如果一个错误被标记为已解决，但在后续（version 不同）又产生了相同的错误，则该 Issue 的状态会从结束态重新打开，并标记为「问题复现」。
</Warning>

## Issue 详情

Issue 列表支持两种查看模式：侧栏模式和全屏模式。默认以侧栏方式打开详情面板，您也可以点击展开按钮切换到全屏模式，获得更宽敞的查看空间和更完整的数据展示。

点击任何 Issue 可以打开详情面板，查看更多信息。

<Frame>
  <img src="https://docs-cdn.flashcat.cloud/imges/png/964b9102aca07b4e68b569acf1d99891.png" alt="Issue 详情" />
</Frame>

<AccordionGroup>
  <Accordion title="基础信息">
    面板上部显示 Issue 的基础信息，如状态、错误原因等。您还可了解 Issue 的生命周期：首次和最后出现日期、持续时间，以及时间内的错误发生次数（按照一定时间粒度聚合）。
  </Accordion>

  <Accordion title="标签分布">
    在标签分布区块可按照各种维度查看该 Issue 下不同标签所占比重，从而快速判断问题影响范围，辅助定位根因。

    目前支持 `view_name`、`browser_name`、`version`、`env` 等标签。
  </Accordion>

  <Accordion title="错误样例">
    默认展示当前 Issue 发生期间最近一次上报的错误信息作为错误样例，您也可通过导航条进行切换。

    对于 Native 崩溃，样例导航列表中的每条样例都会标注符号化状态（「已解析」/「未解析」徽标）。当最新一条样例尚未解析、而更早的样例可以符号化时，详情会自动切换到可符号化的样例，并提示「已自动切换到可符号化的样例（最新一条尚未解析）」；点击「回到最新」可切回最新上报的样例。自动切换最多尝试 5 条更早的样例，若这些样例均无法符号化，详情会切回最新一条样例，不再继续自动切换。
  </Accordion>

  <Accordion title="错误堆栈与源码映射">
    查看错误的上下文信息和堆栈信息。如果已上传对应的 SourceMap、Android mapping 文件、iOS dSYM 文件或 Flutter 符号文件，您可以看到映射还原后的原始源码位置和代码片段。

    <Frame>
      <img src="https://docs-cdn.flashcat.cloud/imges/png/551f3fdc7eef25ac2888f71db87b9f69.png" alt="错误堆栈" />
    </Frame>

    在「应用管理」-「源码管理」可查看已上传的源码信息，详见 [源码映射](./source-mapping)。
  </Accordion>

  <Accordion title="错误堆栈（Native — Android/iOS）">
    Native 平台（Android/iOS）的错误堆栈展示针对移动端特点进行了专门设计，提供以下能力：

    **Pretty / Raw 模式切换**

    * **Pretty 模式**：结构化展示堆栈信息，自动区分应用帧（app frames）和第三方帧（third-party frames），第三方帧默认折叠，突出显示您自己的代码
    * **Raw 模式**：展示原始堆栈文本，方便复制和在外部工具中分析

    **符号化状态**

    如果已上传对应版本的符号文件（Android mapping 或 iOS dSYM），堆栈中的混淆地址会被自动还原为可读的函数名、文件名和行号。未符号化时，系统会提示您上传符号文件，并提供直达「源码管理」和上传工具的链接。

    符号化结果会被缓存。如果为一条已经出现过的崩溃补传了符号文件，点击提示条或「本条崩溃所需符号」区块中的「重新解析」按钮，即可跳过缓存强制重新执行符号化（重新拉取 dSYM 并完整还原），并刷新当前堆栈，无需等待新的崩溃上报。

    **线程堆栈（Threads）**

    Native 崩溃通常涉及多个线程。线程面板展示崩溃时所有线程的堆栈信息，支持：

    * 查看线程总数和当前展示的线程数
    * 展开/折叠所有线程
    * 每个线程内独立区分应用帧和第三方帧，第三方帧可按需展开查看
    * 崩溃线程的堆栈会被优先展示

    **Binary Images（iOS）**

    对于 iOS 崩溃，还可以查看崩溃时加载的 Binary Images（二进制镜像）列表，包含镜像名称、地址范围和 UUID 等信息，用于辅助离线符号化分析。

    **本条崩溃所需符号（非系统库）**

    当崩溃事件携带非系统二进制镜像时（iOS、Electron 等通过二进制镜像还原地址的 Native 崩溃，含 Flutter 的 iOS 原生崩溃），堆栈上方会展示「本条崩溃所需符号（非系统库）」区块，列出本条崩溃引用的所有非系统二进制镜像及其符号化状态：

    * 区块标题汇总为「已解析数/总数 已解析」；全部已解析时默认折叠为一行摘要，存在未解析镜像时默认展开
    * 每个镜像一行，展示镜像名称、UUID 以及「已解析」/「未解析」徽标，并提供复制 UUID 的按钮
    * 点击「在符号表中查找」跳转到「源码映射」页面，并按该镜像的 UUID 预筛选符号表
    * 未解析的镜像提供「去上传」链接，直达「源码映射」页面的上传入口
    * 未解析时也可以点击区块中的「重新解析」按钮，强制重新符号化并刷新堆栈

    **Flutter 支持**

    Flutter 原生崩溃（`source_type` 为 `ndk`、`android` 或 `ios`）携带线程堆栈和 Binary Images，与 Android/iOS 原生崩溃一样使用上述 Native 渲染展示；Dart 异常则按堆栈中的 build\_id 匹配已上传的 Flutter 符号文件，进行符号化还原。

    **React Native 支持**

    React Native 与 Flutter 的形态一致：JS 错误按 Web 堆栈展示，并以上传的 JS sourcemap 还原原始源码；原生崩溃（`source_type` 为 `ios`、`android` 或 `ndk`）携带线程堆栈和 Binary Images，按上述 Native 堆栈视图展示，与 Android/iOS 原生崩溃一样通过 dSYM / NDK 符号文件还原。JS 错误的 sourcemap 匹配范围为 `react-native` 类型，并按错误的 OS（`os_name`）推算平台（iOS / Android）进一步收窄——两端 bundle 可能同名，平台收窄可以避免匹配到另一端的文件。

    **Electron 支持**

    Electron 错误按类型分流展示：主进程和渲染进程的 JavaScript 错误是 V8 堆栈，与浏览器错误一样按 Web 堆栈展示（上传 sourcemap 后还原原始源码）；minidump 原生崩溃则是地址形式的 Native 堆栈（含线程与 binary\_images），按上述 Native 堆栈视图展示，上传匹配的 Breakpad 符号后还原函数名、文件名和行号。详见 [Electron 错误符号化](../sdk/electron/error-symbolication)。

    详细的符号文件上传流程请参阅 [源码映射](./source-mapping)。
  </Accordion>

  <Accordion title="会话时间线">
    查看当前错误示例所属的 Session 事件总数，以及该异常发生前后用户的资源访问情况和操作情况。

    <Note>
      当前最多展示包含当前 Error 事件在内的 20 条上下文信息，后续您可在 Session 查看器模块查看更多日志信息。
    </Note>

    <Tip>
      如果该会话已采集了回放数据，您可以直接点击「查看回放」按钮跳转到会话重放页面，从用户视角重现错误发生时的完整操作路径。
    </Tip>
  </Accordion>

  <Accordion title="属性">
    异常事件在上报时会携带一系列属性，您可在属性区块查看当前的 Session、视图、用户等各类信息，方便排查问题。

    Electron 错误的属性面板会在 Other 属性组额外展示一个虚拟 `process` 属性（主进程 / 渲染进程），标识错误来自哪个运行时；非 Electron 错误不展示该属性。
  </Accordion>
</AccordionGroup>

## 异常告警

在问题发生时立即发现它，让您有机会在问题变得严重之前主动识别和修复它。

<Frame>
  <img src="https://docs-cdn.flashcat.cloud/imges/png/eebe04d7a964b0dfaafd87daa9b6a345.png" alt="异常告警配置" />
</Frame>

<Steps>
  <Step title="进入应用管理">
    选中应用卡片后进行编辑
  </Step>

  <Step title="开启告警">
    打开「告警」开关
  </Step>

  <Step title="选择协作空间">
    选择通知的协作空间
  </Step>
</Steps>

<Info>
  具体告警配置说明请参阅 [Issue 告警](./issue-alerts)。
</Info>

## 最佳实践

<CardGroup cols={2}>
  <Card title="配置源码映射" icon="code">
    便于在生产环境定位问题
  </Card>

  <Card title="添加用户信息" icon="user">
    配置用户相关信息，提供更好的错误上下文
  </Card>

  <Card title="设置告警策略" icon="bell">
    为错误配置合理的协作空间和分派策略
  </Card>

  <Card title="定期错误分析" icon="chart-line">
    定期检查错误报告，发现潜在问题
  </Card>

  <Card title="团队协作" icon="users">
    利用团队所有权功能确保问题能够快速分配给相关团队
  </Card>

  <Card title="监控回归" icon="rotate">
    密切关注已解决问题的潜在回归
  </Card>
</CardGroup>

## 下一步

<CardGroup cols={3}>
  <Card title="源码映射" icon="code" href="./source-mapping">
    配置源码映射
  </Card>

  <Card title="异常聚合" icon="layer-group" href="./error-aggregation">
    了解聚合机制
  </Card>

  <Card title="Issue 状态" icon="circle-check" href="./issue-status">
    管理 Issue 状态
  </Card>
</CardGroup>