tessl/npm-speedscope

A fast, interactive web-based viewer for performance profiles with support for multiple profiler formats

—

Pending

Overview

Eval results

Files

Profile Import

Name: tessl/npm-speedscope
Author: tessl

Core profile importing functionality supporting automatic format detection and parsing for 15+ profiler formats from various programming languages and environments.

Capabilities

Main Import Functions

Primary entry points for importing profile data from different sources.

/**
 * Import profile from text content with automatic format detection
 * @param fileName - Name of the profile file for format detection
 * @param contents - Raw text content of the profile
 * @returns Promise resolving to ProfileGroup or null if format unsupported
 */
function importProfileGroupFromText(
  fileName: string,
  contents: string
): Promise<ProfileGroup | null>;

/**
 * Import profile from base64-encoded data
 * @param fileName - Name of the profile file for format detection
 * @param b64contents - Base64-encoded profile data
 * @returns Promise resolving to ProfileGroup or null if format unsupported
 */
function importProfileGroupFromBase64(
  fileName: string,
  b64contents: string
): Promise<ProfileGroup | null>;

/**
 * Import profile from browser File object
 * @param file - File object containing profile data
 * @returns Promise resolving to ProfileGroup or null if format unsupported
 */
function importProfilesFromFile(file: File): Promise<ProfileGroup | null>;

/**
 * Import profile from ArrayBuffer
 * @param fileName - Name of the profile file for format detection
 * @param buffer - ArrayBuffer containing profile data
 * @returns Promise resolving to ProfileGroup or null if format unsupported
 */
function importProfilesFromArrayBuffer(
  fileName: string,
  buffer: ArrayBuffer
): Promise<ProfileGroup | null>;

/**
 * Import profiles from FileSystem Directory Entry (for Instruments traces)
 * @param entry - FileSystemDirectoryEntry containing trace data
 * @returns Promise resolving to ProfileGroup or null if import fails
 */
function importFromFileSystemDirectoryEntry(
  entry: FileSystemDirectoryEntry
): Promise<ProfileGroup | null>;

Usage Examples:

import { 
  importProfileGroupFromText,
  importProfilesFromFile,
  importProfileGroupFromBase64 
} from 'speedscope/dist/import';

// Import from text content
const textProfile = await importProfileGroupFromText(
  'profile.stackprof.json',
  jsonString
);

// Import from File object (browser file input)
const fileInput = document.querySelector('input[type="file"]');
const file = fileInput.files[0];
const fileProfile = await importProfilesFromFile(file);

// Import from base64 data
const base64Profile = await importProfileGroupFromBase64(
  'profile.chrome.json',
  base64String
);

Chrome DevTools Import

Import profiles from Chrome DevTools performance panel and CPU profiler.

/**
 * Import from Chrome CPU profile format
 * @param profile - Chrome CPU profile object
 * @returns Profile instance or null
 */
function importFromChromeCPUProfile(profile: any): Profile | null;

/**
 * Import from Chrome Timeline trace format
 * @param events - Array of trace events or timeline object
 * @param fileName - Optional filename for profile naming
 * @returns ProfileGroup or null
 */
function importFromChromeTimeline(
  events: any[] | any,
  fileName?: string
): ProfileGroup | null;

/**
 * Import from legacy V8 CPU profile format
 * @param profile - Old V8 CPU profile object
 * @returns Profile instance or null
 */
function importFromOldV8CPUProfile(profile: any): Profile | null;

/**
 * Import from Chrome heap profile format
 * @param profile - Chrome heap profile object
 * @returns Profile instance or null
 */
function importFromChromeHeapProfile(profile: any): Profile | null;

/**
 * Check if data matches Chrome Timeline format
 * @param data - Data to check
 * @returns Boolean indicating if data is Chrome Timeline
 */
function isChromeTimeline(data: any): boolean;

/**
 * Check if data matches Chrome Timeline object format
 * @param data - Data to check
 * @returns Boolean indicating if data is Chrome Timeline object
 */
function isChromeTimelineObject(data: any): boolean;

V8 Profiler Import

Import profiles from V8 JavaScript engine profiler outputs.

/**
 * Import from V8 --prof-process log format
 * @param profile - V8 profiler log object
 * @returns Profile instance or null
 */
function importFromV8ProfLog(profile: any): Profile | null;

Ruby Profiler Import

Import profiles from Ruby profiling tools.

/**
 * Import from Ruby stackprof format
 * @param profile - Stackprof profile object
 * @returns Profile instance or null
 */
function importFromStackprof(profile: any): Profile | null;

Firefox Profiler Import

Import profiles from Firefox Developer Tools profiler.

/**
 * Import from Firefox profiler format
 * @param profile - Firefox profile object
 * @returns Profile instance or null
 */
function importFromFirefox(profile: any): Profile | null;

macOS Instruments Import

Import profiles from macOS Instruments application.

/**
 * Import from Instruments deep copy text format
 * @param contents - Instruments deep copy text content
 * @returns Profile instance or null
 */
function importFromInstrumentsDeepCopy(contents: any): Profile | null;

/**
 * Import from Instruments trace directory
 * @param entry - FileSystemDirectoryEntry of trace directory
 * @returns Promise resolving to ProfileGroup or null
 */
function importFromInstrumentsTrace(
  entry: FileSystemDirectoryEntry
): Promise<ProfileGroup | null>;

Go pprof Import

Import profiles from Go's pprof profiler.

/**
 * Import from protobuf-encoded pprof format
 * @param buffer - ArrayBuffer containing pprof data
 * @returns Profile instance or null
 */
function importAsPprofProfile(buffer: ArrayBuffer): Profile | null;

Linux Perf Import

Import profiles from Linux perf tools.

/**
 * Import from Linux perf script output
 * @param contents - Perf script text content
 * @returns ProfileGroup or null
 */
function importFromLinuxPerf(contents: any): ProfileGroup | null;

Collapsed Stack Format Import

Import profiles from collapsed stack format (used by FlameGraph tools).

/**
 * Import from collapsed stack format
 * @param contents - Collapsed stack text content
 * @returns Profile instance or null
 */
function importFromBGFlameGraph(contents: any): Profile | null;

Safari Profiler Import

Import profiles from Safari Web Inspector.

/**
 * Import from Safari timeline recording format
 * @param profile - Safari recording object
 * @returns Profile instance or null
 */
function importFromSafari(profile: any): Profile | null;

Additional Format Support

Support for various other profiler formats.

/**
 * Import from Callgrind profile format
 * @param contents - Callgrind profile content
 * @param fileName - Profile filename
 * @returns ProfileGroup or null
 */
function importFromCallgrind(contents: any, fileName: string): ProfileGroup | null;

/**
 * Import from Haskell GHC JSON profile format
 * @param profile - Haskell profile object
 * @returns ProfileGroup or null
 */
function importFromHaskell(profile: any): ProfileGroup | null;

/**
 * Import from Papyrus profile format
 * @param contents - Papyrus profile content
 * @returns Profile instance or null
 */
function importFromPapyrus(contents: any): Profile | null;

/**
 * Import from PMC stat callgraph format
 * @param contents - PMC stat callgraph content
 * @returns Profile instance or null
 */
function importFromPMCStatCallGraph(contents: any): Profile | null;

/**
 * Import from Trace Event Format
 * @param profile - Trace event format object
 * @returns ProfileGroup or null
 */
function importTraceEvents(profile: any): ProfileGroup | null;

/**
 * Check if data matches Trace Event Format
 * @param data - Data to check
 * @returns Boolean indicating if data is Trace Event Format
 */
function isTraceEventFormatted(data: any): boolean;

Format Detection

Speedscope uses a two-pass detection system:

Filename-based detection: Checks file extensions and naming patterns
Content-based detection: Analyzes file structure and properties

Supported File Patterns

.speedscope.json - Native speedscope format
.chrome.json, Profile-*.json, Trace-*.json - Chrome formats
.stackprof.json - Ruby stackprof
.instruments.txt - Instruments deep copy
.linux-perf.txt - Linux perf output
.collapsedstack.txt - Collapsed stack format
.v8log.json - V8 profiler log
.heapprofile - Chrome heap profiles
-recording.json - Safari profiles
callgrind.* - Callgrind format
.pmcstat.graph - PMC stat format

Types

interface ProfileDataSource {
  name(): Promise<string>;
  readAsArrayBuffer(): Promise<ArrayBuffer>;
  readAsText(): Promise<TextProfileDataSource>;
}

class TextProfileDataSource {
  constructor(fileName: string, contents: string);
  parseAsJSON(): any;
  firstChunk(): string;
}

class MaybeCompressedDataReader implements ProfileDataSource {
  static fromFile(file: File): MaybeCompressedDataReader;
  static fromArrayBuffer(fileName: string, buffer: ArrayBuffer): MaybeCompressedDataReader;
}

Install with Tessl CLI