Speedscope

Speedscope is a comprehensive performance profiling visualization tool that provides an interactive web-based interface for analyzing profiling data from multiple programming languages and environments. It supports importing profiles from Chrome DevTools, Firefox, Node.js, Ruby, Python, Go, Java, and many other sources, enabling developers to identify performance bottlenecks through multiple visualization modes including chronological time order view, left-heavy aggregated view, and sandwich table view.

Package Information

• Package Name: speedscope
• Package Type: npm
• Language: TypeScript
• Installation: npm install speedscope

Core Imports

Speedscope is primarily a CLI application and web app, not a traditional library:

# CLI usage (primary interface)
npm install -g speedscope
speedscope profile.json

For programmatic browser usage (when speedscope web app is loaded):

// Global speedscope object available in browser
window.speedscope.loadFileFromBase64(filename: string, base64source: string): void;

Note: Speedscope does not export its internal modules for programmatic use. The profile import functionality is designed for internal use by the web application and CLI tool.

Basic Usage

CLI Usage

# Open speedscope in browser with no file
speedscope

# Open speedscope with a profile file
speedscope profile.json

# Read profile from stdin
cat profile.json | speedscope -

# Show help
speedscope --help

# Show version
speedscope --version

Browser Usage

// When speedscope web app is loaded, use the global API to load profiles
window.speedscope.loadFileFromBase64('profile.json', base64Data);

Note: This global API is only available when the speedscope web application is loaded in the browser. It's primarily used internally by the CLI tool for passing profile data to the web interface.

Architecture

Speedscope is built around several key components:

• Profile Import System: Automatic format detection and parsing for 15+ profiler formats
• Data Structures: Core Profile, Frame, and ProfileGroup classes for representing profiling data
• Visualization Engine: WebGL-accelerated rendering for interactive flamecharts and timeline views
• File Format: Native .speedscope.json format with comprehensive export capabilities
• CLI Interface: Node.js-based command-line tool for launching profiles in browser
• Browser Integration: Client-side processing with no server uploads for privacy

Capabilities

Profile Import

Import and parse performance profiles from various profilers and languages. Supports automatic format detection and handles compressed data.

Note: These functions are part of speedscope's internal API and are not designed for external consumption. They are documented here for completeness and understanding of speedscope's capabilities.

function importProfileGroupFromText(
  fileName: string, 
  contents: string
): Promise<ProfileGroup | null>;

function importProfileGroupFromBase64(
  fileName: string, 
  b64contents: string
): Promise<ProfileGroup | null>;

function importProfilesFromFile(file: File): Promise<ProfileGroup | null>;

function importProfilesFromArrayBuffer(
  fileName: string, 
  buffer: ArrayBuffer
): Promise<ProfileGroup | null>;

Profile Import

Command Line Interface

Node.js CLI tool for opening profile files in the browser with automatic format detection and temporary file handling.

speedscope [filepath]                 # Open profile file
speedscope -                          # Read from stdin  
speedscope --help                     # Show help
speedscope --version                  # Show version

CLI Interface

Data Structures

Core data structures for representing performance profiles, call trees, and frame information with weight calculations.

Note: These are internal data structures used by speedscope for profile representation.

class Profile {
  getName(): string;
  setName(name: string): void;
  getWeightUnit(): FileFormat.ValueUnit;
  getTotalWeight(): number;
}

class Frame extends HasWeights {
  // Note: constructor is private, frames are created internally
  key: string | number;
  name: string;
  file?: string;
  line?: number;
  col?: number;
  getSelfWeight(): number;
  getTotalWeight(): number;
}

interface ProfileGroup {
  name: string;
  indexToView: number;
  profiles: Profile[];
}

Data Structures

File Format Export

Export profile data to speedscope's native JSON format with comprehensive metadata and event serialization.

Note: These are internal functions for profile export. The primary way to export profiles is through the web interface.

function exportProfileGroup(profileGroup: ProfileGroup): FileFormat.File;

function saveToFile(
  profileGroup: ProfileGroup, 
  fileName?: string
): void;

interface FileFormat.File {
  $schema: 'https://www.speedscope.app/file-format-schema.json';
  shared: { frames: FileFormat.Frame[] };
  profiles: FileFormat.Profile[];
  name?: string;
  activeProfileIndex?: number;
  exporter?: string;
}

File Format

Supported Formats

Speedscope automatically detects and imports from these profiler formats:

• Chrome DevTools: CPU profiles, timeline traces, heap profiles
• Firefox Profiler: Performance profiles and timeline data
• Node.js: V8 CPU profiles and heap allocations
• Ruby: stackprof and rbspy outputs
• Python: py-spy and pyinstrument profiles
• Go: pprof protobuf and text formats
• Java: async-profiler outputs
• Safari: Timeline recording files
• Linux: perf script outputs and callgrind format
• macOS: Instruments deep copy and trace files
• Custom: Collapsed stack format and trace event format

Types

interface FrameInfo {
  key: string | number;
  name: string;
  file?: string;
  line?: number;
  col?: number;
}

type SymbolRemapper = (
  frame: Frame
) => { name?: string; file?: string; line?: number; col?: number } | null;

enum FileFormat.ProfileType {
  EVENTED = 'evented',
  SAMPLED = 'sampled'
}

type FileFormat.ValueUnit = 
  | 'none' 
  | 'nanoseconds' 
  | 'microseconds' 
  | 'milliseconds' 
  | 'seconds' 
  | 'bytes';