speedscope/README.md

126 lines
6.8 KiB
Markdown
Raw Normal View History

2018-01-08 06:16:07 +03:00
# 🔬speedscope
2018-08-21 20:20:08 +03:00
A fast, interactive web-based viewer for performance profiles. An alternative viewer for [FlameGraphs][1]. Will happily display multi-megabyte profiles without crashing your browser.
2018-01-08 06:16:07 +03:00
Given raw profiling data, speedscope allows you to interactively explore the data to get insight into what's slow in your application, or allocating all the memory, or whatever data is represented in the profiling data.
![Example Profile](https://user-images.githubusercontent.com/150329/40900669-86eced80-6781-11e8-92c1-dc667b651e72.gif)
2017-12-08 10:51:15 +03:00
[0]: https://en.wikipedia.org/wiki/Profiling_(computer_programming)#Statistical_profilers
2018-01-08 06:16:07 +03:00
[1]: https://github.com/brendangregg/FlameGraph
2017-12-08 10:51:15 +03:00
# Usage
2018-07-06 12:14:34 +03:00
Visit https://www.speedscope.app, then either browse to find a profile file or drag-and-drop one onto the page. The profiles are not uploaded anywhere -- the application is totally in-browser.
2018-01-08 06:16:07 +03:00
## Command line usage
Add a CLI to load the target file in your default browser (#88) This PR add a CLI speedscope which load file given as an argument in your default browser. Expected usage looks like: ``` speedscope /path/to/profile ``` Note that since we're using base64 encoded strings as a transport for this, this won't work with multi-file profiles, like the Instruments .trace files. This could be augmented to support that by archiving the contents, but that can be handled in a different PR. This PR also set up a viable model for integrating speedscope into other projects. By replicating the contents of `cli.js` in other languages, integration should be possible in other languages with no dependency upon node in any way. Distribution should consist of just HTML, JS, and CSS assets to be loaded in browser. Test Plan: - Ran the following to simulate a publish & subsequent installation: ``` $ npm pack $ mv speedscope-0.1.0.tgz /tmp/ $ cd /tmp $ tar -xvvf speedscope-0.1.0.tgz $ cd package $ npm install --only=production $ ./cli.js Opening file:///private/tmp/package/dist/release/index.html in your default browser $ ./cli.js ~/code/speedscope/sample/profiles/Chrome/65/timeline.json Creating temp file /var/folders/l0/qtd9z14973s2tw81vmzwkyp00000gp/T/speedscope-1531023992823-3880.js Creating temp file /var/folders/l0/qtd9z14973s2tw81vmzwkyp00000gp/T/speedscope-1531023992823-3880.html Opening file:///var/folders/l0/qtd9z14973s2tw81vmzwkyp00000gp/T/speedscope-1531023992823-3880.html in your default browser ``` Fixes #24
2018-07-08 07:33:02 +03:00
For offline use, or convenience in the terminal, you can also install speedscope
via npm:
npm install -g speedscope
Invoking `speedscope /path/to/profile` will load speedscope in your default browser.
## Self-contained directory
If you don't have npm or node installed, you can also download a
self-contained version from https://github.com/jlfwong/speedscope/releases.
After you download the zip file from a release, simply unzip it and open the
contained `index.html` in Chrome or Firefox.
## Supported file formats
speedscope is designed to ingest profiles from a variety of different profilers for different programming languages & environments. Click the links below for documentation on how to import from a specific source.
- JavaScript
- [Importing from Chrome](https://github.com/jlfwong/speedscope/wiki/Importing-from-Chrome)
- [Importing from Firefox](https://github.com/jlfwong/speedscope/wiki/Importing-from-Firefox)
- [Importing from Safari](https://github.com/jlfwong/speedscope/wiki/Importing-from-Safari)
- [Importing from Node.js](https://github.com/jlfwong/speedscope/wiki/Importing-from-Node.js)
- Ruby
- [Importing from stackprof](https://github.com/jlfwong/speedscope/wiki/Importing-from-stackprof-(ruby))
- [Importing from rbspy](https://github.com/jlfwong/speedscope/wiki/Importing-from-rbspy-(ruby))
- [Importing from ruby-prof](https://github.com/jlfwong/speedscope/wiki/Importing-from-ruby-prof)
2019-10-07 00:59:17 +03:00
- Python
- [Importing from py-spy](https://github.com/jlfwong/speedscope/wiki/Importing-from-py-spy-(python))
- [pyspeedscope](https://github.com/windelbouwman/pyspeedscope)
- [Importing from Austin](https://github.com/P403n1x87/austin-python#format-conversion)
2018-09-26 23:38:36 +03:00
- Go
- [Importing from pprof](https://github.com/jlfwong/speedscope/wiki/Importing-from-pprof-(go))
- Rust
- [flamescope](https://github.com/coolreader18/flamescope)
- Native code
- [Importing from Instruments.app](https://github.com/jlfwong/speedscope/wiki/Importing-from-Instruments.app) (macOS)
- [Importing from `perf`](https://github.com/jlfwong/speedscope/wiki/Importing-from-perf-(linux)) (linux)
2019-10-16 10:15:06 +03:00
- [Importing from .NET Core](https://github.com/jlfwong/speedscope/wiki/Importing-from-.NET-Core)
2018-10-29 19:37:11 +03:00
- [Importing from GHC (Haskell)](https://github.com/jlfwong/speedscope/wiki/Importing-from-Haskell)
- [Importing from custom sources](https://github.com/jlfwong/speedscope/wiki/Importing-from-custom-sources)
2018-08-21 19:55:27 +03:00
Contributions to add support for additional formats are welcome! See issues with the ["import source" tag](https://github.com/jlfwong/speedscope/issues?q=is%3Aissue+is%3Aopen+label%3A%22import+source%22).
## Importing via URL
To load a specific profile by URL, you can append a hash fragment like `#profileURL=[URL-encoded profile URL]&title=[URL-encoded custom title]`. Note that the server hosting the profile must have CORS configured to allow AJAX requests from speedscope.
2018-01-08 06:16:07 +03:00
## Views
### 🕰Time Order
2018-08-23 18:15:59 +03:00
![Detail View](https://user-images.githubusercontent.com/150329/42108613-e6ef6d3a-7b8f-11e8-93d4-541b2cb93fe5.png)
2018-01-08 06:16:07 +03:00
2018-08-23 19:22:24 +03:00
In the "Time Order" view (the default), call stacks are ordered left-to-right in the same order as they occurred in the input file, which is usually going to be the chronological order they were recorded in. This view is most helpful for understanding the behavior of an application over time, e.g. "first the data is fetched from the database, then the data is prepared for serialization, then the data is serialized to JSON".
2018-08-23 18:15:59 +03:00
The horizontal axis represents the "weight" of each stack (most commonly CPU time), and the vertical axis shows you the stack active at the time of the sample. If you click on one of the frames, you'll be able to see summary statistics about it.
2018-01-08 06:16:07 +03:00
### ⬅Left Heavy
2018-08-23 18:15:59 +03:00
![Left Heavy View](https://user-images.githubusercontent.com/150329/44534434-a05f8380-a6ac-11e8-86ac-e3e05e577c52.png)
2018-01-08 06:16:07 +03:00
In the "Left Heavy" view, identical stacks are grouped together, regardless of whether they were recorded sequentially. Then, the stacks are sorted so that the heaviest stack for each parent is on the left -- hence "left heavy". This view is useful for understanding where all the time is going in situations where there are hundreds or thousands of function calls interleaved between other call stacks.
2017-12-08 10:51:15 +03:00
### 🥪 Sandwich
2018-08-23 18:15:59 +03:00
![Sandwich View](https://user-images.githubusercontent.com/150329/42108467-76a57baa-7b8f-11e8-815f-1df7b6ac3ede.png)
The Sandwich view is a table view in which you can find a list of all functions an their associated times. You can sort by self time or total time.
It's called "Sandwich" view because if you select one of the rows in the table, you can see flamegraphs for all the callers and callees of the selected
row.
2018-01-08 06:16:07 +03:00
## Navigation
2017-12-08 10:51:15 +03:00
2018-01-08 06:16:07 +03:00
Once a profile has loaded, the main view is split into two: the top area is the "minimap", and the bottom area is the "stack view".
2018-01-01 21:19:39 +03:00
2018-01-08 06:16:07 +03:00
### Minimap Navigation
* Scroll on either axis to pan around
* Click and drag to narrow your view to a specific range
2017-12-08 10:51:15 +03:00
2018-01-08 06:16:07 +03:00
### Stack View Navigation
* Scroll on either axis to pan around
* Pinch to zoom
* Hold Cmd+Scroll to zoom
* Double click on a frame to fit the viewport to it
* Click on a frame to view summary statistics about it
2017-12-08 10:51:48 +03:00
2018-01-08 06:16:07 +03:00
### Keyboard Navigation
* `+`: zoom in
* `-`: zoom out
* `0`: zoom out to see the entire profile
* `w`/`a`/`s`/`d` or arrow keys: pan around the profile
* `1`: Switch to the "Time Order" view
* `2`: Switch to the "Left Heavy" view
* `3`: Switch to the "Sandwich" view
* `r`: Collapse recursion in the flamegraphs
* `Cmd+S`/`Ctrl+S` to save the current profile
* `Cmd+O`/`Ctrl+O` to open a new profile
* `n`: Go to next profile/thread if one is available
* `p`: Go to previous profile/thread if one is available
* `t`: Open the profile/thread selector if available
2020-08-05 11:02:17 +03:00
* `Cmd+F`/`Ctrl+F`: to open search. While open, `Enter` and `Shift+Enter` cycle through results
2018-08-23 18:07:03 +03:00
## Contributing
Do you want to contribute to speedscope? Sweeeeet. Check out [CONTRIBUTING.md](./CONTRIBUTING.md) for instructions on setting up your dev environment.