docs/README.md

# What is Perfetto?

TIP: If you are unfamiliar with tracing or, in general, are new to the world of
performance, we suggest reading the [What is Tracing?](/docs/tracing-101.md)
page first.

Perfetto is an open-source suite of SDKs, daemons and tools which use
**tracing** and **profiling** to help developers understand the behaviour of
complex systems and root-cause functional and performance issues on client /
embedded systems.

It consists of:

- **High-performance tracing daemons** for capturing tracing information from
  many processes on a single machine into a unified trace file for offline
  analysis and visualization.
- **Low-overhead tracing SDK** for direct userspace-to-userspace tracing of
  timings and state changes of your C/C++ code. A community-maintained
  [Rust SDK](/docs/getting-started/rust-sdk.md) is also available.
- **Extensive OS-level probes on Android and Linux** for capturing wider system
  level (e.g. scheduling states, CPU frequencies, memory profiling, callstack
  sampling) context during the trace.
- **Fully local, browser-based UI** for visualizing large amounts of complex,
  interconnected data on a timeline and for exploring CPU and memory profiles
  with flamegraphs and call trees. Our UI works in all major browsers, doesn't
  require any installation, works offline, and can open traces and profiles
  recorded by other tools, such as pprof, Linux perf and simpleperf.
- **Powerful, SQL-based analysis library** for programmatically analyzing large
  amounts of complex, interconnected data on a timeline, even if it was not
  collected with Perfetto recording tooling.

![](images/perfetto-stack.svg)

## Why would you use Perfetto?

Perfetto was designed from the ground up to act as the default tracing system
for the Android OS and the Chrome Browser. As such, Perfetto is officially
supported for collecting, analysing and visualizing:

- **System traces on Android** to debug and root-cause functional and
  performance issues in the Android platform and Android apps. Perfetto is
  suited for debugging e.g. slow startups, dropped frames (jank), animation
  glitches, low memory kills, App Not Responding (ANRs) and general buggy
  behaviour.

- **ART heap dumps and native heap profiles on Android** to debug and
  root-cause high memory use in both Java/Kotlin code and C++ code respectively,
  in the Android platform and Android apps.
- **Callstack sampling profiles on Android** to debug and root-cause high CPU
  usage by C++/Java/Kotlin code in the Android platform and Android apps.
- **Chrome browser traces** to debug and root cause issues in the browser, V8,
  Blink and, in advanced usecases, in websites themselves.

Beyond these "official" usecases, Perfetto consists a highly flexible set of
tools. This makes it capable of being used as a general purpose tracing system,
a performance data analyzer or a timeline visualizer. The Perfetto team
dedicates a portion of their time to supporting these cases, albeit at a
reduced level of support.

Other usecases Perfetto is commonly used for include:

- **Collecting, analysing and visualizing in-app traces** to debug functional
  and performance issues in C/C++ and Rust apps and libraries on Windows,
  macOS and Linux-based embedded systems.
- **Collecting, analysing and visualizing system traces on Linux** to debug
  kernel issues via ftrace, scheduling latency or IPCs between processes.
- **Collecting, analysing and visualizing heap profiles on Linux** to debug high
  memory usage of C/C++/Rust apps and libraries.
- **Viewing and analysing CPU profiles from other profilers** such as pprof,
  Linux perf and simpleperf, to optimize CPU usage of apps and libraries in
  any language. See
  [Viewing CPU Profiles](/docs/getting-started/viewing-cpu-profiles.md).
- **Analyze and visualize a wide range of profiling and tracing formats.**
  Perfetto can open traces and profiles from various other tools, allowing you
  to use the Perfetto UI and its SQL-based query engine on many data sources,
  including:
  - _pprof_
  - _Chrome JSON format_
  - _Firefox Profiler JSON format_
  - _Linux perf (binary and text formats)_
  - _Android simpleperf_
  - _Collapsed stacks (Brendan Gregg's FlameGraph format)_
  - _Linux ftrace text format_
  - _macOS Instruments_
  - _Fuchsia tracing format_
- **Analysing and visualizing arbitrary "trace-like" data**. The Perfetto
  analysis and visualization tools can be used on any "trace-like" data (e.g.
  data with a timestamp and some payload) as long as it can be converted to the
  Perfetto protobuf format; the possibilities are only limited by creativity!

## Why would you **not** use Perfetto?

There are several types of problems Perfetto is either not designed for or is
explicitly unsupported.

- **Recording traces for distributed / server systems**

  - Perfetto is **not** a distributed tracer in the vein of OpenTelemetry,
    Jaeger, Datadog. Perfetto's recording tools are entirely for recording
    client side traces, especially at the system level. Our team believes that
    the space of distributed/server tracing is well covered by the
    aforementioned projects, unlike client side systems like Android and
    Linux/embedded systems.
  - However, the Perfetto UI **can** be used to visualize distributed traces if
    traces are converted to a format that Perfetto supports. In fact, this is
    commonly done inside Google.

- **Recording system traces on Windows or macOS**

  - Perfetto's recording tools do **not** integrate with any system level data
    sources on Windows or macOS.
  - However, Perfetto _can_ be used to analyse and visualize macOS traces
    collected with Instruments as we natively support the Instruments XML
    format.

- **Consuming traces on the critical path**

  - Perfetto's producer code is optimized for low-overhead trace writing but the
    consumer side is _not_ optimized for low-latency readback.
  - This means it is _not_ advised to use Perfetto for situations where you want
    end-to-end low-latency tracing.

- **Recording traces with the lowest overhead possible**

  - Perfetto SDK makes no claims on being the fastest possible way to record
    traces: we are well aware that there will be libraries and tools out there
    which can capture traces with less overhead. You can beat our tracing SDK by
    recording fixed-sized events in a shmem ring buffer bumping atomic pointers.
  - Instead, Perfetto's recording libraries and daemons focus on having a good
    trade-off between performance, flexibility and security of tracing.
  - For example, Perfetto supports arbitrary sized events (e.g. high res
    screenshots), coordinating multi-process tracing, concurrent tracing
    sessions with different configs, dynamic buffer multiplexing, arbitrarily
    nested key-value **arguments** attached to trace events, dynamic string
    interning, **flows** for linking trace events together and **dynamic trace
    event names** which many other low-overhead tracing systems do not support.
  - However, the Perfetto UI _can_ be used to visualize traces recorded with
    non-Perfetto tools if those traces can be converted to the Perfetto protobuf
    format or some other format we support natively e.g. _Chrome JSON_,
    _Fuchsia_ etc.

- **Recording, analysing or visualizing GPU traces for games**

  - Tracing and profiling of games is very different world to tracing general
    purpose software for many reasons: the orientation of the whole system
    around "frames", the heavy focus on the GPU and its utilization, the
    presence of game engines and the need to integrate with them.
  - Due to Perfetto not having any specialized focus on the things game
    developers care heavily about, we feel like Perfetto is not well suited to
    this task.
  - We have some support for GPU render stages and GPU counters recording on
    Android, but these features are better supported by
    [Android GPU Inspector](https://gpuinspector.dev) (which under the hoods
    uses Perfetto as one of its data sources).

## How do I get started using Perfetto?

We appreciate that Perfetto has a lot of parts to it so it can be confusing to
someone new to the project to know what is relevant to them. For this reason, we
have a whole page dedicated to this:
[How do I start using Perfetto?](/docs/getting-started/start-using-perfetto.md)

## {#who-uses-perfetto} Who uses Perfetto today?

Perfetto is the **default tracing system** for the **Android operating system**
and the **Chromium browser**. As such, Perfetto is utilized extensively by these
teams in Google, both to proactively identify performance improvements and
reactively to debug/root-cause issues locally, in the lab and even from the
field.

There are also many other teams in Google who use Perfetto in diverse ways. This
includes including "non-traditional" uses of a tracing system. Perfetto has also
been used and adopted widely in the wider industry by many other companies.

The following is a non-exhaustive list of public mentions of Perfetto in blog
posts, articles and videos:

- [Diagnosing performance issues in .NET applications with dotnet-trace and Perfetto](https://dfamonteiro.com/posts/using-dotnet-trace-with-perfetto/)
- [Google IO 2023 - What's new in Dart and Flutter](https://youtu.be/yRlwOdCK7Ho?t=798)
- [Google IO 2023 - Debugging Jetpack Compose](https://youtu.be/Kp-aiSU8qCU?t=1092)
- [Performance: Perfetto Traceviewer - MAD Skills](https://www.youtube.com/watch?v=phhLFicMacY)
  "On this episode of the MAD Skills series on Performance, Android Performance
  Engineer Carmen Jackson discusses the Perfetto traceviewer, an alternative to
  Android Studio for viewing system traces."
- [Performance and optimisation on the Meta Quest Platform](https://m.facebook.com/RealityLabs/videos/performance-and-optimization-on-meta-quest-platform/488126049869673/)
- [Performance testing through proportional traces ](https://www.jviotti.com/2022/09/07/performance-testing-through-proportional-traces.html)
- [Performance](https://www.twoscomplement.org/podcast/performance.mp3) An
  episode of the
  [Twoscomplement podcast](https://www.twoscomplement.org/#podcast) "Our most
  efficient podcast ever. Ben and Matt talk performance testing and optimization
  in fewer than 30 minutes."
- [Collabora: Profiling virtualized GPU acceleration with Perfetto](https://www.collabora.com/news-and-blog/blog/2021/04/22/profiling-virtualized-gpu-acceleration-with-perfetto/)
- [Snap: Client Tracing at Scale](https://www.droidcon.com/2022/06/28/client-tracing-at-scale/)
  "With the wide range of Android devices, it can be difficult to find the root
  cause of performance problems. By leveraging traces, we can begin to
  understand the exact circumstances that led to a poor user experience. We will
  discuss how we instrument our Snapchat app such that we can have the necessary
  signals for explainability. Additionally, we will describe how we incorporate
  tracing into our development process from local debugging, to performance
  tests and finally in production."
- [Microsoft: Perfetto tooling for analyzing Android, Linux, and Chromium browser performance](https://devblogs.microsoft.com/performance-diagnostics/perfetto-tooling-for-analyzing-android-linux-and-chromium-browser-performance-microsoft-performance-tools-linux-android/)
- [Mesa 3D](https://docs.mesa3d.org/perfetto.html) embeds Perfetto in some of
  its drivers for GPU counter and render stage monitoring.
- [JaneStreet's MagicTrace](https://blog.janestreet.com/magic-trace/) A tool
  based on Perfetto to record and visualize Intel Processor traces.

## Where do I find more information and get help with Perfetto?

For our source code and project home:
[GitHub](https://github.com/google/perfetto)

For Q/A:

- [GitHub Discussions](https://github.com/google/perfetto/discussions/categories/q-a)
  or our
  [public mailing list](https://groups.google.com/forum/#!forum/perfetto-dev).
- **Googlers**: use [YAQS](https://go/perfetto-yaqs) or our
  [internal mailing list](http://go/perfetto-dev).

For bugs affecting any part of Perfetto **except** Chrome tracing:

- [GitHub issues](https://github.com/google/perfetto/issues).
- **Googlers**: use the internal bug tracker
  [go/perfetto-bugs](http://goto.google.com/perfetto-bugs)

For bugs affecting Chrome Tracing:

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

For chatting directly with the Perfetto team:

- Use [Discord](https://discord.gg/35ShE3A)
- **Googlers**: Thank you for contacting us. All our lines are currently busy.
  Your message is important to us, and an operator will get back to you as soon
  as possible. If your enquiry is truly urgent see
  [this page](http://go/perfetto-project).

Perfetto follows
[Google's Open Source Community Guidelines](https://opensource.google/conduct/).

Community projects:

🇨🇳 A community-maintained Chinese translation of the Perfetto docs is available at
[gugu-perf.github.io/perfetto-docs-zh-cn](https://gugu-perf.github.io/perfetto-docs-zh-cn).