Awesome

cairo-profiler

Profiler for Cairo programming language & Starknet.

Example output

Installation

You can install cairo-profiler using asdf or the installation script.

asdf (recommended):

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

script:

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

Installation on Windows

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

External tools integration

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.

Integrated tools

Starknet Foundry - check how to use it with cairo-profiler here

Usage

Usage flow consists of two steps:

generating the output file
viewing the generated profile

Generating output file

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.

Example

cairo-profiler build-profile path/to/trace.json

cairo-profiler path/to/trace.json

📝 Note

Trace needs to be in the correct format. See trace.json as an example.

Viewing profile

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 to build-profile subcommand

By default, the top 10 steps samples will be shown. This can be changed using --limit and --sample flags.

Examples:

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"

Using pprof

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.

Roadmap

cairo-profiler is under active development! Expect a lot of new features to appear soon! 🔥

Development

Environment setup

You need to install: Rust, Go, protoc, pprof and Graphviz.

Running the binary

The binary can be run with:

cargo run <PATH_TO_TRACE_DATA>

Running tests

Tests can be run with:

cargo test

Formatting and lints

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

Spelling

cairo-profiler uses typos for spelling checks.

You can run the checker with

typos

Some typos can be automatically fixed by running

typos -w