Contributing to Perfetto

Quickstart

Follow those steps if you are new to contributing to Perfetto.

Setup

Prerequisites: git and python3.

# Clone the Perfetto repo and enter the directory
git clone https://github.com/google/perfetto.git
cd perfetto

# Install dependencies
tools/install-build-deps

# Setup all build configs
tools/setup_all_configs.py

Building

On Linux

# Production build
tools/ninja -C out/linux_clang_release

# Debug build
tools/ninja -C out/linux_clang_debug

On Mac

# Production build
tools/ninja -C out/mac_release

# Debug build
tools/ninja -C out/mac_debug

# Build the UI
ui/build

# Run the dev server
ui/run_dev_server

For more information on building Perfetto go to build instructions.

Contributing

NOTE: In March 2025 our team has moved the primary development of Perfetto to GitHub (previously on Android Gerrit).

Googlers

NOTE: Follow the instructions at go/perfetto-github-instructions.

Make sure you/your organization has signed the Google CLA at cla.developers.google.com
Create a branch with the change:

git checkout -b first-contribution

Make change in the repo.
Add, commit and upload the change:

git add .
git commit -m "My first contribution"
gh pr create  # Requires cli.github.com

Please note our project follows the Google C++ style, and targets -std=c++17.

External contributors

Please contribute the same way as you would to any other Github repository. A good explanation of how to do it can be found here.

Testing

As Perfetto has a rather complicated testing strategy, we will automatically run our presubmit on each push into the repo. For manual run: tools/run_presubmit.

For more information on testing Perfetto go to testing page.

What's next?

You might want to contribute to the UI, Trace Processor, SDK or various data importers.

If you want to add a new functionality to the UI, most likely the next step is the UI getting started.
If you want to edit the core functionality of the UI: it's a much bigger change which would require in depth understanding of Perfetto UI. Most requests/bugs now are related to various plugins, not the core.
If you want to add a new ftrace event take a look at common tasks page.
If you want to add a new table/view/function to Perfetto SQL standard library you need to first undestand the Perfetto SQL syntax, and then read the details of updating the standard library at common tasks page.
If you want to add a support of a new file type into Perfetto, you need to add a new importer to Trace Processor C++ code.

Communication

Contact

Our main communication channel is our mailing list: https://groups.google.com/forum/#!forum/perfetto-dev.

You can also reach us on our Discord channel but our support there is best effort only.

This project follows Google's Open Source Community Guidelines.

Bugs

For bugs affecting Android or the tracing internals:

Googlers: use the internal bug tracker go/perfetto-bugs
Non-Googlers: use GitHub issues.

For bugs affecting Chrome Tracing:

Use http://crbug.com Component:Speed>Tracing label:Perfetto.

Contributor License Agreement

Contributions to this project must be accompanied by a Contributor License Agreement. You (or your employer) retain the copyright to your contribution; this simply gives us permission to use and redistribute your contributions as part of the project. Head over to https://cla.developers.google.com/ to see your current agreements on file or to sign a new one.

You generally only need to submit a CLA once, so if you've already submitted one (even if it was for a different project), you probably don't need to do it again.