ali-trace-tools/README.md

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/ 只放最终图片。
• 当前主分析入口只维护 15 张图，对应的数据也只保留为这 15 张图服务的最小集合。

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

Install

uv sync

Step 1: Format Raw Trace

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

格式化整个目录：

python -m trace_formatter format trace-glm5

格式化单个原始 shard：

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

默认输出：

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。

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

默认输出：

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

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

Step 3: Analyze Formatted Trace

主分析入口：

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

默认输出布局：

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 请求级主表。用于：
  • TTFT / TPOT
  • 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/ 当前只保留的 15 张图

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
14. 14_ttft_cdf.png
15. 15_tpot_cdf.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/ 只放图片