Maafw Sentry Analysis

MaaFramework Sentry 遥测数据分析指南

本指南指导 AI Agent 如何调用 tools.sentry.cli 分析 MaaFramework（MaaFW）应用在生产环境中的任务失败率、跨版本走势及异常回归。

[!NOTE] 运行本工具依赖新一代 Sentry CLI（cli.sentry.dev，命令名为 sentry，可通过 pnpm add -g sentry 安装并通过 sentry auth 登录）。若未安装，先提示用户安装认证。

快速决策树（Scenario $\rightarrow$ Command）

核心命令与常用参数

统一通过 Python 模块入口运行：uv run python -m tools.sentry.cli <子命令>。

1. task-trend（跨版本趋势与环比对比）

• --versions N：对比最近 N 个版本（默认 3）。
• --sort {runs,rate,delta,name}：
  • rate：按最新版本失败率降序排列（找高危任务）；
  • delta：按环比恶化幅度降序排列（找回归任务，+12.7pp > +1.0pp > -2.0pp）；
  • runs：按运行量降序（默认）；
  • name：按任务名字典序。
• --limit N：限制输出行数（强烈建议配合 --sort 使用，如 --limit 10，避免大表溢出屏幕）。
• --reverse：反转排序（如排查稳定性最高或改善最明显的任务）。
• --task <任务名>：穿透查询单个任务（支持模糊匹配）。
• --include-beta：在版本序列中包含 beta / rc 测试版（默认仅对比正式稳定版）。

2. task-failure（单版本深度体检）

• --sort {failures,rate,total,name}：
  • rate：按失败率降序排列；
  • failures：按失败绝对次数降序排列（默认）；
  • total：按总运行次数降序；
  • name：按任务名排序。
• --limit N：同时限制「任务表」与「失败节点标记表」的最大展示行数。
• --release <release字符串>：手动指定特定 release（未指定时自动通过 Sentry API 探索最新版本）。

数据解读与统计口径

1. 唯一 Trace 去重： 所有样本按 count_unique(trace) 聚合，一次管线运行内部多次触发同一事件不会被重复计数。
2. 环比百分点（Δpp）：
   • 格式形如 21.6% (+12.7pp)：表示该版本失败率为 21.6%，相较于上一版本上升了 12.7 个百分点（恶化）；
   • 格式形如 3.9% (-2.0pp)：表示相较于上一版本下降了 2.0 个百分点（优化改善）；
   • 0.0pp：表现持平。
3. 任务 vs 失败节点标记：
   • 顶层任务：具有成功（ok）样本或实际业务任务名，展示 总次数 / 失败 / 取消 / 失败率；
   • 失败节点标记：内部节点或系统事件（如 控制器初始化失败、连接失败、ReturnMain），仅在失败时上报，不具备成功样本，因此仅计触发次数，不参与失败率计算。

配置文件规范 (tools/sentry/config.json)

工具从同级目录下的 config.json 加载配置，若文件不存在或缺少必填字段会直接抛出异常：

{
    "target": "m9a/gui",
    "project_prefix": "m9a",
    "release_pattern": null,
    "task_run_spans": [
        "mfa.task_run",
        "mxu.task_run"
    ],
    "ignored_prefixes": ["__MXU"],
    "ignored_suffixes": [".task_run"]
}

当协助用户将本工具迁移到其他 MaaFW 项目（如 MaaEnd、MAA 等）时，只需告知用户修改上述 JSON 即可，无需改动任何 Python 源码。