cairo-profiler

Profiler for Cairo programming language & Starknet.

Installation

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 generate the input file here

Usage

Usage flow consists of two steps:

• generating the output file,
• running pprof tool.

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 --output-path <OUTPUT_PATH> - if not specified, the output file will be saved as profile.pb.gz.

Example

cairo-profiler path/to/trace.json

📝 Note

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

Running pprof

To see results from the generated file 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
• Exposing cairo-profiler library to allow other tools to integrate

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