English | 简体中文
一个 Streamlit 页面，用于分析应用资源消耗 Excel 数据：场景横向对比、趋势观察、阈值异常、内存泄漏检测、版本退化判定、资源效率、容量估算与自动测试报告。
- 约定：Excel 第一个 sheet 为系统信息（展示用），其余每个 sheet 是一个测试场景，sheet 名即场景名。
- 详细分析方法与口径说明见 docs/analysis-methodology.md。
- 代码结构说明见 docs/code-map.md。
# 1. 安装依赖
python3 -m pip install -r requirements.txt
# 2. 生成调试用示例数据（可选，已有 data/sample_resource_consumption.xlsx 可跳过）
python3 generate_sample_data.py
# 3. 启动页面
streamlit run app.py浏览器访问 http://localhost:8501。
- 没有上传 Excel 时，默认读取
data/sample_resource_consumption.xlsx；上传后以上传文件为准。 - 支持一次上传多个 Excel，文件名会作为"数据源"，用于版本对比和多批次对比。
运行测试：
python3 -m pytest tests/ -q以下截图均取自示例数据（data/sample_resource_consumption.xlsx）在"应用性能"模式下的实际页面，覆盖主要分析模块。
概览：场景数、样本数、CPU/内存峰值与告警点总数，以及各场景 CPU 统计（均值/峰值/P90/P95/P99/波动性/趋势斜率）和告警持续性摘要。
趋势：多场景指标曲线叠加，含滚动均值、P5-P95 区间带与阈值线，便于定位压力时段。
配置建议：按测试机核数、目标 CPU 利用率上限、内存与磁盘预留推导最低可运行配置和推荐配置，并给出完整推导过程。
泄漏检测：内存线性回归斜率、R2、首尾增长与疑似泄漏判定，并用柱状图对比各场景增长速率。
分布：箱线图观察场景内分布与离群点，下方为指标相关性热力图。
报告：报告章节可勾选（共 12 个章节），一键导出 Markdown / HTML / Word / PDF / ZIP。
- 轻载、重载、空闲、冷启动、长时间运行等场景的资源对比
- CPU、内存、线程、句柄、IO 的趋势观察与阈值告警
- 找峰值、P95、P99 等高水位与异常点
- 不同版本 / 构建 / 测试批次的资源压力差异与退化判定
- 基于长时间资源数据推导最低运行配置和推荐配置
- 还没有真实采集数据时，用示例数据先调试分析流程
工作簿按 sheet 拆分：
| Sheet 位置 | 含义 | 说明 |
|---|---|---|
| 第 1 个 sheet | 系统信息 | 展示用，不参与指标计算 |
| 第 2 个及之后 | 场景数据 | 每个 sheet 一个场景，sheet 名就是场景名 |
场景 sheet 会先自动识别核心表头（时间戳、CPU%、内存占用（MB）、系统总内存、内存占用百分比、线程、句柄、io），字段名支持中英文近似名称，例如 CPU%、cpu、内存占用（MB）、memory、thread、线程 都可识别；识别不到的可在侧边栏"自定义字段映射"补充别名。
在"应用性能"模式下，还会优先识别语义化扩展字段：QPS、TPS、任务数、并发数、响应时间(ms)、错误数、FPS、卡顿次数、GC次数、GC耗时(ms)、堆内存(MB)、网络上行/下行(KB/s)、请求数、失败请求数、重试次数、磁盘读/写(MB/s)、IOPS、IO等待(ms)。这些字段进入趋势、对比、效率、决策等分析；其他可转数值的列自动作为"动态扩展指标"（如 GPU%、队列长度）。
配置建议只使用 CPU、内存、线程、句柄、IO 这些语义明确的核心指标；业务字段主要用于效率、体验和稳定性判断。
| 模式 | 适用数据 | 页面特点 |
|---|---|---|
| 应用性能 | 应用资源消耗、压测、版本性能对比 | 自动识别 CPU、内存、IO、QPS、响应时间等性能语义，含配置建议、效率、决策等性能专属页面 |
| 通用时序 | 传感器、设备测量、实验记录、质量检测等通用采样数据 | 只强制识别时间戳，其余数值列都作为指标，保留概览、趋势、对比、版本对比、分布、异常和报告 |
通用时序模式沿用同一 Excel 结构；分组名称可在侧边栏配置为"设备""工况""批次""实验组"等。
推荐字段格式：
| 字段 | 类型 | 示例 | 说明 |
|---|---|---|---|
| 时间戳 | 时间 | 2026-06-13 09:00:00 |
趋势图横轴 |
| CPU% | 数值 | 36.5 |
CPU 使用率 |
| 内存占用（MB） | 数值 | 1024.8 |
应用占用内存 |
| 系统总内存 | 数值 | 16384 |
单位 MB，用于补算内存占比 |
| 内存占用百分比 | 数值 | 6.25 |
缺失时用 内存占用 / 系统总内存 补算 |
| 线程 / 句柄 | 数值 | 68 / 1200 |
线程和句柄数量 |
| io | 数值 | 3.4 |
IO 指标，单位按采集工具定义 |
| QPS / TPS | 数值 | 120.5 |
业务吞吐，用于计算单位资源成本 |
| 并发数 | 数值 | 80 |
并发用户、连接或任务数 |
| 响应时间(ms) | 数值 | 235.8 |
响应质量指标 |
| FPS / 卡顿次数 | 数值 | 58.2 / 1 |
客户端渲染体验 |
| GC次数 / GC耗时(ms) / 堆内存(MB) | 数值 | 3 / 45.6 / 512 |
运行时回收压力 |
| 网络上行/下行(KB/s) | 数值 | 120 / 860 |
网络吞吐 |
| 请求数 / 失败请求数 / 重试次数 | 数值 | 1000 / 2 / 1 |
请求稳定性 |
| 磁盘读/写(MB/s) / IOPS / IO等待(ms) | 数值 | 20.5 / 8.2 / 320 / 12 |
磁盘压力 |
| 其他数值列 | 数值 | GPU%、队列长度 |
自动作为动态扩展指标 |
| 页面 | 作用 | 关键能力 |
|---|---|---|
| 概览 | 快速判断整体情况 | 场景数、样本数、CPU/内存峰值、告警点；每场景均值/峰值/P90/P95/P99、波动性、趋势斜率、超阈次数与占比、最大连续超阈 |
| 趋势 | 按时间观察指标曲线 | 多场景叠加、阈值线、滚动均值、P5-P95 上下限区间带、阶段化分析（自动切分 预热/稳定/压力 并叠加边界） |
| 对比 | 场景横向对比 | 均值/峰值/P90/P95/P99/标准差/IQR/变异系数/趋势斜率柱状图 |
| 配置建议 | 推导运行配置 | 输入测试机核数、目标 CPU 利用率、预留内存等，输出最低可运行配置和推荐配置（CPU 核数/内存/磁盘） |
| 基准增长 | 相对基准的增长率 | 选基准场景和口径，计算各场景相对增长率并绘图 |
| 泄漏检测 | 内存泄漏与趋势风险 | 内存线性回归斜率、R2、首尾增长、疑似泄漏判定；全指标趋势斜率（CPU/线程/句柄/IO/动态指标） |
| 版本对比 | 多文件版本退化判定 | 按场景对比数据源、选统计口径、增长率阈值判定退化；Mann-Whitney U + Cohen's d 统计显著性；版本退化热力图 |
| 效率 | 资源归一化到业务负载 | CPU P95/吞吐、内存峰值/并发、失败率等；吞吐-资源散点图；分钟级归一化（分桶瞬时成本） |
| 决策 | 把指标转成测试结论 | 场景风险评级、风险矩阵、风险雷达图、发布门禁、稳定性评分、瓶颈提示、容量估算与容量曲线 |
| 分布 | 分布与相关性 | 箱线图、相关性热力图、控制图（均值/UCL/LCL） |
| 异常 | 阈值超标分析 | 异常段摘要与多指标联动图、异常时间轴、异常点明细、异常段/异常点 CSV 与交互式 HTML 下载 |
| 报告 | 自动生成测试报告 | 章节可选；Markdown / HTML / Word / PDF / ZIP 下载，PDF 为图文摘要归档版 |
| 数据质量 | 数据质量诊断 | 时间字段诊断、时间/指标质量摘要、采样突变、非数值列提示 |
| 系统信息 | 展示第一个 sheet | 应用名称、版本、测试设备、系统内存、采样间隔等（不参与计算） |
| 原始数据 | 查看字段映射后的数据 | 采样间隔摘要/分布/时间线，导出当前筛选 CSV |
| 配置 | 说明 |
|---|---|
| 数据源 | 上传一个或多个 Excel，或使用本地示例数据 |
| 导入分析配置 | 上传 JSON 配置文件，复用字段别名、阈值、告警方向和分析参数 |
| 自定义字段映射 | 为每个标准字段配置额外别名，适配不同采集工具 |
| 阈值 | 配置核心指标和动态扩展指标的告警阈值；可配置单位、缩放因子 |
| 指标方向 | 每个指标"越高越差"还是"越低越差"（如 FPS、成功率） |
| 稳定区间 | 排除每个场景开头 N 分钟，避免启动预热影响统计 |
| 筛选 | 选择分析的数据源、场景和趋势图指标 |
| 高级筛选 | 时间范围（分钟级）、指标条件（AND/OR）、分类列多选、采样降频（每 N 个点） |
| 批量导出 | 把趋势图、分布图、异常时间轴、采样间隔图打包成 ZIP（含交互式 HTML 图表） |
阈值和上下限会影响告警点、超阈次数、告警持续性、趋势图阈值线、报告和决策分析，不会修改原始数据。动态扩展指标默认阈值使用当前数据 P95。
侧边栏支持导入 / 导出 JSON 分析配置，用于复用字段映射、阈值、告警方向、分析参数、筛选条件和主要图表/决策配置。先在界面里调好参数，再点击"导出当前分析配置"，下次直接导入复用。
配置文件示例：
{
"version": 1,
"mode": "performance",
"fields": {
"cpu_percent": ["CPU使用率", "Process CPU"],
"response_time_ms": ["P95响应时间", "latency_ms"]
},
"analysis": {
"mode": "performance",
"group_label": "场景",
"memory_leak_slope_threshold": 2.0,
"warmup_minutes": 1.0,
"risk_rules": {
"alert_ratio_warning": 5.0,
"alert_ratio_critical": 20.0,
"response_ms_warning": 500.0,
"response_ms_critical": 1000.0,
"fps_warning": 45.0,
"fps_critical": 30.0,
"failure_rate_warning": 0.1,
"failure_rate_critical": 1.0,
"leak_score": 3.0,
"minor_leak_score": 1.0
}
},
"metrics": {
"cpu_percent": {
"label": "CPU",
"unit": "%",
"threshold": 80,
"direction": "higher"
},
"fps": {
"label": "FPS",
"threshold": 45,
"direction": "lower"
},
"响应时间(ms)": {
"threshold": 1000,
"direction": "higher"
}
},
"ui": {
"trend": {
"show_rolling": true,
"rolling_window": 10,
"band_mode": "配置上下限"
},
"version_compare": {
"p_threshold": 0.05,
"effect_size_threshold": 0.2
},
"filters": {
"selected_sources": ["示例数据"],
"selected_groups": ["轻载", "重载"],
"selected_trend_metrics": ["cpu_percent", "memory_mb"]
}
}
}兼容策略：
- 配置按内部指标 key 或显示名匹配（
cpu_percent、fps、响应时间(ms)）；配置里有、Excel 里没有的指标会被忽略。 - Excel 里有、配置里没有的指标继续用内置默认阈值或当前数据 P95。
- 动态扩展指标可用原始列名或内部 key
extra::原始列名匹配。 mode可填performance/generic_timeseries（对应"应用性能"/"通用时序"）。- 告警方向支持
higher/lower，也兼容越高越差/越低越差。 lower_threshold/upper_threshold为可选字段，配置后按"正常区间"判断异常并显示区间带。analysis.risk_rules为可选字段，缺失的字段用默认值（完整字段见下方参数表）。- 配置文件可用
description、notes或_comment写备注，不参与计算。
导入后侧边栏会校验配置：未知字段提示并忽略；数字字段不是数字时提示并使用默认值；direction 无法识别时提示；lower_threshold > upper_threshold 时自动交换；未命中当前 Excel 的指标提示但不阻断分析。
| 参数 | 位置 | 说明 |
|---|---|---|
fields.timestamp |
顶层 fields |
时间戳字段别名，通用时序模式至少需要命中一个时间字段 |
analysis.group_label |
analysis |
sheet 分组的名称（场景、设备、工况、批次等） |
analysis.warmup_minutes |
analysis |
排除每个分组开头 N 分钟数据 |
analysis.memory_leak_slope_threshold |
analysis |
内存疑似泄漏斜率阈值，单位 MB/分钟 |
analysis.risk_rules.* |
analysis |
决策规则阈值集（alert_ratio_* 5/20、alert_minutes_* 1/5、failure_rate_* 0.1/1.0、error_per_thousand_* 1/10、response_ms_* 500/1000、fps_* 45/30、leak_score 3、minor_leak_score 1），缺省用默认值 |
metrics.*.label / unit |
metrics |
指标展示名和单位 |
metrics.*.threshold |
metrics |
单阈值告警线；没有上下限时按它和 direction 判断异常 |
metrics.*.direction |
metrics |
higher 越高越差，lower 越低越差 |
metrics.*.lower_threshold / upper_threshold |
metrics |
正常区间上下限，配置后按区间判断异常 |
ui.trend.* |
ui.trend |
滚动均值、窗口、区间带模式等趋势页默认值 |
ui.alerts.* |
ui.alerts |
异常段联动图窗口与默认指标 |
ui.version_compare.* |
ui.version_compare |
版本对比口径、基准数据源、退化阈值、显著性 P 值（默认 0.05）与效应量（默认 0.2） |
ui.baseline_growth.* / ui.distribution.* / ui.efficiency.* |
ui.* |
基准增长、分布、效率页默认值 |
ui.decision.* / ui.capacity.* |
ui.* |
发布门禁规则与容量估算参数 |
ui.configuration_recommendation.* |
ui.* |
配置建议页 CPU、内存、磁盘和安全系数参数 |
ui.filters.* |
ui.filters |
数据源、分组、趋势指标与高级筛选条件 |
ui.report.sections.* |
ui.report |
报告各章节是否启用（key 为章节 ID） |
页面会显示当前数据识别到的指标数和配置命中的指标数。导入配置后，阈值区可只显示"配置命中指标"，避免侧边栏被大量动态指标撑满。
| 指标 | 含义 |
|---|---|
| 均值 / 峰值 | 场景内全部采样点的平均值 / 最大值 |
| P90 / P95 / P99 | 90 / 95 / 99 分位值，用于观察较高水位与尾部风险 |
| 超阈次数 / 超阈占比 | 异常采样点数量 / 数量占比，占比比次数更公平 |
| 最大连续超阈 | 同一指标连续超阈的最长时间，区分短暂尖峰与持续压力 |
| 峰值发生时间 | 峰值相对场景起始时间的偏移 |
| 标准差 / IQR / 变异系数 | 衡量指标波动性 |
| 趋势斜率 / 内存斜率 | 指标对时间的线性回归斜率，单位 指标值/分钟 或 MB/分钟 |
| CPU P95/吞吐、内存峰值/并发 | 单位吞吐 CPU 成本、单位并发内存成本 |
| 失败率 / 每千请求错误数 | 失败请求数/请求数、错误数/请求数×1000 |
| 风险评分 / 稳定性评分 | 综合超阈、连续超阈、泄漏、失败率、响应时间、FPS 的规则评分（100 分制扣分） |
| 发布门禁 / 容量估算 | 按风险规则输出通过/不通过；按 P95 单位成本对目标吞吐线性外推 |
| 控制图 UCL/LCL | 序列均值 ± 3 倍标准差，用于发现统计波动异常 |
| 采样间隔 / 异常段 | 相邻时间戳之差；连续异常点集合（间隔不超过典型采样间隔 1.5 倍） |
P95 比峰值更适合判断稳定压力，因为峰值可能只是一次瞬时尖峰。
- 动态指标发现：核心字段映射为内部标准字段后，扫描剩余列，可转数值的自动加入动态扩展指标（内部 key 加
extra::前缀，避免冲突）。 - 阈值告警：越高越差
值 > 阈值；越低越差值 < 阈值；配置上下限时按正常区间判断。配置了上下限优先用上下限。 - 稳定区间：按 数据源+场景 分别排除开头 N 分钟，避免启动预热尖峰影响长稳结论。
- 内存泄漏检测：对内存占用做线性回归，斜率 ≥ 阈值且 R2 ≥ 0.35 判为疑似泄漏；斜率 > 0 未达阈值判为轻微增长。适合快速筛查，不替代代码级定位。
- 版本对比：按 数据源+场景 分组计算统计值后横向比较；增长率超阈值且显著性检验通过（P 值 < 阈值且 |Cohen's d| ≥ 效应量阈值）才判"退化(显著)"。
- 阶段化分析：滚动平滑后用窗口跨度变化量找水平跳变点，把场景切分为 预热/稳定/压力 阶段（变化平缓的序列保持单一阶段）。
- 分钟级归一化：按分钟分桶计算 平均CPU/平均吞吐 等瞬时成本，观察高负载时段单位成本是否恶化。
- 测试结论模板：报告根据超阈采样点、峰值位置、疑似泄漏、配置建议生成规则式结论草稿，正式结论仍需结合业务与实测确认。
更详细的算法说明与示例见 docs/analysis-methodology.md。
配置建议使用 CPU P95（而不是均值或单次峰值）估算核心需求：
CPU原始需求 = 测试机逻辑核数 × CPU P95 / 目标CPU利用率上限
推荐配置 = 最低配置 × 安全系数（向上取常见核数档位）
示例：测试机 8 核、CPU P95 56%、目标利用率 70% → 8 × 56% / 70% = 6.4 → 取 8 核；推荐 8 × 1.5 = 12 核。
注意事项：
- 不要把系统总 CPU 再除以核数：
psutil.cpu_percent(interval=1)本身已是整机总利用率（0-100%）；进程占比口径（如process.cpu_percent() / cpu_count）才适合本公式。 - 目标利用率不能按 100% 估算：长期满载时响应易抖动。常见取值：60%（响应敏感）、70%（通用）、80%（资源紧张可接受抖动）。
- 只有总 CPU% 时无法判断单线程瓶颈、多核不均衡、IO 等待或锁竞争；如需正式配置说明，建议补充每核 CPU、进程 CPU 时间、业务负载量和响应时间。
generate_sample_data.py 会生成 data/sample_resource_consumption.xlsx：1 个系统信息 sheet + 4 个场景 sheet（冷启动、首页浏览、大数据导入、后台空闲），每个场景含 CPU、内存、线程、句柄、IO 及 QPS、并发、响应时间、FPS、GC、网络、请求、磁盘等语义化字段。
脚本数据为模拟数据，只用于页面调试和功能演示，不代表真实应用性能。
| 文件/目录 | 说明 |
|---|---|
app.py |
Streamlit 主页面（入口、侧边栏、tab 编排） |
generate_sample_data.py |
示例 Excel 生成脚本 |
perf_analyzer/ |
核心包：数据读取（io.py/data_loader.py）、分析计算（analysis.py/alerts.py/stats.py/quality.py）、决策规则（rules.py）、显著性检验（significance.py）、阶段检测（phases.py）、配置（config.py）、视图（views_*.py）、报告与导出（report.py/export*.py） |
tests/ |
pytest 测试：分析、告警、配置、显著性、阶段检测、分钟归一化 |
config/ |
可导入的分析配置示例（应用性能 / 通用时序） |
data/ |
示例 Excel 数据 |
docs/ |
分析方法说明、代码地图、superpowers 设计与实施文档 |
png/ |
本 README 使用到的界面截图 |
开发约定：
- 新增页面：在
perf_analyzer/views_*.py新增render_*()，由app.py编排到 tab。 - 新增图表：统一走
ui_helpers.render_plotly_chart()展示与导出。 - 新增指标：扩展
constants.py的标准指标和字段别名。 - 新增配置项：同步更新
config.py、ui_state.py、示例 JSON 和本 README。 - 修改代码后运行
python3 -m pytest tests/ -q确认无回归。