multi-agent-performance-profiling

多 Agent 性能分析

自我进化的技能：此技能会在使用过程中不断改进。如果指令有误、参数发生漂移，或需要采用变通方法，请立即修复此文件，不要拖延。仅针对真实、可复现的问题进行更新。

概述

一套规范化工作流，用于并行启动分析 Agent，全面识别多个系统层的性能瓶颈。曾成功发现 QuestDB 的摄取速度达到每秒 1.1M 行（比目标快 11 倍），证明数据库并非瓶颈——CloudFront 下载占据了整个流水线耗时的 90%。

何时使用此技能

在以下情况使用此技能：

• 性能低于 SLO（例如，目标为每秒 100K 行，实际仅为 47K 行）
• 多阶段流水线优化（下载 → 解压 → 解析 → 摄取）
• 数据库性能调查
• 识别复杂工作流中的瓶颈
• 优化前分析（进行任何更改之前）

主要成果：

• 找出真正的瓶颈（而非假定的瓶颈）
• 量化各阶段对总耗时的贡献
• 按影响确定优化优先级（P0/P1/P2）
• 避免过早优化非瓶颈

核心方法论

1. 多层分析模型（5-Agent 模式）

Agent 1：性能分析（埋点）

• 对流水线各阶段进行实测计时
• 在阶段边界使用 time.perf_counter() 埋点
• 内存分析（峰值使用量、分配情况）
• 识别瓶颈（占总耗时的百分比）

Agent 2：数据库配置分析

• 审查服务器设置（WAL、堆、提交间隔）
• 比较生产环境与开发环境的配置
• 量化预期影响（<5%、10%、50%）

Agent 3：客户端库分析

• API 使用模式（数据帧与逐行处理）
• 缓冲区大小调优机会
• 分析自动刷新行为

Agent 4：批次大小分析

• 验证当前批次大小
• 确定最佳批次范围
• 权衡内存开销与吞吐量

Agent 5：集成与综合

• 在各 Agent 之间达成共识
• 确定优先级（P0/P1/P2）并量化影响
• 制定实施路线图

2. Agent 编排模式

并行执行（全部 5 个 Agent 同时运行）：

Agent 1 (Profiling)          → [PARALLEL]
Agent 2 (DB Config)          → [PARALLEL]
Agent 3 (Client Library)     → [PARALLEL]
Agent 4 (Batch Size)         → [PARALLEL]
Agent 5 (Integration)        → [PARALLEL - reads tmp/ outputs from others]

关键原则：调查 Agent（1-4）之间没有依赖关系。集成 Agent 负责综合调查结果。

动态 Todo 管理：

• 从调查计划开始（5 个 Agent）
• 使用包含多个 Task 工具调用的单条消息并行启动 Agent
• 每个 Agent 完成后更新 todos
• 集成 Agent 等待所有调查结果后再进行综合

3. 分析脚本结构

每个 Agent 都会产出：

1. 调查脚本（例如，profile_pipeline.py）
   • 在阶段边界使用 time.perf_counter() 埋点
   • 使用 tracemalloc 进行内存分析
   • 结构化输出（阶段、耗时、占总耗时的百分比）
2. 报告（包含调查结果、建议和影响量化的 Markdown 文档）
3. 证据（基准测试结果、配置转储、API 跟踪记录）

性能分析代码示例：

import time

# Profile multi-stage pipeline
def profile_pipeline():
    results = {}

    # Phase 1: Download
    start = time.perf_counter()
    data = download_from_cdn(url)
    results["download"] = time.perf_counter() - start

    # Phase 2: Extract
    start = time.perf_counter()
    csv_data = extract_zip(data)
    results["extract"] = time.perf_counter() - start

    # Phase 3: Parse
    start = time.perf_counter()
    df = parse_csv(csv_data)
    results["parse"] = time.perf_counter() - start

    # Phase 4: Ingest
    start = time.perf_counter()
    ingest_to_db(df)
    results["ingest"] = time.perf_counter() - start

    # Analysis
    total = sum(results.values())
    for phase, duration in results.items():
        pct = (duration / total) * 100
        print(f"{phase}: {duration:.3f}s ({pct:.1f}%)")

    return results

4. 影响量化框架

优先级：

• P0（关键）：提升 >5 倍，解决主要瓶颈
• P1（高）：提升 2-5 倍，次要优化
• P2（中）：提升 1.2-2 倍，快速见效的优化
• P3（低）：提升 <1.2 倍，细微调优

影响报告格式：

### Recommendation: [Optimization Name] (P0/P1/P2) - [IMPACT LEVEL]

**Impact**: 🔴/🟠/🟡 **Nx improvement**
**Effort**: High/Medium/Low (N days)
**Expected Improvement**: CurrentK → TargetK rows/sec

**Rationale**:

- [Why this matters]
- [Supporting evidence from profiling]
- [Comparison to alternatives]

**Implementation**:
[Code snippet or architecture description]

5. 达成共识的模式

集成 Agent 的职责：

1. 阅读所有调查报告（Agent 1-4）
2. 找出共识建议（所有 Agent 均认同）
3. 标记意见相左之处（Agent 之间存在分歧）
4. 综合形成主集成报告
5. 制定实施路线图（P0 → P1 → P2）

共识标准：

• ≥3/4 的 Agent 建议进行相同优化 → 达成共识
• 2/4 的 Agent 建议，2/4 持中立态度 → 进一步调查
• Agent 意见相左（一方建议“优化 X”，另一方认为“X 并非瓶颈”）→ 运行裁决实验

工作流：分步指南

步骤 1：定义性能问题

输入：性能指标低于 SLO 输出：包含基线指标的问题陈述

问题陈述示例：

Performance Issue: BTCUSDT 1m ingestion at 47K rows/sec
Target SLO: >100K rows/sec
Gap: 53% below target
Pipeline: CloudFront download → ZIP extract → CSV parse → QuestDB ILP ingest

步骤 2：制定调查计划

目录结构：

tmp/perf-optimization/
  profiling/              # Agent 1
    profile_pipeline.py
    PROFILING_REPORT.md
  questdb-config/         # Agent 2
    CONFIG_ANALYSIS.md
  python-client/          # Agent 3
    CLIENT_ANALYSIS.md
  batch-size/             # Agent 4
    BATCH_ANALYSIS.md
  MASTER_INTEGRATION_REPORT.md  # Agent 5

Agent 分配：

• Agent 1：实证性能分析（插桩）
• Agent 2：数据库配置分析
• Agent 3：客户端库使用情况分析
• Agent 4：批次大小优化分析
• Agent 5：综合与集成

步骤 3：并行启动 Agent

重要：使用一条消息调用多个 Task 工具，以实现真正的并行处理

示例：

I'm going to spawn 5 parallel investigation agents:

[Uses Task tool 5 times in a single message]
- Agent 1: Profiling
- Agent 2: QuestDB Config
- Agent 3: Python Client
- Agent 4: Batch Size
- Agent 5: Integration (depends on others completing)

执行：

# All agents run simultaneously (user observes 5 parallel tool calls)
# Each agent writes to its own tmp/ subdirectory
# Integration agent polls for completed reports

步骤 4：等待所有 Agent 完成

进度跟踪：

• 每个 Agent 完成后更新待办列表
• 集成 Agent 轮询 tmp/ 目录，查找报告文件
• 一旦存在 4/4 份调查报告 → 集成 Agent 汇总结果

完成标准：

• 已写入全部 4 份调查报告
• 集成报告汇总调查结果
• 已创建总建议列表

步骤 5：审阅总集成报告

报告结构：

# Master Performance Optimization Integration Report

## Executive Summary

- Critical discovery (what is/isn't the bottleneck)
- Key findings from each agent (1-sentence summary)

## Top 3 Recommendations (Consensus)

1. [P0 Optimization] - HIGHEST IMPACT
2. [P1 Optimization] - HIGH IMPACT
3. [P2 Optimization] - QUICK WIN

## Agent Investigation Summary

### Agent 1: Profiling

### Agent 2: Database Config

### Agent 3: Client Library

### Agent 4: Batch Size

## Implementation Roadmap

### Phase 1: P0 Optimizations (Week 1)

### Phase 2: P1 Optimizations (Week 2)

### Phase 3: P2 Quick Wins (As time permits)

步骤 6：实施优化（先处理 P0）

对于每项建议：

1. 实施优先级最高的优化（P0）
2. 重新运行性能分析脚本
3. 验证是否达到预期改进
4. 使用实际结果更新报告
5. 继续处理下一优先级（P1、P2、P3）

实施示例：

# Before optimization
uv run python tmp/perf-optimization/profiling/profile_pipeline.py
# Output: 47K rows/sec, download=857ms (90%)

# Implement P0 recommendation (concurrent downloads)
# [Make code changes]

# After optimization
uv run python tmp/perf-optimization/profiling/profile_pipeline.py
# Output: 450K rows/sec, download=90ms per symbol * 10 concurrent (90%)

实际示例：QuestDB 重构性能调查

背景：管道处理速度为 47K 行/秒，目标为 100K 行/秒（低于 SLO 53%）

调查前的假设：

• QuestDB ILP 写入是瓶颈（耗时 4%）
• 需要调整数据库配置
• 需要优化 Sender API 的使用

5 个 Agent 调查后的发现：

1. 性能分析 Agent：CloudFront 下载占用 90% 的时间（857ms），ILP 写入仅占 4%（40ms）
2. QuestDB 配置 Agent：数据库配置已达最佳，调整后的改进幅度低于 5%
3. Python 客户端 Agent：Sender API 已达最佳状态（使用 dataframe() 批量写入）
4. 批次大小 Agent：44K 的批次大小处于最佳范围内
5. 集成 Agent：一致建议优化下载，而不是数据库

最重要的 3 项建议：

1. 🔴 P0：并发下载多个交易品种（提升 10–20 倍）
2. 🟠 P1：并行处理多个月份的管道任务（提升 2 倍）
3. 🟡 P2：流式解压 ZIP 文件（提升 1.3 倍）

影响：发现数据库写入速度达到 1.1M 行/秒（比目标快 11 倍），证明数据库从来都不是瓶颈

结果：避免在数据库优化上浪费 2–3 周，而真正的瓶颈在下载环节

常见陷阱

1. 只分析一层

❌ 错误：只分析数据库，假定它是瓶颈 ✅ 正确：分析整个管道（下载 → 解压 → 解析 → 写入）

2. 串行执行 Agent

❌ 错误：运行 Agent 1 并等待，然后运行 Agent 2 并等待，以此类推 ✅ 正确：通过一条消息调用多个 Task，并行启动全部 5 个 Agent

3. 未经性能分析就进行优化

❌ 错误：“我们先优化数据库配置吧”（基于假设） ✅ 正确：先进行性能分析，发现数据库仅占用 4% 的时间，然后改为优化下载

4. 忽略容易实现的优化

❌ 错误：只实施 P0（影响最大、投入最高） ✅ 正确：规划 P0 的同时，实施 P2 快速优化（投入 4–8 小时可提升 1.3 倍）

5. 更改后未重新进行性能分析

❌ 错误：实施优化后，就假定优化生效 ✅ 正确：重新运行性能分析脚本，验证是否达到预期改进

资源

scripts/

不适用——性能分析脚本因项目而异（存放在 tmp/perf-optimization/ 中）

references/

• profiling_template.py - 阶段边界插桩模板
• integration_report_template.md - 总集成报告模板
• impact_quantification_guide.md - P0/P1/P2 优先级评估方法

assets/

不适用——性能分析产物因项目而异

---

故障排除

问题	原因	解决方案
Agent 按顺序运行	使用了单独的消息	在一条消息中使用多个 Task 启动所有 Agent
集成报告为空	Agent 未撰写报告	等待全部 4 个调查 Agent 完成
识别的瓶颈有误	仅分析了单层性能	对整个管道进行性能分析，而不只是分析假定的层
性能分析结果不一致	未进行预热运行	测量前运行 3-5 次预热迭代
未分析内存使用情况	缺少 tracemalloc	在性能分析脚本中添加 tracemalloc 检测
P0/P1 优先级不明确	未量化影响	为每项发现注明预期的 N 倍提升
缺少共识	未比较 Agent 的结论	集成 Agent 必须综合全部 4 份报告
重新分析后结果没有变化	缓存影响	重新进行性能分析前，清除缓存并重启服务

执行后反思

此技能完成后，在结束任务前进行反思：

0. 确定自身位置。——编辑前，找到此 SKILL.md 的规范路径。
1. 哪里失败了？——修正导致失败的指令。
2. 哪些做得比预期更好？——将其列为推荐实践。
3. 哪里出现了偏差？——修正任何与实际情况不符的脚本、参考资料或依赖项。
4. 记录下来。——添加演进日志条目，记录触发原因、修正内容和证据。

不要推迟。下一次调用会继承你留下的一切。