cairo-profiler

Profiler for Cairo programming language & Starknet.

Installation

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

Starkup (recommended)

Starkup installs the tools used to develop Cairo packages and Starknet contracts.

Note

On Windows, run Starkup in WSL. Starkup supports macOS and Linux directly.

Run the installer and follow the onscreen instructions:

curl --proto '=https' --tlsv1.2 -sSf https://sh.starkup.sh | sh

asdf

asdf plugin add 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:

# in asdf <0.16.0
asdf local cairo-profiler latest
# OR
asdf global cairo-profiler latest

# or in asdf >= 0.16.0
asdf set cairo-profiler latest
# OR
asdf set -u cairo-profiler latest

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:

1. Download the release archive matching your CPU architecture.
2. 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

3. Add path to the cairo_profiler\bin directory to your PATH environment variable.
4. 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
• Scarb Execute - 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

or

cairo-profiler path/to/trace.json

📝 Note

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

Libfuncs

In order to include libfuncs nodes in the output, build profile with --show-libfuncs flag:

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

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 calls samples will be shown. This can be changed using --limit and --sample flags.

l2 gas profiling

If the trace file was generated with snforge 0.49.0+ (with sierra gas tracking enabled), an l2 gas sample will be available.

This measurement includes:

• function and syscall execution resources (i.e. used sierra gas)
• transaction calldata and signatures
• keys and data of emitted events

It does not include:

• constructor calldata (for DEPLOY_ACCOUNT transactions)
• ABI and CASM/Sierra bytecode (for DECLARE transactions)

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"

Viewing the nodes with everything from crate "core" filtered out:

cairo-profiler view path/to/profile.pb.gz --hide "^core::*"

Using pprof

Alternatively to see results from the generated file you can also use pprof. To do so, you will need to install:

• Go
• Graphviz
• pprof

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! 🔥

• 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 and cairo-run

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