# 集群指标对比分析（Cluster Metrics Comparator）
# 运行命令

bash -lc "source .venv/bin/activate && python3 compare_cluster_metrics.py prod out_test 11,12,13"

first run:

rm -rf .venv
python3 -m venv .venv
bash -lc "source .venv/bin/activate && pip install -U pip"
bash -lc "source .venv/bin/activate && pip install numpy pandas matplotlib"


对两套集群数据进行指标对齐、统计与图表输出的 Python 工程。

## 目录
- 特性
- 前置条件
- 快速开始（示例）
- 输入与命名约定
- 输出位置
- 运行流程
- 支持指标
- 新增图表/指标指南
- 新增集群类型
- 常见问题

## 特性
- 支持多指标对比：`P999`、`P99`、`P95`、`CPS`、`Duration_AVG`、`CPU_TiDB/TiKV/TiFlash`
- 自动时间轴对齐（第二集群前移 `time_offset`）
- 输出 Markdown 对比表与 PNG 图表
- 延迟类统一以毫秒展示

## 前置条件
- Python 3.x
- 依赖安装：
  - `python3 -m venv .venv`
  - `source .venv/bin/activate`
  - `python -m pip install -r requirements.txt`

## 快速开始（示例）
以 `prod` 集群为例：
- 准备数据（`prod/data/`）：`prod_p99.csv`、`replay_p99.csv`、`prod_duration_avg.csv`、`replay_duration_avg.csv`（每个文件必须有 `Time` 与一个数值列）
- 运行：`python compare_cluster_metrics.py prod`
- 查看输出：
  - 表格：`prod/prod_comparison_table.md`
  - 图片：`prod/png/*.png`

## 输入与命名约定
- 数据目录：
  - `saas05-1/data_saas05/`（`saas05` vs `gosaas`）
  - `gogame-1/data_gogame/`（`gogame` vs `poc`）
  - `prod/data/`（`prod` vs `replay`）
- 文件命名：`<cluster>_<metric>.csv`，如 `prod_duration_avg.csv`
- 时间对齐：第二集群文件按 `time_offset` 前移（`compare_cluster_metrics.py:63-67`）

## 输出位置
- 表格：`/<cluster1>/<cluster1>_comparison_table.md`（`compare_cluster_metrics.py:685-691`）
- 图片：`/<cluster1>/png/*.png`（自动创建目录，`compare_cluster_metrics.py:425-431`）

## 运行流程
1. 入口选择与构造比较器：`compare_cluster_metrics.py:699-736`
2. 加载数据：`load_all_data()`（`metric_files` 定义，`compare_cluster_metrics.py:78-117`）
3. 统计计算：`calculate_statistics()`（含延迟毫秒转换，`compare_cluster_metrics.py:203-239`）
4. 生成表格：`generate_comparison_table()`（`compare_cluster_metrics.py:299-353`）
5. 绘制图表：`plot_comparison_charts()`（`compare_cluster_metrics.py:421-557`）

## 支持指标
- 默认启用：`P999`、`P99`、`P95`、`CPS`、`Duration_AVG`、`CPU_TiDB`、`CPU_TiKV`、`CPU_TiFlash`
- 可选启用：`Memory_*`、`Storage_*`、`IOPS`、`Bandwidth`、`FailCount`

## 新增图表/指标指南
以 `duration_avg` 为例：
- 在 `metric_files` 增加：`'Duration_AVG': [f"{cluster1}_duration_avg.csv", f"{cluster2}_duration_avg.csv"]`（`compare_cluster_metrics.py:78-117`）
- 在 `metrics_to_show` 增加：
  - `('duration_avg_Max (ms)', 'Duration_AVG', 'max')`
  - `('duration_avg_AVG (ms)', 'Duration_AVG', 'avg')`（`compare_cluster_metrics.py:299-353`）
- 在 `metric_info` 增加：`'Duration_AVG': {'title': 'duration_avg 对比', 'unit': 'ms'}`（`compare_cluster_metrics.py:436-453`）
- 秒→毫秒转换：
  - 统计阶段：`compare_cluster_metrics.py:233-238`
  - 绘图阶段：`compare_cluster_metrics.py:495-499`

## 新增集群类型
- 在 `main()` 添加分支，设置 `data_dir`、`cluster1_name`、`cluster2_name`、`time_offset`（示例见 `compare_cluster_metrics.py:724-730`）

## 常见问题
- 表格写入失败：确保 `/<cluster1>` 目录存在
- 错误率图未生成：需同时提供 `FailCount` 与 `CPS` 两个 CSV
- 单位不匹配：确认指标已加入毫秒转换列表，并在 `metric_info` 设置单位为 `ms`


## 新增指标和图行
在现有脚本 `compare_cluster_metrics.py` 中，新增对 `QPS` 指标的支持，读取 `prod_qps.csv` 与 `replay_qps.csv` 并生成 `qps_comparison.png`，同时在对比表格中展示 QPS 的 Max/Max_Time/AVG。

## 代码改动点
1. 指标文件映射
- 位置：`compare_cluster_metrics.py:79-135`
- 操作：在 `metric_files` 中新增键 `"QPS"`，映射到 `[f"{self.cluster1_name}_qps.csv", f"{self.cluster2_name}_qps.csv"]`
- 示例：
  - `'QPS': [f'{self.cluster1_name}_qps.csv', f'{self.cluster2_name}_qps.csv'],`

2. 图表元信息
- 位置：`compare_cluster_metrics.py:461-478`
- 操作：在 `metric_info` 中新增：
  - `'QPS': {'title': 'QPS 吞吐量对比', 'unit': 'QPS'}`

3. 数值格式化
- 位置：`compare_cluster_metrics.py:291-314`
- 操作：将 `CPS` 的格式化规则同时应用到 `QPS`：
  - `elif metric_name in ['CPS', 'QPS']:` 返回千分位整数。

4. 对比表格项目
- 位置：`compare_cluster_metrics.py:321-371`
- 操作：在 `metrics_to_show` 里新增 QPS 行，参考 CPS：
  - `('QPS_Max (QPS)', 'QPS', 'max')`
  - `('QPS_Max_Time', 'QPS', 'max_time')`
  - `('QPS_AVG (QPS)', 'QPS', 'avg')`

5. 其他逻辑
- 无需单位转换：`QPS` 不在 `['P999','P99','P95','Duration_AVG']`，无需毫秒转换。
- 错误率计算保持使用 `CPS`（`FailCount`/`CPS`），不改动。

## 输入/输出路径
- 输入：`prod/data/prod_qps.csv`、`prod/data/replay_qps.csv`（已存在且格式为 `Time,Value`）。
- 输出：在指定 `output_dir` 下的 `png` 目录生成 `qps_comparison.png`；在对比表格中增加 QPS 行（例如写入 `out_test/prod_comparison_table.md`）。

## 运行方式
- 示例：`bash -lc "source .venv/bin/activate && python3 compare_cluster_metrics.py prod out_test 11,12,13"`
- 也可：`python compare_cluster_metrics.py prod out_test 11,12,13`

## 验证步骤
- 确认 `.venv` 中已安装 `pandas/numpy/matplotlib`（`python -m pip install -r requirements.txt`）。
- 执行后检查：
  - `out_test/png/qps_comparison.png` 是否生成且曲线与时间轴正常。
  - `out_test/prod_comparison_table.md` 中是否出现 QPS 三行并正确填值。
- 快速自检：
  - `python -c "import pandas as pd; print(pd.read_csv('prod/data/prod_qps.csv').head())"`