Perfetto

This article provides the basic information required to start using the perfetto [1] Android™ tool.

1 Introduction[edit]

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

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

No: 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[1] is a performance instrumentation and tracing tool for Android™.
  • Open-source project for platform tracing
  • Trace processing and analysis
  • Web-based trace viewer UI
No No No No* No* Yes
* With Android-P (9.0.0), only protobuf binary format supported for configuration files, which required to have full baseline

2 Installing perfetto trace and debug tool on your target board[edit]

2.1 Using the STM32MPU Embedded Software distribution for Android™[edit]

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

  • With Android-P(9.0.0), perfetto version does not support the <--txt> option that provides a trace configuration file in protobuf text format, so a Distribution Package is required to get protobuf compiler (protoc or aprotoc), which enables building 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 with perfetto[edit]

To execute perfetto, it is mandatory to have root access rights on the board target and be allowed to create trace files.

Proceed as follows:

PC $> adb root
restarting adbd as root

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

PC $> adb shell

Board $> start traced
Board $> start traced_probes
Board $> mkdir /data/misc/perfetto-traces

3.1 Using perfetto[edit]

To use the perfetto current version integrated in STM32MPU Embedded Software distribution for Android™, proceed as follows:

Board $> 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 commands[edit]

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

PC $> 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 can be used to decode and display trace datas.

3.3 Using custom trace configurations in proto buffer binary format[edit]

Warning.png Linux® environment with Distribution Package is required to be able to use the protobuf configuration templates available in the baseline

.

The configuration file to be passed in the perfetto command line is given in protobuf binary format[2]. When it is written in text format, it must be built to generate the corresponding binary.

3.3.1 Creating custom trace configuration files[edit]

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

PC $> 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 periodically drains 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 the perfetto source package: platform/external/perfetto/test/configs

3.3.2 Compiling custom trace configuration files[edit]

Follow the commands below to compile the custom proto configuration:

PC $> 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.

The output is a protobuf binary format file, /tmp/config.pb.

3.3.3 Executing perfetto commands and getting a trace[edit]

  • Use adb link if it is connected:
PC $> cat /tmp/config.pb | adb shell perfetto -c - -o /data/misc/perfetto-traces/trace.pb 
PC $> adb shell cat /data/misc/perfetto-traces/trace.pb > /tmp/trace.pb

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

3.4 Using custom trace configurations in proto buffer text format[edit]

Warning.png Not supported for current perfetto version


3.5 Trace viewer[edit]

Open the saved trace file through the web UI[4].

4 To go further[edit]

More information and documentation can be found on the perfetto web site[5].

For example, trace files can be converted in specific redeable format.

Additional information are available within the perfetto source package[6].

5 References[edit]



User Interface

Attachments

Discussions