mstange/samply — 4.5k★ on GitHub (Rust). Command-line sampling profiler for macOS, Linux, and Windows
Snapshot summary built from the project's own GitHub metadata — there's no written TopGit review yet. The page will update automatically when a full review is published.
WHY NO REVIEW YET
TopGit writes full reviews for the most-starred, most-requested repositories. This page is a snapshot until then — see the READ ME tab for the original README in full.
samply is a command line CPU profiler which uses the Firefox profiler as its UI.
samply works on macOS, Linux, and Windows.
In order to profile the execution of ./my-application, prepend samply record to the command invocation:
samply record ./my-application my-arguments
On Linux, samply uses perf events. You can grant temporary access by running:
echo '-1' | sudo tee /proc/sys/kernel/perf_event_paranoid
On Windows, you can use samply record -a to record all processes. The Microsoft Symbol Server is pre-configured in the config file, so you get symbols for Windows libraries out of the box. You can add more symbol servers either in the config file or on the command line. Here's a command which adds symbols for Firefox and Chrome:
samply record -a --breakpad-symbol-server https://symbols.mozilla.org/try/ --windows-symbol-server https://chromium-browser-symsrv.commondatastorage.googleapis.com
Installation
You have the following options to install samply:
Install prebuilt binaries via shell script
macOS/Linux:
curl --proto '=https' --tlsv1.2 -LsSf https://github.com/mstange/samply/releases/download/samply-v0.13.1/samply-installer.sh | sh
git clone https://github.com/mstange/samply
cd samply
cargo build --release
./target/release/samply ...
Description
samply record ./my-application my-arguments
This spawns ./my-application my-arguments in a subprocess and records a profile of its execution. When the command finishes, samply opens
profiler.firefox.com in your default browser, loads the recorded profile in it, and starts a local webserver which serves symbol information and source code.
Then you can inspect the profile. And you can upload it.
Here's an example: https://share.firefox.dev/3j3PJoK
This is a profile of dump_syms, running on macOS, recorded as follows:
samply record ./dump_syms ~/mold-opt-libxul.so > /dev/null
You can see which functions were running for how long. You can see flame graphs and timelines. You can double-click functions in the call tree to open the source view, and see which lines of code were sampled how many times.
All data is kept locally (on disk and in RAM) until you choose to upload your profile.
samply is a sampling profiler and collects stack traces, per thread, at some sampling interval (the default 1000Hz, i.e. 1ms). On macOS and Windows, both on- and off-cpu samples are collected (so you can see under which stack you were blocking on a lock, for example). On Linux, only on-cpu samples are collected at the moment.
On Linux, samply needs access to performance events system for unprivileged users. For this, you can either:
Grant access until reboot:
echo '1' | sudo tee /proc/sys/kernel/perf_event_paranoid
Grant access more permanently:
sudo sysctl kernel.perf_event_paranoid=1
If using Linux 5.8 or later, you can try setting the CAP_PERFMON capability as effective and permitted for samply, though people have reported mixed results with this approach:
sudo setcap 'cap_perfmon+ep' `which samply`
If you still get a mmap failed error (an EPERM), you might also need to increase the mlock limit, e.g.:
sudo sysctl kernel.perf_event_mlock_kb=2048
Symbols and configuration
Symbol servers can be configured in the config file at ~/.config/samply/config.toml (%APPDATA%\samply\config.toml on Windows). You can also specify the maximum size of the symbol cache and of the profile store.
By default, the profiles produced by samply record and samply import are stored in ~/.local/share/samply/profiles/ (%LOCALAPPDATA%\samply\profiles\ on Windows).
Examples
Here's a profile from samply record rustup check: https://share.firefox.dev/3hteKZZ
Turn on debug info for full stacks
If you profile Rust code, make sure to profile a binary which was compiled in release mode and with debug info. This will give you inline stacks and a working source code view.
The best way is the following:
Create a global cargo profile called profiling, see below how.
Compile with cargo build --profile profiling.
Record with samply record ./target/profiling/yourrustprogram.
To create the profiling cargo profile, create a text file at ~/.cargo/config.toml with the following content:
Similar advice applies to other compiled languages. For C++, you'll want to make sure the -g flag is included in the compiler invocation.
Known issues
On macOS, samply cannot profile system commands, such as the sleep command or system python. This is because system executables are signed in such a way that they block the DYLD_INSERT_LIBRARIES environment variable, which breaks samply's ability to siphon out the mach_port of the process.
But you can profile any binaries that you've compiled yourself, or which are unsigned or locally-signed (such as anything installed by cargo install or by Homebrew). In order to attach to running processes on macOS, run samply setup once (and every time samply is updated) self-sign the samply binary.
License
Licensed under either of
Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)
at your option.
Unless you explicitly state otherwise, any contribution intentionally submitted
for inclusion in the work by you, as defined in the Apache-2.0 license, shall be
dual licensed as above, without any additional terms or conditions.
No homepage URL was recorded for mstange/samply in TopGit's last sync. The README tab above frequently contains screenshots and demo links, or check the repository description on GitHub.
Is mstange/samply open source?
Yes — mstange/samply ships under the Apache-2.0 license, which makes its source code freely readable (and, depending on license terms, forkable and reusable). Source: github.com/mstange/samply.
What is mstange/samply?
mstange/samply (mstange/samply) is a Rust project on GitHub. From the project's own README: Command-line sampling profiler for macOS, Linux, and Windows
What license does mstange/samply use?
mstange/samply is released under the Apache-2.0 license. Always verify the LICENSE file directly on GitHub for the authoritative terms — license strings can be edited out of sync with a project's actual stance.
Where do I read more about mstange/samply?
This TopGit page is a snapshot — the READ ME tab shows the project's own README content (links stripped, images preserved). The GitHub repository at github.com/mstange/samply is the definitive source.
Read full README in the tab above.
Want a second opinion on samply?
Ask an AI that can read this page — one click and you get its take on samply.