# xperf

**Repository Path**: stkid/xperf

## Basic Information

- **Project Name**: xperf
- **Description**: 通智算融合 Top-down 性能分析工具
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-04
- **Last Updated**: 2026-06-12

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# xperf — 通智算融合 Top-down 性能分析工具

为 AI Agent 工作负载构建全栈性能可观测性工具，基于通智算融合 Top-down 理论，将 Intel 微架构 Top-down 方法论扩展到三个计算域：**通算域**（CPU）、**智算域**（GPU/LLM）、**融合域**（跨域数据流瞬间）。

## 理论基础

详见 [`software-topdown-performance-theory.md`](docs/software-topdown-performance-theory.md)

核心四分类：

| 类别 | 含义 | 融合场景解读 |
|------|------|-------------|
| **Supply Bound** | 等待数据/资源 | Agent 等 LLM 响应、TTFT、GPU 排队 |
| **Processing Bound** | 处理速度跟不上 | LLM 推理慢、Prompt 组装慢 |
| **Waste Bound** | 无效工作（客观可测） | 失败 tool call、重试、截断 token |
| **Effective Work** | 产出预期结果 | 成功的推理链、必要的 prompt 组装 |

三大域 × 四分类 = 12 子类（L2），28+ 瓶颈点（L3），PMU 硬件根因（L4）。

## 架构

```
Agent Process (xperf-sdk)    →    JSON trace files    →    Analyzer (xperf-analyze)
     嵌入式 hook 采集                本地文件管道               独立进程事后分析
```

四个模块（按依赖顺序）：

| 模块 | 职责 | 依赖 |
|------|------|------|
| `xperf-theory` | 纯数据定义：域、分类、瓶颈表、阈值、优化建议 | 无 |
| `xperf-trace-schema` | TurnTrace/Event/PerfEvent JSON Schema 与验证 | theory |
| `xperf-sdk` | 嵌入式采集 hook，自动域归属，写 JSON trace | theory + trace-schema |
| `xperf-analyze` | 归一化→域校验→钻取→报告 | theory + trace-schema |

## 安装

```bash
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
```

## SDK 使用示例

```python
import xperf

xperf.init(agent_info={"name": "claude-code", "model": "claude-sonnet-4-6"})
turn = xperf.start_turn()

# 1. Prompt 组装（通算域 Processing）
span_prompt = turn.enter("prompt_assembly")
# ... build prompt
turn.leave(span_prompt)

# 2. Prompt 传输 → TTFT（融合域 Supply）
span_ttf = turn.enter("prompt_transfer")
turn.mark_fused("ttft", {"ttft_ns": elapsed_ns})
turn.leave(span_ttf)

# 3. LLM 推理（智算域）
span_llm = turn.enter_llm({"system": "anthropic", "request_model": "claude-sonnet-4-6", "input_tokens": 150})
# ... receive streaming tokens
turn.leave_llm(span_llm, {"output_tokens": 80, "finish_reason": "stop"})

# 4. Response 解析（通算域）
span_parse = turn.enter("response_parse")
# ... parse output
turn.leave(span_parse)

# 5. Tool 调用（含失败 → Waste）
span_tool = turn.enter("tool_call", tool_name="bash")
# ... execute tool
if tool_result.is_error:
    turn.mark_waste("failed_tool_call", {"failed_calls": 1, "retries": 2})
turn.leave(span_tool)

xperf.end_turn(turn)
```

Trace 文件写入 `.xperf/traces/{session_id}/turn_001.json`

## Analyzer 使用

```bash
# 单 Turn 分析（JSON 输出）
xperf analyze turn .xperf/traces/{session}/turn_001.json

# 单 Turn 分析（文本输出）
xperf analyze turn .xperf/traces/{session}/turn_001.json --format text

# 单 Turn 分析（HTML 报告）
xperf analyze turn .xperf/traces/{session}/turn_001.json --format html > report.html

# 钻取深度控制
xperf analyze turn turn_001.json --depth L2   # 只到域分解
xperf analyze turn turn_001.json --depth L3   # 到瓶颈点（默认）
xperf analyze turn turn_001.json --depth L4   # 到硬件根因

# 会话聚合分析
xperf analyze session .xperf/traces/{session}/

# 可测性筛选（只看客观可测指标）
xperf analyze turn turn_001.json --measurability A,B
```

## Analyzer Pipeline

```
TraceLoader → Normalizer → DomainAttributor → DrillDownEngine → Aggregator → Reporter
  读 JSON      归一化      校验域归属         L1→L2→L3→L4 钻取     多Turn聚合      JSON/Text/HTML
  验证Schema   sum=100%    修正错误           >20%阈值触发         瓶颈频率         报告输出
```

## 自动域归属

SDK 内置 `STAGE_DOMAIN_MAP`，Agent 只需标注 stage 名称：

| Stage | 自动归属域 |
|-------|-----------|
| `prompt_assembly`, `response_parse`, `tool_call`, `tool_compute`, `orchestration`, `context_compress`, `state_serialize`, `memory_ops` | **通算域** (compute) |
| `llm_inference`, `prefill`, `decode`, `sampling` | **智算域** (intelligent) |
| `prompt_transfer`, `response_transfer`, `ttft`, `streaming_gap` | **融合域** (fused) |

`bound_category` 自动推导规则：
- 通算域：`cpu_time/duration < 0.3` → Supply，否则 → Processing
- 智算域：含 "wait" → Supply，否则 → Processing
- 融合域：`ttft/streaming_gap/prompt_transfer` → Supply，否则 → Processing
- `mark_waste()` → Waste（最高优先级）

## 关键设计原则

- **执行位置原则**：CPU 工作 → 通算域，GPU 工作 → 智算域，跨域瞬间 → 融合域
- **融合域是薄接口**：只捕获数据流跨域的瞬间（TTFT、streaming gap），不包含 CPU 侧的 prompt 组装、response 解析
- **归一化在单 Turn 内**：所有时间片段 sum = 100%
- **钻取阈值**：某类 > 20% → 继续钻取
- **可测性分级**：A 级（直接可测）和 B 级（间接可测）用于实时 Topdown，C 级（主观需审）暂归 Processing

## 测试

```bash
# 运行所有测试
pytest tests/ -v

# 覆盖率检查
pytest tests/ --cov=xperf --cov-report=term-missing
```

当前：**200 tests, 91% coverage**

## 项目结构

```
xperf/
├── xperf/
│   ├── theory/          # 纯数据定义（域、分类、瓶颈表、阈值）
│   ├── trace_schema/    # JSON Schema 定义与验证
│   ├── sdk/             # 嵌入式采集 SDK
│   ├── analyze/         # 独立分析工具（CLI + Pipeline）
├── tests/
│   ├── theory/
│   ├── sdk/
│   ├── analyze/
├── docs/software-topdown-performance-theory.md   # 核心理论文档
├── docs/superpowers/specs/                   # 设计规格
├── pyproject.toml
└── README.md
```

## 设计规格

详见 [`docs/superpowers/specs/2026-06-04-xperf-tool-design.md`](docs/superpowers/specs/2026-06-04-xperf-tool-design.md)

## 许可

MIT