perf-compare 是 AutoGPT 项目用于性能工作的共享测量方法，目标是让不同智能体对速度或稳定性的调优结果可以相互比较，避免把噪声当作性能提升来报告。数据存储在 Sentry（组织 significant-gravitas，API 为 https://us.sentry.io，追踪采样率 100%），实际查询与统计由 scripts/perf_compare.py 执行，该脚本要求 Python 3.8+ 且仅使用标准库。
用途与场景 在声称某项改动使性能更快或更慢之前使用，适用于 preview 环境或合并之后。合并后可对比 dev 与 prod 的 release 与 release，检查收益是否保持；也可在不指定 --transaction 时检查改动是否导致其他事务回归。支持多种数值字段：默认 span.duration，也支持 builder 页面加载的 Web Vitals（如 measurements.lcp）、LLM token 计数（gen_ai.usage.input_tokens）以及自定义 tags。它不适用于调试单个慢请求（应直接打开 trace）或错误分诊。
认证与运行方式 脚本只从环境变量读取 SENTRY_AUTH_TOKEN，需要只读令牌，权限恰为 org:read、project:read 和 event:read，可以是用户认证令牌或具备相应读取权限的内部集成；组织级认证令牌（sntrys_...）会返回 403。缺少令牌时以退出码 5 退出。--print-queries 不需要令牌，可打印出精确的 REST URL 与 MCP 参数。脚本按 project、env、release、query 以及时间窗口（window、start/end、period）定义基线与候选两侧，两侧各自的参数覆盖共享默认值，时间统一为 UTC ISO 8601，未指定时默认最近 7 天。
数据选择原则 合并后对比建议在同一项目、同一环境下比较新旧 release，并使用等长且覆盖相同时段的时间窗口；有 release 时应始终按 release 过滤，因为旧 release 仍会持续上报事件。preview 对比建议用候选 preview 与对照 preview（改动分支所基于的 dev 提交，无改动）以相同方式部署，再施加相同负载，可同窗口并行或采用 A B B A 交错以抵消漂移；用候选 preview 对比 dev HEAD 更省事但证据较弱。也可在无 release 标签时做部署前与部署后对比，但需在报告中说明其他部署的影响。信任结果前建议先做 A/A 检查：同一选择器在两个窗口上对比自身，应得到“无可检测变化”。
数据量与统计 脚本在每侧样本数达到 --min-count（默认 200）且来自至少 --min-traces（默认 30）个独立 trace 时才给出 p50/p95 结论；p99 仅展示不判定。每侧每个事务最多采样 --sample-cap（默认 1000，上限 20000）。相关 span 只计一次，bootstrap 按整条 trace 重采样，避免少数繁忙 trace 被误判为大样本。建议每个关注事务每侧至少施加 1000 次请求，并在负载停止后等待几分钟再测量。
负载驱动 preview 后端为 https://pr-<N>-server.agpt.co，前端为 https://autogpt-pr-<N>.vercel.app。k6 测试位于 autogpt_platform/backend/load-tests/，可用 ./k6.sh 在本机以 Docker 运行，避免在 Grafana Cloud k6 上运行以免按虚拟用户小时计费。设置 K6_ENVIRONMENT=PREVIEW 和 PR_NUMBER=<N> 即可针对 preview 施压，认证测试会自动注册一次性账号。需记录运行的 UTC 时间窗口，并在两侧使用相同测试、VU 数与时长。注意 preview 数据库为空，随数据增长的成本（如 N+1 查询）不会显现，需要先通过 API 播种数据或合并后在 dev/prod 确认；k6 测试也不覆盖 copilot 对话。
结果解读 markdown 或 --json 输出会报告每个事务的 Sentry 聚合值（count、p50、p95、p99、失败率）以及基于原始样本的 bootstrap 置信区间（经 Bonferroni 校正）。判定“更快/更慢”需要校正后的区间排除零，且样本变化与 Sentry 全事件变化均达到 --min-effect（默认 5%）；否则为“无可检测变化”。失败率使用 Fisher 精确检验，并设 --min-failure-delta（默认 0.1 个百分点）。失败率上升即视为回归，即使事务变快，因为快速失败看起来像提速。一次胜利需同时满足：测量前用 --transaction 指定事务、判定为更快、失败率未上升、并在第二个独立窗口或运行中复现。
退出码 0 表示更快且无回归；1 表示更慢或失败更多；2 为用法错误或 Sentry 拒绝查询（400）；3 为无可检测变化；4 为数据不足；5 为认证问题；6 为 Sentry API 或网络等意外错误，不能读作回归。--json 模式下可依据 overall.verdict、overall.exit_code、overall.reasons 及各事务的 verdict、regression、p50/p95 区间、failure_rate、样本数、settings 等字段做判断。