cairo-profiler

Profiler for Cairo programming language & Starknet.

Installation

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

asdf (recommended):

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