234 lines
8.0 KiB
Markdown
234 lines
8.0 KiB
Markdown
# 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/` 只放图片
|