1# Perfetto - System profiling, app tracing and trace analysis 2 3Perfetto is a production-grade open-source stack for performance 4instrumentation and trace analysis. It offers services and libraries for 5recording system-level and app-level traces, native + java heap profiling, a 6library for analyzing traces using SQL and a web-based UI to visualize and 7explore multi-GB traces. 8 9 10 11## Recording traces 12 13At its core, Perfetto introduces a novel userspace-to-userspace 14[tracing protocol](/docs/design-docs/api-and-abi.md#tracing-protocol-abi) based 15on direct protobuf serialization onto a shared memory buffer. The tracing 16protocol is used both internally for the built-in data sources and exposed to 17C++ apps through the [Tracing SDK](/docs/instrumentation/tracing-sdk.md) and the 18[Track Event Library](/docs/instrumentation/track-events.md). 19 20This new tracing protocol allows dynamic configuration of all aspects of tracing 21through an extensible protobuf-based capability advertisement and data source 22configuration mechanism (see 23[Trace configuration docs](/docs/concepts/config.md)). 24Different data sources can be multiplexed onto different subsets of 25user-defined buffers, allowing also streaming of 26[arbitrarily long traces](/docs/concepts/config.md#long-traces) into the 27filesystem. 28 29### System-wide tracing on Android and Linux 30 31On Linux and Android, Perfetto bundles a number of data sources that are able to 32gather detailed performance data from different system interfaces. For the full 33sets and details see the _Data Sources_ section of the documentation. Some 34examples: 35 36* [Kernel tracing](/docs/data-sources/cpu-scheduling.md): Perfetto integrates 37 with [Linux's ftrace][ftrace] and allows to record kernel events (e.g 38 scheduling events, syscalls) into the trace. 39 40* [/proc and /sys pollers](/docs/data-sources/memory-counters.md), which allow 41 to sample the state of process-wide or system-wide cpu and memory counters 42 over time. 43 44* Integration with Android HALs modules for recording [battery and energy-usage 45 counters](/docs/data-sources/battery-counters.md). 46 47* [Native heap profiling](/docs/data-sources/native-heap-profiler.md): a 48 low-overhead heap profiler for hooking malloc/free/new/delete and associating 49 memory to call-stacks, based on out-of-process unwinding, configurable 50 sampling, attachable to already running processes. 51 52* Capturing [Java heap dumps](/docs/data-sources/java-heap-profiler.md) with an 53 out-of-process profiler tightly integrated with the Android RunTime that 54 allows to get full snapshots of the managed heap retention graph (types, 55 field names, retained size and references to other objects) without, however, 56 dumping the full heap contents (strings and bitmaps) and hence reducing the 57 serialization time and output file size. 58 59On Android, Perfetto is the next-generation system tracing system and replaces 60the chromium-based systrace. 61[ATrace-based instrumentation](/docs/data-sources/atrace.md) remains fully 62supported. 63See [Android developer docs](https://developer.android.com/topic/performance/tracing) 64for more details. 65 66### Tracing SDK and user-space instrumentation 67 68The [Perfetto Tracing SDK](/docs/instrumentation/tracing-sdk.md) enables C++ 69developers to enrich traces with app-specific trace points. You can choose 70between the flexibility of defining your own strongly-typed events and creating 71custom data sources or using the easier-to-use 72[Track Event Library](/docs/instrumentation/track-events.md) which allows to 73easily create time-bounded slices, counters and time markers using annotations 74of the form `TRACE_EVENT("category", "event_name", "x", "str", "y", 42)`. 75 76The SDK is designed for tracing of multi-process systems and multi-threaded 77processes. It is based on [ProtoZero](/docs/design-docs/protozero.md), a library 78for direct writing of protobuf events on thread-local shared memory buffers. 79 80The same code can work both in fully-in-process mode, hosting an instance of the 81Perfetto tracing service on a dedicated thread, or in _system mode_, connecting 82to the Linux/Android tracing daemon through a UNIX socket, allowing to combine 83app-specific instrumentation points with system-wide tracing events. 84 85The SDK is based on portable C++17 code [tested](/docs/contributing/testing.md) 86with the major C++ sanitizers (ASan, TSan, MSan, LSan). It doesn't rely on 87run-time code modifications or compiler plugins. 88 89### Tracing in Chromium 90 91Perfetto has been designed from the grounds to replace the internals of the 92[chrome://tracing infrastructure][chrome-tracing]. Tracing in Chromium and its 93internals are based on Perfetto's codebase on all major platforms (Android, 94CrOS, Linux, MacOS, Windows). 95The same [service-based architecture](/docs/concepts/service-model.md) of 96system-wide tracing applies, but internally the Chromium Mojo IPC system is 97used instead of Perfetto's own UNIX socket. 98 99By default tracing works in in-process mode in Chromium, recording only data 100emitted by Chromium processes. On Android (and on Linux, if disabling the 101Chromium sandbox) tracing can work in hybrid in-process+system mode, combining 102chrome-specific trace events with Perfetto system events. 103 104_(Googlers: see [go/chrometto](https://goto.google.com/chrometto) for more)_ 105 106## Trace analysis 107 108Beyond the trace recording capabilities, the Perfetto codebase includes a 109dedicated project for importing, parsing and querying new and legacy trace 110formats, [Trace Processor](/docs/analysis/trace-processor.md). 111 112Trace Processor is a portable C++17 library that provides column-oriented 113table storage, designed ad-hoc for efficiently holding hours of trace data 114into memory and exposes a SQL query interface based on the popular SQLite query 115engine. 116The trace data model becomes a set of 117[SQL tables](/docs/analysis/sql-tables.autogen) which can be queried and joined 118in extremely powerful and flexible ways to analyze the trace data. 119 120On top of this, Trace Processor includes also a 121[trace-based metrics subsystem](/docs/analysis/metrics.md) consisting of 122pre-baked and extensible queries that can output strongly-typed summaries 123about a trace in the form of JSON or protobuf messages (e.g., the CPU usage 124at different frequency states, breakdown by process and thread). 125 126Trace-based metrics allow an easy integration of traces in performance testing 127scenarios or batch analysis or large corpuses of traces. 128 129Trace Processor is also designed for low-latency queries and for building 130trace visualizers. Today Trace Processor is used by the 131[Perfetto UI](https://ui.perfetto.dev) as a Web Assembly module, 132[Android Studio](https://developer.android.com/studio) and 133[Android GPU Inspector](https://gpuinspector.dev/) as native C++ library. 134 135## Trace visualization 136 137Perfetto provides also a brand new trace visualizer for opening and querying 138hours-long traces, available at [ui.perfetto.dev](https://ui.perfetto.dev). 139The new visualizer takes advantage of modern web platform technologies. 140Its multi-threading design based WebWorkers keeps the UI always responsive; 141the analytical power of Trace Processor and SQLite is fully available in-browser 142through WebAssembly. 143 144The Perfetto UI works fully offline after it has been opened once. Traces opened 145with the UI are processed locally by the browser and do not require any 146server-side interaction. 147 148 149 150## Contributing 151 152See the [Contributing -> Getting started page](/docs/contributing/getting-started.md). 153 154## Bugs 155 156For bugs affecting Android or the tracing internals: 157 158* **Googlers**: use the internal bug tracker [go/perfetto-bugs](http://goto.google.com/perfetto-bugs) 159 160* **Non-Googlers**: use [GitHub issues](https://github.com/google/perfetto/issues). 161 162For bugs affecting Chrome Tracing: 163 164* **Googlers**: use the internal bug tracker [go/chrometto-bugs](http://goto.google.com/chrometto-bugs) 165 166* **Non-Googlers**: use [crbug.com](https://bugs.chromium.org/p/chromium/issues/list?q=component%3ASpeed%3ETracing%20label%3APerfetto) 167to [file new bugs](https://bugs.chromium.org/p/chromium/issues/entry?components=Speed%3ETracing&labels=Perfetto). 168 169[ftrace]: https://www.kernel.org/doc/Documentation/trace/ftrace.txt 170[chrome-tracing]: https://www.chromium.org/developers/how-tos/trace-event-profiling-tool 171
