# Perfetto - System profiling, app tracing and trace analysis Perfetto is a production-grade open-source stack for performance instrumentation and trace analysis. It offers services and libraries for recording system-level and app-level traces, native + java heap profiling, a library for analyzing traces using SQL and a web-based UI to visualize and explore multi-GB traces.  ## Recording traces At its core, Perfetto introduces a novel userspace-to-userspace [tracing protocol](/docs/design-docs/api-and-abi.md#tracing-protocol-abi) based on direct protobuf serialization onto a shared memory buffer. The tracing protocol is used both internally for the built-in data sources and exposed to C++ apps through the [Tracing SDK](/docs/instrumentation/tracing-sdk.md) and the [Track Event Library](/docs/instrumentation/track-events.md). This new tracing protocol allows dynamic configuration of all aspects of tracing through an extensible protobuf-based capability advertisement and data source configuration mechanism (see [Trace configuration docs](/docs/concepts/config.md)). Different data sources can be multiplexed onto different subsets of user-defined buffers, allowing also streaming of [arbitrarily long traces](/docs/concepts/config.md#long-traces) into the filesystem. ### System-wide tracing on Android and Linux On Linux and Android, Perfetto bundles a number of data sources that are able to gather detailed performance data from different system interfaces. For the full sets and details see the _Data Sources_ section of the documentation. Some examples: * [Kernel tracing](/docs/data-sources/cpu-scheduling.md): Perfetto integrates with [Linux's ftrace][ftrace] and allows to record kernel events (e.g scheduling events, syscalls) into the trace. * [/proc and /sys pollers](/docs/data-sources/memory-counters.md), which allow to sample the state of process-wide or system-wide cpu and memory counters over time. * Integration with Android HALs modules for recording [battery and energy-usage counters](/docs/data-sources/battery-counters.md). * [Native heap profiling](/docs/data-sources/native-heap-profiler.md): a low-overhead heap profiler for hooking malloc/free/new/delete and associating memory to call-stacks, based on out-of-process unwinding, configurable sampling, attachable to already running processes. * [Java heap profiling](/docs/data-sources/java-heap-profiler.md): an out-of-process profiler tightly integrated with the Android RunTime that allows to get full snapshots of the managed heap retention graph (types, field names, retained size and references to other objects) without, however, dumping the full heap contents (strings and bitmaps) and hence reducing the serialization time and output file size. On Android, Perfetto is the next-generation system tracing system and replaces the chromium-based systrace. [ATrace-based instrumentation](/docs/data-sources/atrace.md) remains fully supported. See [Android developer docs](https://developer.android.com/topic/performance/tracing) for more details. ### Tracing SDK and user-space instrumentation The [Perfetto Tracing SDK](/docs/instrumentation/tracing-sdk.md) enables C++ developers to enrich traces with app-specific trace points. You can choose between the flexibility of defining your own strongly-typed events and creating custom data sources or using the easier-to-use [Track Event Library](/docs/instrumentation/track-events.md) which allows to easily create time-bounded slices, counters and time markers using annotations of the form `TRACE_EVENT("category", "event_name", "x", "str", "y", 42)`. The SDK is designed for tracing of multi-process systems and multi-threaded processes. It is based on [ProtoZero](/docs/design-docs/protozero.md), a library for direct writing of protobuf events on thread-local shared memory buffers. The same code can work both in fully-in-process mode, hosting an instance of the Perfetto tracing service on a dedicated thread, or in _system mode_, connecting to the Linux/Android tracing daemon through a UNIX socket, allowing to combine app-specific instrumentation points with system-wide tracing events. The SDK is based on portable C++11 code [tested](/docs/contributing/testing.md) with the major C++ sanitizers (ASan, TSan, MSan, LSan). It doesn't rely on run-time code modifications or compiler plugins. ### Tracing in Chromium Perfetto has been designed from the grounds to replace the internals of the [chrome://tracing infrastructure][chrome-tracing]. Tracing in Chromium and its internals are based on Perfetto's codebase on all major platforms (Android, CrOS, Linux, MacOS, Windows). The same [service-based architecture](/docs/concepts/service-model.md) of system-wide tracing applies, but internally the Chromium Mojo IPC system is used instead of Perfetto's own UNIX socket. By default tracing works in in-process mode in Chromium, recording only data emitted by Chromium processes. On Android (and on Linux, if disabling the Chromium sandbox) tracing can work in hybrid in-process+system mode, combining chrome-specific trace events with Perfetto system events. _(Googlers: see [go/chrometto](https://goto.google.com/chrometto) for more)_ ## Trace analysis Beyond the trace recording capabilities, the Perfetto codebase includes a dedicated project for importing, parsing and querying new and legacy trace formats, [Trace Processor](/docs/analysis/trace-processor.md). Trace Processor is a portable C++11 library that provides column-oriented table storage, designed ad-hoc for efficiently holding hours of trace data into memory and exposes a SQL query interface based on the popular SQLite query engine. The trace data model becomes a set of [SQL tables](/docs/analysis/sql-tables.autogen) which can be queried and joined in extremely powerful and flexible ways to analyze the trace data. On top of this, Trace Processor includes also a [trace-based metrics subsystem](/docs/analysis/metrics.md) consisting of pre-baked and extensible queries that can output strongly-typed summaries about a trace in the form of JSON or protobuf messages (e.g., the CPU usage at different frequency states, breakdown by process and thread). Trace-based metrics allow an easy integration of traces in performance testing scenarios or batch analysis or large corpuses of traces. Trace Processor is also designed for low-latency queries and for building trace visualizers. Today Trace Processor is used by the [Perfetto UI](https://ui.perfetto.dev) as a Web Assembly module, [Android Studio](https://developer.android.com/studio) and [Android GPU Inspector](https://gpuinspector.dev/) as native C++ library. ## Trace visualization Perfetto provides also a brand new trace visualizer for opening and querying hours-long traces, available at [ui.perfetto.dev](https://ui.perfetto.dev). The new visualizer takes advantage of modern web platform technologies. Its multi-threading design based WebWorkers keeps the UI always responsive; the analytical power of Trace Processor and SQLite is fully available in-browser through WebAssembly. The Perfetto UI works fully offline after it has been opened once. Traces opened with the UI are processed locally by the browser and do not require any server-side interaction.  ## Contributing See the [Contributing -> Getting started page](/docs/contributing/getting-started.md). ## Bugs For bugs affecting Android or the tracing internals: * **Googlers**: use the internal bug tracker [go/perfetto-bugs](http://goto.google.com/perfetto-bugs) * **Non-Googlers**: use [GitHub issues](https://github.com/google/perfetto/issues). For bugs affecting Chrome Tracing: * Use http://crbug.com `Component:Speed>Tracing label:Perfetto`. [ftrace]: https://www.kernel.org/doc/Documentation/trace/ftrace.txt [chrome-tracing]: https://www.chromium.org/developers/how-tos/trace-event-profiling-tool