gahow/ali-trace-tools
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
5a6b1acb490afa9ada3b5523db2ad649a0cb3f8a
ali-trace-tools/README.md
Gahow Wang bce3fe1395 Initial commit
2026-04-21 15:44:47 +00:00

8.0 KiB
Raw Blame History

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

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 请求级主表。用于：
    • 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/ 只放图片