lightswitch

lightswitch is a profiler as a library for Linux suitable for on-demand and continuous on-CPU profiling. It's written in Rust with sprinkles of C for eBPF. Currently C, C++, Rust, Zig, and Go are fully supported on x86_64 and arm64.

Features / design goals

• Minimal overhead: currently targeting 3% CPU utilization and 500MB of memory.
• Works without frame pointers: no need to recompile code.
• Detailed metrics: no more guessing around if profiles are broken and why.
• Support for deeper process stacks: by using a bespoke unwinding implementation and not relying on PERF_SAMPLE_STACK_USER.
• Support for modern kernels: (>=5.15), released approximately 4y ago.
• Automatic selection of BPF features: to run faster and more accurately in newer kernels.

Installation

Download and install the latest release for your architecture with:

$ curl https://raw.githubusercontent.com/javierhonduco/lightswitch/refs/heads/main/install.sh | bash

Usage

As a CLI, lightswitch can be run with:

$ sudo lightswitch

Stop it with Ctrl+C, or alternatively, pass a --duration in seconds. By default, a flamegraph in SVG format will be written to disk. Pprof, Firefox Profiler, and Perfetto traces are also supported with --profile-format=pprof, --profile-format=firefox, and --profile-format=perfetto, respectively. Completed Firefox and Perfetto profiles can be visualized with lightswitch server. The server automatically selects firefox-profiler.json or profile.pftrace when exactly one exists, or accepts another path with --profile <PROFILE>. By default the whole machine will be profiled, which can be overridden with --pids.

For example, open the default completed profile in its native web viewer with:

$ lightswitch server

Development

We use nix for the development environment and the building system. It can be installed with the official installer (make sure to enable support for flakes) or with the Determinate Systems installer. Once nix is installed, you can

• start a developer environment with nix develop and then you'll be able to build the project with cargo with cargo build. This might take a little while the first time.
• generate a container image nix build .#container will write a symlink to the container image to ./result.

Building

# after running `nix develop`
$ cargo build # use `--release` to get an optimized build
$ sudo ./target/debug/lightswitch # or ./target/release for optimized builds

Running tests

# after running `nix develop`
$ cargo test

Running kernel tests

$ nix run .#vmtest

Live mode

Run with --live to view a live flamegraph in the terminal (powered by flamelens):

$ sudo lightswitch --live --pids $(pidof myapp)

Key bindings

Flamegraph

Reporting bugs

Please share which version / revision you are running, the arguments you used, the output of lightswitch system-info and if relevant, the logs with --logging=debug. If you suspect there is a bug in the unwinders, adding --bpf-logging and sharing the output from bpftool prog tracelog or /sys/kernel/debug/tracing/trace_pipe will be very helpful.

Project status

lightswitch is in active development and the main focus is to provide a low-overhead profiler with excellent UX. A more comprehensive roadmap will be published. Feedback is greatly appreciated.