0
# Speedscope
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: speedscope
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install speedscope`
10

11
## Core Imports
12

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

15
```bash
16
# CLI usage (primary interface)
17
npm install -g speedscope
18
speedscope profile.json
19
```
20

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

23
```typescript
24
// Global speedscope object available in browser
25
window.speedscope.loadFileFromBase64(filename: string, base64source: string): void;
26
```
27

28
**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.
29

30
## Basic Usage
31

32
### CLI Usage
33

34
```bash
35
# Open speedscope in browser with no file
36
speedscope
37

38
# Open speedscope with a profile file
39
speedscope profile.json
40

41
# Read profile from stdin
42
cat profile.json | speedscope -
43

44
# Show help
45
speedscope --help
46

47
# Show version
48
speedscope --version
49
```
50

51
### Browser Usage
52

53
```typescript
54
// When speedscope web app is loaded, use the global API to load profiles
55
window.speedscope.loadFileFromBase64('profile.json', base64Data);
56
```
57

58
**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.
59

60
## Architecture
61

62
Speedscope is built around several key components:
63

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

71
## Capabilities
72

73
### Profile Import
74

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

77
**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.
78

79
```typescript { .api }
80
function importProfileGroupFromText(
81
  fileName: string, 
82
  contents: string
83
): Promise<ProfileGroup | null>;
84

85
function importProfileGroupFromBase64(
86
  fileName: string, 
87
  b64contents: string
88
): Promise<ProfileGroup | null>;
89

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

92
function importProfilesFromArrayBuffer(
93
  fileName: string, 
94
  buffer: ArrayBuffer
95
): Promise<ProfileGroup | null>;
96
```
97

98
[Profile Import](./import.md)
99

100
### Command Line Interface
101

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

104
```bash { .api }
105
speedscope [filepath]                 # Open profile file
106
speedscope -                          # Read from stdin  
107
speedscope --help                     # Show help
108
speedscope --version                  # Show version
109
```
110

111
[CLI Interface](./cli.md)
112

113
### Data Structures
114

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

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

119
```typescript { .api }
120
class Profile {
121
  getName(): string;
122
  setName(name: string): void;
123
  getWeightUnit(): FileFormat.ValueUnit;
124
  getTotalWeight(): number;
125
}
126

127
class Frame extends HasWeights {
128
  // Note: constructor is private, frames are created internally
129
  key: string | number;
130
  name: string;
131
  file?: string;
132
  line?: number;
133
  col?: number;
134
  getSelfWeight(): number;
135
  getTotalWeight(): number;
136
}
137

138
interface ProfileGroup {
139
  name: string;
140
  indexToView: number;
141
  profiles: Profile[];
142
}
143
```
144

145
[Data Structures](./data-structures.md)
146

147
### File Format Export
148

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

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

153
```typescript { .api }
154
function exportProfileGroup(profileGroup: ProfileGroup): FileFormat.File;
155

156
function saveToFile(
157
  profileGroup: ProfileGroup, 
158
  fileName?: string
159
): void;
160

161
interface FileFormat.File {
162
  $schema: 'https://www.speedscope.app/file-format-schema.json';
163
  shared: { frames: FileFormat.Frame[] };
164
  profiles: FileFormat.Profile[];
165
  name?: string;
166
  activeProfileIndex?: number;
167
  exporter?: string;
168
}
169
```
170

171
[File Format](./file-format.md)
172

173
## Supported Formats
174

175
Speedscope automatically detects and imports from these profiler formats:
176

177
- **Chrome DevTools**: CPU profiles, timeline traces, heap profiles
178
- **Firefox Profiler**: Performance profiles and timeline data  
179
- **Node.js**: V8 CPU profiles and heap allocations
180
- **Ruby**: stackprof and rbspy outputs
181
- **Python**: py-spy and pyinstrument profiles
182
- **Go**: pprof protobuf and text formats
183
- **Java**: async-profiler outputs
184
- **Safari**: Timeline recording files
185
- **Linux**: perf script outputs and callgrind format
186
- **macOS**: Instruments deep copy and trace files
187
- **Custom**: Collapsed stack format and trace event format
188

189
## Types
190

191
```typescript { .api }
192
interface FrameInfo {
193
  key: string | number;
194
  name: string;
195
  file?: string;
196
  line?: number;
197
  col?: number;
198
}
199

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

204
enum FileFormat.ProfileType {
205
  EVENTED = 'evented',
206
  SAMPLED = 'sampled'
207
}
208

209
type FileFormat.ValueUnit = 
210
  | 'none' 
211
  | 'nanoseconds' 
212
  | 'microseconds' 
213
  | 'milliseconds' 
214
  | 'seconds' 
215
  | 'bytes';
216
```