Profiler for Cairo programming language & Starknet.
You can install cairo-profiler
using asdf
or the installation script.
asdf plugin add cairo-profiler https://github.com/software-mansion/asdf-cairo-profiler
asdf install cairo-profiler latest # Replace 'latest' with a specific version number if needed
Please remember to set global/project version to use:
asdf global cairo-profiler 0.7.0
# or
asdf local cairo-profiler 0.7.0
To install the latest stable version of cairo-profiler
, run:
curl -L https://raw.githubusercontent.com/software-mansion/cairo-profiler/main/scripts/install.sh | sh
If you want to install a specific a version, run the following command with the requested version:
curl -L https://raw.githubusercontent.com/software-mansion/cairo-profiler/main/scripts/install.sh | sh -s -- v0.1.0
As for now, cairo-profiler
on Windows needs manual installation, but necessary steps are kept to minimum:
- Download the release archive matching your CPU architecture.
- Extract it to a location where you would like to have
cairo-profiler
installed. A folder named cairo_profiler in your%LOCALAPPDATA%\Programs
directory will suffice:
%LOCALAPPDATA%\Programs\cairo_profiler
- Add path to the cairo_profiler\bin directory to your PATH environment variable.
- Verify installation by running the following command in new terminal session:
cairo-profiler --version
cairo-profiler
is a tool-agnostic profiler which means that it accepts input from any tool. Those tools need to generate
trace in the expected format.
- Starknet Foundry - check how to use it with
cairo-profiler
here
Usage flow consists of two steps:
- generating the output file
- viewing the generated profile
To generate the file run cairo-profiler
with the <PATH_TO_TRACE_DATA>
argument containing
the path to the json file with the trace to be profiled. You can also specify the path to the output file via --output-path <OUTPUT_PATH>
-
if not specified, the output file will be saved as profile.pb.gz
.
cairo-profiler build-profile path/to/trace.json
or
cairo-profiler path/to/trace.json
📝 Note
Trace needs to be in the correct format. See trace.json as an example.
You can use the cairo-profiler
to see the results from the generated file. The information will be printed in top
view, closely mimicking pprof
output. There are two ways to view the profile:
- by using
view
subcommand on previously generated profile file - by adding
--view
flag tobuild-profile
subcommand
By default, the top 10 steps
samples will be shown. This can be changed using --limit
and --sample
flags.
Viewing directly after building the profile:
cairo-profiler build-profile path/to/trace.json --view
Viewing the previously built profile:
cairo-profiler view path/to/profile.pb.gz
Viewing all the available samples in the profile:
cairo-profiler view path/to/profile.pb.gz --list-samples
Viewing the top 2 nodes for "range check builtin" sample:
cairo-profiler view path/to/profile.pb.gz --sample "range check builtin" --limit 2
Showing nodes accounting for 37 range check builtin, 92.50% of 40 range check builtin total
Showing top 2 nodes out of 14
flat | flat% | sum% | cum | cum% |
------------------------+--------+--------+------------------------+---------+-----------------------------------------------------------------------
22 range check builtin | 55.00% | 55.00% | 40 range check builtin | 100.00% | "Contract: SNFORGE_TEST_CODE\nFunction: SNFORGE_TEST_CODE_FUNCTION\n"
15 range check builtin | 37.50% | 92.50% | 15 range check builtin | 37.50% | "CallContract"
Alternatively to see results from the generated file you can also use pprof
. To do so, you will need to install:
and run:
go tool pprof -http=":8000" profile.pb.gz
This command will start a web server at the specified port that provides an interactive interface. You can learn more about pprof usage options here.
cairo-profiler
is under active development! Expect a lot of new features to appear soon! 🔥
- Starknet calls profiling:
- L2 resources - steps, memory holes, builtins, syscalls
- L1 resources - contract updates, L2 -> L1 messages
- Function level profiling:
- Steps profiling
- Builtins profiling
- Memory holes profiling
- Information about inlined functions
- Integrating with other tools:
- Exposing
cairo-profiler
library to allow other tools to integrate - Integrating with
snforge
- Integrating with
cairo-test
andcairo-run
- Exposing
You need to install: Rust, Go, protoc, pprof and Graphviz.
The binary can be run with:
cargo run <PATH_TO_TRACE_DATA>
Tests can be run with:
cargo test
cairo-profiler
uses rustfmt for formatting. You can run the formatter with:
cargo fmt
For linting, it uses clippy. You can run it using our defined alias:
cargo lint
cairo-profiler
uses typos for spelling checks.
You can run the checker with
typos
Some typos can be automatically fixed by running
typos -w