从火焰图到JSON：py-spy全输出格式实战指南

从火焰图到JSON：py-spy全输出格式实战指南

【免费下载链接】py-spy Sampling profiler for Python programs 项目地址: https://gitcode.com/gh_mirrors/py/py-spy

py-spy作为一款强大的Python采样分析器（Sampling profiler for Python programs），提供了多种输出格式帮助开发者诊断性能问题。本文将系统解析speedscope、火焰图（Flamegraph）、Chrome Trace和原始数据四种核心格式的应用场景与实现原理，结合src/speedscope.rs、src/flamegraph.rs等源码模块，帮助你选择最适合的分析方式。

输出格式对比速查表

格式类型	适用场景	工具兼容性	输出文件示例	核心源码模块
speedscope	交互式调用栈分析	speedscope.app	profile.speedscope.json	src/speedscope.rs
火焰图	热点函数可视化	浏览器/Firefox Profiler	flamegraph.svg	src/flamegraph.rs
Chrome Trace	时间线分析	Chrome DevTools	trace.json	src/chrometrace.rs
原始数据	自定义分析	文本编辑器/Python脚本	dump.txt	src/dump.rs

1. speedscope：交互式调用栈分析

speedscope格式通过JSON结构保存采样数据，支持多线程对比和调用栈展开分析。其实现位于src/speedscope.rs，采用采样类型（ProfileType::Sampled）记录每个线程的调用栈序列。

使用方法

py-spy record -o profile.speedscope.json -- python app.py

关键实现

在src/speedscope.rs#L59-L127定义了符合speedscope规范的JSON结构，包括：

• Shared：存储所有唯一调用栈帧（Frame）
• Profile：按线程分组的采样数据
• ValueUnit::Seconds：时间单位标准化

2. 火焰图：热点函数可视化

火焰图通过SVG图像直观展示函数调用耗时，X轴表示采样时间分布，Y轴表示调用栈深度。src/flamegraph.rs使用inferno库生成符合Brendan Gregg格式的可视化结果。

使用方法

py-spy record -o flamegraph.svg -- python app.py

实现细节

src/flamegraph.rs#L50-L74将调用栈转换为分号分隔的字符串：

// 代码片段：[src/flamegraph.rs#L52-L70]
let frame = trace
    .frames
    .iter()
    .rev()
    .map(|frame| {
        let filename = match &frame.short_filename {
            Some(f) => f,
            None => &frame.filename,
        };
        if self.show_linenumbers && frame.line != 0 {
            format!("{} ({}:{})", frame.name, filename, frame.line)
        } else if !filename.is_empty() {
            format!("{} ({})", frame.name, filename)
        } else {
            frame.name.clone()
        }
    })
    .collect::<Vec<String>>()
    .join(";");

3. Chrome Trace：时间线分析

Chrome Trace格式将采样数据转换为Chrome DevTools兼容的事件流，适合分析线程活动和GIL（Global Interpreter Lock，全局解释器锁）争用。实现位于src/chrometrace.rs。

使用方法

py-spy record -o trace.json --format chrometrace -- python app.py

数据结构

src/chrometrace.rs#L18-L27定义了事件格式：

#[derive(Clone, Debug, Serialize)]
struct Event {
    pub args: Args,      // 包含文件名和行号
    pub cat: String,     // 事件类别（固定为"py-spy"）
    pub name: String,    // 函数名
    pub ph: String,      // 事件类型（B=开始，E=结束）
    pub pid: u64,        // 进程ID
    pub tid: u64,        // 线程ID
    pub ts: u64,         // 时间戳（微秒）
}

4. 原始数据：自定义分析基础

原始数据格式通过命令行直接输出调用栈信息，适合编写自定义分析脚本。实现位于src/dump.rs，支持JSON和文本两种输出模式。

使用方法

# 文本格式
py-spy dump -- python app.py

# JSON格式
py-spy dump --json -- python app.py

文本输出示例

Thread 1 (active): "MainThread"
    run (app.py:42)
    handle_request (server.py:156)
    process_data (utils/parser.py:89)

5. 控制台实时查看

除文件输出外，py-spy还提供交互式控制台查看器，通过src/console_viewer.rs实现实时数据展示。支持按键切换排序方式（1-4）、显示行号（L）和重置统计（R）。

格式选择决策指南

1. 性能瓶颈定位：优先选择火焰图（flamegraph.svg），快速识别热点函数
2. 调用关系分析：使用speedscope格式，支持调用栈展开和比较
3. 线程调度问题：Chrome Trace格式配合Chrome DevTools时间线视图
4. 自动化分析：原始JSON格式，通过tests/integration_test.py等脚本处理

通过灵活运用这些输出格式，结合py-spy的采样能力，可有效诊断Python应用的各类性能问题。完整使用文档参见README.md。

【免费下载链接】py-spy Sampling profiler for Python programs 项目地址: https://gitcode.com/gh_mirrors/py/py-spy