1# Perfetto SDK example project 2 3This directory contains an example project using the [Perfetto 4SDK](https://perfetto.dev/docs/instrumentation/tracing-sdk). It demonstrates 5how to instrument your application with track events to give more context in 6developing, debugging and performance analysis. 7 8Dependencies: 9 10- [CMake](https://cmake.org/) 11- C++11 12 13## Building 14 15First, check out the latest Perfetto release: 16 17```bash 18git clone https://android.googlesource.com/platform/external/perfetto -b v14.0 19``` 20 21Then, build using CMake: 22 23```bash 24cd perfetto/examples/sdk 25cmake -B build 26cmake --build build 27``` 28 29## Track event example 30 31The [basic example](example.cc) shows how to instrument an app with track 32events. Run it with: 33 34```bash 35build/example 36``` 37 38The program will create a trace file in `example.perfetto-trace`, which can be 39directly opened in the [Perfetto UI](https://ui.perfetto.dev). The result 40should look like this: 41 42 44 45## System-wide example 46 47While the above example only records events from the program itself, with 48Perfetto it's also possible to combine app trace events with system-wide 49profiling data (e.g., ftrace on Linux). The repository has a [second 50example](example_system_wide.cc) which demonstrates this on Android. 51 52Requirements: 53- [Android NDK](https://developer.android.com/ndk) 54- A device running Android Pie or newer 55 56> Tip: It's also possible to sideload Perfetto on pre-Pie Android devices. 57> See the [build 58> instructions](https://perfetto.dev/docs/contributing/build-instructions). 59 60To build: 61 62```bash 63export NDK=/path/to/ndk 64cmake -DCMAKE_TOOLCHAIN_FILE=$NDK/build/cmake/android.toolchain.cmake \ 65 -B build_android 66cmake --build build_android 67``` 68 69Next, plug in an Android device into a USB port, download the example and run 70it while simultaneously recording a trace using the `perfetto` command line 71tool: 72 73```bash 74adb push build_android/example_system_wide ../system_wide_trace_cfg.pbtxt \ 75 /data/local/tmp/ 76adb shell "\ 77 cd /data/local/tmp; \ 78 rm -f /data/misc/perfetto-traces/example_system_wide.perfetto-trace; \ 79 cat system_wide_trace_cfg.pbtxt | \ 80 perfetto --config - --txt --background \ 81 -o 82 /data/misc/perfetto-traces/example_system_wide.perfetto-trace; \ 83 ./example_system_wide" 84``` 85 86Finally, retrieve the resulting trace: 87 88```bash 89adb pull /data/misc/perfetto-traces/example_system_wide.perfetto-trace 90``` 91 92When opened in the Perfetto UI, the trace now shows additional contextual 93information such as CPU frequencies and kernel scheduler information. 94 95 97 98> Tip: You can generate a new trace config with additional data sources using 99> the [Perfetto UI](https://ui.perfetto.dev/#!/record) and replace 100> `system_wide_trace_cfg.pbtxt` with the [generated config]( 101> https://ui.perfetto.dev/#!/record?p=instructions). 102 103## Custom data source example 104 105The [final example](example_custom_data_source.cc) shows how to use an 106application defined data source to emit custom, strongly typed data into a 107trace. Run it with: 108 109```bash 110build/example_custom_data_source 111``` 112 113The program generates a trace file in `example_custom_data_source.perfetto-trace`, 114which we can examine using Perfetto's `trace_to_text` tool to show the trace 115packet written by the custom data source: 116 117```bash 118trace_to_text text example_custom_data_source.perfetto-trace 119... 120packet { 121 trusted_uid: 0 122 timestamp: 42 123 trusted_packet_sequence_id: 2 124 previous_packet_dropped: true 125 for_testing { 126 str: "Hello world!" 127 } 128} 129... 130``` 131
