Perfetto

This article provides the basic information needed to start using the Android™ tool: Perfetto

1. Introduction

The following table provides a brief description of the tool, as well as its availability depending on the software packages:

: this tool is either present (ready to use or to be activated), or can be integrated and activated on the software package.

: this tool is not present and cannot be integrated, or it is present but cannot be activated on the software package.

Tool			STM32MPU Embedded Software distribution			STM32MPU Embedded Software distribution for Android™
Name	Category	Purpose	Starter Package	Developer Package	Distribution Package	Starter Package	Developer Package	Distribution Package
Perfetto	Tracing tools	perfetto is a performance instrumentation and tracing tool for Android™. Open-source project for platform tracing Trace processing and analysis Web-based trace viewer UI				*	*
						* With Android-P (9.0.0), only protobuf binary format supported for configuration files, which required to have full baseline

2. Installing the trace and debug tool on your target board

2.1. Using the STM32MPU Embedded Software distribution for Android™

Perfetto is installed by default on all STM32MPU Embedded Software Packages for Android, but there is currently a restriction for using it with Starter and Developer Packages, so it is currently only supported with the Distribution Package:

• With Android-P(9.0.0), perfetto version does not support <--txt> option, to provide a trace configuration file in protobuf text format, so a Distribution Package is needed to get protobuf compiler (protoc or aprotoc) which allows to build protobuf binary file from protobuf text string file.

Perfetto is integrated in Android image distribution through Android base makefile: build/make/target/product/base.mk:

# Base modules (will move elsewhere, previously user tagged)
PRODUCT_PACKAGES += \
    20-dns.conf \
    95-configured \
...
    netd \
    perfetto \
    ping \
    ping6 \

3. Getting started

This is mandatory to enable root access right on the board target to execute perfetto, and to be allow to create trace files.

It can be done as follow:

 adb root
restarting adbd as root

Then you have to start required daemon and create output trace directory (mandatory to avoid SELinux denials)

 adb shell

 start traced
 start traced_probes
 mkdir /data/misc/perfetto-traces

3.1. Usage

Here is perfetto usage with current version integration in STM32MPU Embedded Software distribution for Android™

 perfetto --help
Usage: perfetto
  --background     -b     : Exits immediately and continues tracing in background
  --config         -c     : /path/to/trace/config/file or - for stdin
  --out            -o     : /path/to/out/trace/file
  --dropbox        -d TAG : Upload trace into DropBox using tag TAG (default: perfetto)
  --no-guardrails  -n     : Ignore guardrails triggered when using --dropbox (for testing).
  --help           -h

statsd-specific flags:
  --alert-id           : ID of the alert that triggered this trace.
  --config-id          : ID of the triggering config.
  --config-uid         : UID of app which registered the config.

3.2. Using basic test command

It is possible to check perfetto is working on the board by using default test configuration.

 adb shell perfetto --config :test --out /data/misc/perfetto-traces/trace
 perfetto_cmd.cc:255      Connected to the Perfetto traced service, starting tracing for 2000 ms  
 perfetto_cmd.cc:322      Wrote 40350 bytes into /data/misc/perfetto-traces/trace

Then trace viewer to be used to decode and display trace datas.

3.3. Using custom trace configuration in proto buffer binary format

Warning

Linux environment with Distribution Package required to be able to use the protobuf configuration templates available in the baseline

Configuration file to be pass on the perfetto command line, is given in protobuf binary format, so when written in text format, it must be built to generate the corresponding binary.

3.3.1. Create custom trace configuration file

You can create a custom trace configuration file in a text editor, or using shell command line. See an example below:

 cat > /tmp/config.txpb <<EOF
# This is a text-encoded protobuf for /protos/perfetto/config/trace_config.proto
duration_ms: 10000

# For long traces set the following variables. It will periodically drain the
# trace buffers into the output file, allowing to save a trace larger than the
# buffer size.
write_into_file: true
file_write_period_ms: 5000

buffers {
  size_kb: 10240
}

data_sources {
  config {
    name: "linux.ftrace"
    target_buffer: 0
    ftrace_config {
      buffer_size_kb: 40 # Kernel ftrace buffer size.
      ftrace_events: "sched_switch"
      ftrace_events: "print"
    }
  }
}

data_sources {
  config {
    name: "linux.process_stats"
    target_buffer: 0
  }
}
EOF

Other examples of custom configuration files are available in perfetto source package: external/perfetto/test/configs

3.3.2. Compile custom trace config file

Please follow commands below to compile the custom proto configuration:

 aprotoc --encode=perfetto.protos.TraceConfig \
        -I$(pwd)/external/perfetto/protos \
        $(pwd)/external/perfetto/protos/perfetto/config/perfetto_config.proto \
        < /tmp/config.txpb \
        > /tmp/config.pb

Note: perfetto_config.proto is the protbug template file entry

Output is protobuf binary format file /tmp/config.pb.

3.3.3. Execute perfetto command and get trace

• Using adb link if connected

 cat /tmp/config.pb | adb shell perfetto -c - -o /data/misc/perfetto-traces/trace.pb 

 adb shell cat /data/misc/perfetto-traces/trace.pb > /tmp/trace.pb

Then /tmp/trace.pb can be open using the Trace viewer.

3.4. Using custom trace configuration in proto buffer text format

Warning

Not supported for current perfetto version

3.5. Trace viewer

Open saved trace file by using the web UI.

4. To go further

Please find more information and documentation on the perfetto web site.

This is possible for example to convert trace file in specific redeable format.

More information are given in document on the perfetto source package.

User Interface