# ali-trace

这个仓库现在按两阶段组织：

1. `trace_formatter` 负责把 provider 原始 trace 整理成统一的 formatter 输出。
2. `trace_analyzer` 只分析 formatter 产出的 `*-raw.jsonl`，以及同源 build-release 产出的带 `hash_ids` 的 release jsonl。

主约束：

- `trace_analyzer` 不再直接处理 provider-native 原始日志。
- `details/` 只放画图所需数据。
- `figures/` 只放最终图片。
- 当前主分析入口只维护 13 张图，对应的数据也只保留为这 13 张图服务的最小集合。

朴素 wall-clock 时间字段如 `time` 按 `UTC+8` 解释。

## Install

```bash
uv sync
```

## Step 1: Format Raw Trace

把原始 trace 格式化成一个统一、按时间排序的 `*-raw.jsonl`。

格式化整个目录：

```bash
python -m trace_formatter format trace-glm5
```

格式化单个原始 shard：

```bash
python -m trace_formatter format trace-qwen3-coder/0419-1500-1700.jsonl
```

默认输出：

```text
trace-*-formatted/<mmddhh-mmddhh>-raw.jsonl
```

formatter 会做这些事：

1. 提取 provider 原始 trace，输出统一 schema 的 `*-raw.jsonl`。
2. 基于 `user_id + messages` 重建 logical session，并更新 `session_id / parent_request_id / turn / chat_id`。
3. 保留 analyzer 需要的字段，包括：
   - `canonical_prompt`
   - `usage`
   - 原始 `raw_messages`
   - `meta.total_cost_time_ms`
   - `meta.backend_first_request_time_ms`
   - `meta.backend_first_response_time_ms`
4. 对像 `Qwen3-Coder-480B-A35B-Instruct` 这种自带 `tool_parser.py` 的模型，优先使用模型自带 parser 做 `messages -> canonical_prompt`。

对于像 `0417-1500-1530.jsonl` 这种文件名，formatter 还会推断时间窗口，并按 ready-time 截断，避免把窗口外请求拼进结果。

示例：

- `trace-glm5` -> `trace-glm5-formatted/041715-041717-raw.jsonl`
- `trace-qwen3-coder/0419-1500-1700.jsonl` -> `trace-qwen3-coder-formatted/041915-041917-raw.jsonl`

## Step 2: Build Release Trace

从 `*-raw.jsonl` 构建 open-source-ready release jsonl。

```bash
python -m trace_formatter build-release trace-glm5-formatted/041715-041717-raw.jsonl --jobs 16
```

默认输出：

```text
trace-*-formatted/<mmddhh-mmddhh>.jsonl
```

这个 release 文件包含 tokenizer/block 化后的 `hash_ids`，供 kvcache 理论复用分析使用。

## Step 3: Analyze Formatted Trace

主分析入口：

```bash
python -m trace_analyzer analyze trace-glm5-formatted/041715-041717-raw.jsonl
```

默认输出布局：

```text
outputs/
  analysis/
    <model>-<dataset>/
      features.csv
      summary.json
      report.md
      analysis_snapshot.json
      details/
      figures/
```

例如：

- `trace-glm5-formatted/041715-041717-raw.jsonl` -> `outputs/analysis/glm5-041715-041717/`
- `trace-qwen3-coder-formatted/041915-041917-raw.jsonl` -> `outputs/analysis/qwen3-coder-041915-041917/`

`analyze` 会自动寻找同目录 sibling release 文件，也就是把 `*-raw.jsonl` 的 `-raw` 去掉后的 `.jsonl`。如果没有，需要先执行 `trace_formatter build-release`。

### `details/` 当前只保留的数据

`details/` 是数据层，不再放 PNG。

- `request_metrics.csv`
  请求级主表。用于：
  - input/output length
  - session turns / turn 维度请求长度
  - trigger role 占比
  - tool-call output length / latency / added context
  - bucket reuse ratio
- `theoretical_block_reuse_gaps.csv`
  相同 kvcache block 每次 reuse 与上次 reuse/首次出现的时间间隔分布。
- `theoretical_block_lifetimes.csv`
  每个 block 从首次出现到最后一次 reuse 的生命周期。
- `theoretical_alive_block_timeline.csv`
  存活 block 数量随时间变化的事件时间线。
- `session_bucket_boundary_miss.csv`
  session 前后轮请求跨分桶带来的 miss / reused-block loss 按 child bucket 的汇总。
- `details_summary.json`
  details schema 版本、分桶定义、全局 reuse 汇总。
- `progress.json`
  大 trace 运行时的进度与资源占用信息。

### `figures/` 当前只保留的 13 张图

`figures/` 是展示层，只放图片和轻量说明文件。

1. `01_input_output_length_cdf.png`
2. `02_session_turns_cdf.png`
3. `03_request_length_by_turn.png`
4. `04_request_trigger_role_pie.png`
5. `05_tool_call_output_length_cdf.png`
6. `06_tool_call_latency_cdf.png`
7. `07_consecutive_tool_call_count_cdf.png`
8. `08_tool_call_added_context_cdf.png`
9. `09_kvcache_block_reuse_time_cdf.png`
10. `10_kvcache_block_lifecycle_cdf.png`
11. `11_alive_kvcache_blocks_timeline.png`
12. `12_bucket_kvcache_reuse_ratio.png`
13. `13_session_cross_bucket_kvcache_miss.png`

另外还有：

- `manifest.json`
- `README.md`

所有图片都输出为 `600dpi` 的 PNG。

## Repo Structure

下面是当前推荐关注的代码结构，方便判断哪些文件是主路径、哪些是兼容/旧路径。

### Top Level

- `pyproject.toml`: 包配置、依赖、CLI entrypoints。
- `README.md`: 使用说明和当前代码结构。
- `trace_formatter/`: formatter 和 release builder。
- `trace_analyzer/`: analyzer。
- `trace_model_meta/`: tokenizer / chat template / model-specific parser 资源。
- `tests/`: 回归测试。

### `trace_formatter/`

- `trace_formatter/cli.py`: `format` / `build-release` CLI。
- `trace_formatter/formatting.py`: formatter 主逻辑和 release builder 主逻辑。
- `trace_formatter/raw_parser.py`: provider/model-specific message 解析，以及 `messages -> canonical_prompt`。
- `trace_formatter/sessionization.py`: logical session 重建。
- `trace_formatter/time_windows.py`: shard 时间窗口解析和 ready-time 截断。

### `trace_analyzer/`

- `trace_analyzer/cli.py`
  主 CLI。`analyze` 走当前主路径：
  `preparation.py -> resume_advanced.py -> reporting.py -> figures.py`
- `trace_analyzer/parser.py`
  只负责读取 formatter 生成的 `*-raw.jsonl`，反序列化成 `TraceRecord`。
  它不是 stale，`parse / features / report / study` 这些子命令都在用。
- `trace_analyzer/models.py`
  analyzer 内部 dataclass schema 边界。
  它不是 stale，`parser.py`、`features.py`、`report.py` 都依赖它。
- `trace_analyzer/preparation.py`
  流式读取 `*-raw.jsonl`，生成 `features.csv`。
  它是 `analyze` 主路径的第一步，不是 stale。
- `trace_analyzer/features.py`
  从 `TraceRecord` 提取请求级 feature。
- `trace_analyzer/resume_advanced.py`
  当前 `analyze` 主路径的数据层明细分析器。
  现在只负责生成 `details/` 下的画图数据，不再生成 PNG，也不再写大量 transition/context-change/agentic 的旧产物。
- `trace_analyzer/figures.py`
  当前唯一的绘图入口。
  现在统一从 `details/` 读数据，输出 `figures/` 下的 13 张图。
- `trace_analyzer/reporting.py`
  从 `features.csv` 和 `details_summary.json` 生成 `summary.json / report.md / analysis_snapshot.json`。
- `trace_analyzer/report.py`
  旧的 record-oriented report path，主要服务 `parse / features / report / study` 这些 in-memory 子命令。
- `trace_analyzer/study.py`
  兼容保留的旧 in-memory study 路径与辅助函数集合，主要给 `study` 子命令使用。
  它不再是 `analyze` 主路径的明细产物生成入口。
- `trace_analyzer/helpers.py`
  小工具函数。
- `trace_analyzer/layout.py`
  `details/` / 旧 `advanced/` 的路径兼容和存在性判断。

### `trace_model_meta/`

- `trace_model_meta/registry.py`: model family 推断、tokenizer/chat-template 解析。
- `trace_model_meta/Qwen/Qwen3-Coder-480B-A35B-Instruct/qwen3coder_tool_parser.py`:
  Qwen3-Coder 自带 tool parser，formatter 会优先使用它来做 tool-call prompt 序列化。

### `tests/`

- `tests/test_ali_trace_pipeline.py`: formatter + analyzer 主流程回归。
- `tests/test_trace_analyzer.py`: analyzer 单元测试和子命令测试。

## Design Notes

当前代码清理后的边界是：

- trace format 工作集中在 `trace_formatter/`
- trace analyze 工作集中在 `trace_analyzer/`
- `trace_analyzer` 分析输入是 formatter 产出的 `*-raw.jsonl`，而不是 provider-native raw
- `details/` 只放数据
- `figures/` 只放图片