Difference between revisions of "Perfetto"

[quality revision] [quality revision]
(Using 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 YesNo* Yes No* Yes
* Not available for Android With Android-P (9.0.0 as ), only protobuf binary format is supported for configuration files. It's , which required to have a full baseline

2 Getting started with perfetto[edit]

From Android 10.0.0, Perfetto instructions can be generated using the recording tool[2].

  • Create record settings required
  • Copy generated instructions
  • Execute the copied instructions on a opened terminal with the device connected through USB, having ADB installed.

At the end of the trace execution, you can get back the trace:

 adb pull /data/misc/perfetto-traces/trace

From this stage you can directly open the trace through the web viewer[3].

3 For Android 9.0.0 distribution[edit]

3.1

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

3

2.1

.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

.2

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.

2.

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

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

2.

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[

4

2]. When it is written in text format, it must be built to generate the corresponding binary.

3.

2.

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.

2.

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.

2.

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.

2.

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

Warning.png Not supported for current perfetto version


3.

2.

5 Trace viewer[edit]

Open the saved trace file through the web UI[

6

4].

3.3

4 To go further[edit]

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

7

5].

For example, trace files can be converted in specific

readable

redeable format.

Additional information are available within the perfetto source package[

8

6].

4 5 References[edit]


This article provides the basic information required to start using the '''perfetto''' <ref name=perfettowebref/> Android&trade; tool.

== Introduction ==
{{:Trace_and_debug_tools_assignment_table_template}}<onlyinclude>

| rowspan="2" | [[perfetto|perfetto]]
| rowspan="2" | [[:Category:Tracing tools|Tracing tools]]
| rowspan="2" style="text-align:left;" |  '''perfetto'''<ref name=perfettowebref>https://perfetto.dev/</ref> is a performance instrumentation and tracing tool for Android&trade;.<br>

*Open-source project for platform tracing
*Trace processing and analysis
*Web-based trace viewer UI
| rowspan="2" | {{N}}
| rowspan="2" | {{N}} 
| rowspan="2" | {{N}}
| style="height:160px;" | {{YN}}&#42;
| style="height:160px;" | {{YN}}&#42;
| style="height:160px;" | {{Y}}
|-
| colspan="6" style="text-align:left;text-align:bottom;font-size:80%;" | &#42; ''Not available for Android With Android-P (9.0.0 as ), only protobuf binary format is supported for configuration files. It's, which required to have a full baseline''<br>
</onlyinclude>

|}

== Getting started with perfetto ==

From Android 10.0.0, Perfetto instructions can be generated using the recording tool<ref>https://ui.perfetto.dev/#!/record</ref>.
* Create record settings required
* Copy generated instructions
* Execute the copied instructions on a opened terminal with the device connected through USB, having [[ADB]] installed.

At the end of the trace execution, you can get back the trace:
  adb pull /data/misc/perfetto-traces/trace

From this stage you can directly open the trace through the web viewer<ref>https://ui.perfetto.dev</ref>.
<div class="mw-collapsible mw-collapsed">

==For Android 9.0.0 distribution==<div class="mw-collapsible-content">


=== Installing perfetto trace and debug tool on your target board===
====

=== Using the STM32MPU Embedded Software distribution for Android&trade; ====

'''perfetto''' is installed by default on  all STM32MPU Embedded Software Packages for Android. However {{highlight|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 {{HighlightParam|''<--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: <code>''build/make/target/product/base.mk''</code>:
 # Base modules (will move elsewhere, previously user tagged)
 PRODUCT_PACKAGES += \
     20-dns.conf \
     95-configured \
 ...
     netd \
     {{green|'''perfetto \'''}}
     ping \
     ping6 \

=== Getting started with perfetto ===

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

====Using perfetto====

To use the perfetto current version integrated in STM32MPU Embedded Software distribution for Android&trade;, 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.

====Using basic test commands====

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

====Using custom trace configurations in proto buffer binary format====

{{Warning | Linux<sup>&reg;</sup> 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<ref>https://developers.google.com/protocol-buffers/</ref>. When it is written in text format, it must be built to generate the corresponding binary.

=====Creating custom trace configuration files=====

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: {{CodeSource | Android | repo=platform/external/perfetto | test/configs}}

=====Compiling custom trace configuration files=====

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.

=====Executing perfetto commands and getting a trace=====

*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 | Trace viewer]].

====Using custom trace configurations in proto buffer text format====

{{Warning | Not supported for current perfetto version}}
{{InternalInfo|
This mode is not supported in current integrated version of perfetto. Keep following information internally for the moment.

This mode allows benefiting from the web application for creating a custom configuration by using the '''''Record settings''''' feature<ref>https://ui.perfetto.dev/#!/record</ref>.<br>

You can select the information type(s) you want to trace, and perfetto will automatically generate a protobuf configuration to be used in stdin mode when selecting '''''Start recoding'''''.
}}

====Trace viewer====

Open the saved trace file through the web UI<ref>https://ui.perfetto.dev</ref>.

=== To go further ===

More information and documentation can be found on the perfetto web site<ref>https://perfetto.dev/#/?id=perfetto-performance-instrumentation-and-tracing</ref>.

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

Additional information are available within the perfetto source package<ref> {{CodeSource | Android | repo=platform/external/perfetto | docs}}</ref>.
</div></div>

== References ==<references />

<noinclude>

[[Category:Android tracing tools]]
[[Category:Android]]
{{ArticleBasedOnModel | Trace and debug tools article model}}
{{PublicationRequestId | 13230 | 2019-09-11}}</noinclude>
Line 13: Line 13:
 
| rowspan="2" | {{N}}  
 
| rowspan="2" | {{N}}  
 
| rowspan="2" | {{N}}
 
| rowspan="2" | {{N}}
| style="height:160px;" | {{N}}&#42;
+
| style="height:160px;" | {{Y}}&#42;
| style="height:160px;" | {{N}}&#42;
+
| style="height:160px;" | {{Y}}&#42;
 
| style="height:160px;" | {{Y}}
 
| style="height:160px;" | {{Y}}
 
|-
 
|-
| colspan="6" style="text-align:left;text-align:bottom;font-size:80%;" | &#42; ''With Android-P (9.0.0), only protobuf binary format supported for configuration files, which required to have full baseline''<br>
+
| colspan="6" style="text-align:left;text-align:bottom;font-size:80%;" | &#42; ''Not available for Android 9.0.0 as only protobuf binary format is supported for configuration files. It's required to have a full baseline''<br>
 
</onlyinclude>
 
</onlyinclude>
 
|}
 
|}
   
== Installing perfetto trace and debug tool on your target board==
+
== Getting started with perfetto ==
=== Using the STM32MPU Embedded Software distribution for Android&trade; ===
+
 
  +
From Android 10.0.0, Perfetto instructions can be generated using the recording tool<ref>https://ui.perfetto.dev/#!/record</ref>.
  +
* Create record settings required
  +
* Copy generated instructions
  +
* Execute the copied instructions on a opened terminal with the device connected through USB, having [[ADB]] installed.
  +
 
  +
At the end of the trace execution, you can get back the trace:
  +
  adb pull /data/misc/perfetto-traces/trace
  +
 
  +
From this stage you can directly open the trace through the web viewer<ref>https://ui.perfetto.dev</ref>.
  +
 
  +
<div class="mw-collapsible mw-collapsed">
  +
==For Android 9.0.0 distribution==
  +
<div class="mw-collapsible-content">
  +
 
  +
=== Installing perfetto trace and debug tool on your target board===
  +
==== Using the STM32MPU Embedded Software distribution for Android&trade; ====
 
'''perfetto''' is installed by default on  all STM32MPU Embedded Software Packages for Android. However {{highlight|there is currently a restriction for using it with Starter and Developer Packages, so it is currently only supported on the Distribution Package}}:
 
'''perfetto''' is installed by default on  all STM32MPU Embedded Software Packages for Android. However {{highlight|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 {{HighlightParam|''<--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.
 
*With Android-P(9.0.0), perfetto version does not support the {{HighlightParam|''<--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.
Line 37: Line 53:
 
     ping6 \
 
     ping6 \
   
== Getting started with perfetto ==
+
=== Getting started with perfetto ===
 
To execute perfetto, it is mandatory to have root access rights on the board target and be allowed to create trace files.
 
To execute perfetto, it is mandatory to have root access rights on the board target and be allowed to create trace files.
   
Line 52: Line 68:
 
  {{Board$}} mkdir /data/misc/perfetto-traces
 
  {{Board$}} mkdir /data/misc/perfetto-traces
   
===Using perfetto===
+
====Using perfetto====
 
To use the perfetto current version integrated in STM32MPU Embedded Software distribution for Android&trade;, proceed as follows:
 
To use the perfetto current version integrated in STM32MPU Embedded Software distribution for Android&trade;, proceed as follows:
 
  {{Board$}} perfetto --help
 
  {{Board$}} perfetto --help
Line 68: Line 84:
 
   --config-uid        : UID of app which registered the config.
 
   --config-uid        : UID of app which registered the config.
   
===Using basic test commands===
+
====Using basic test commands====
 
It is possible to check that perfetto is working on the board by using the default test configuration:
 
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
 
  {{PC$}} adb shell perfetto --config :test --out /data/misc/perfetto-traces/trace
Line 76: Line 92:
 
Then [[#Trace viewer|trace viewer]] can be used to decode and display trace datas.
 
Then [[#Trace viewer|trace viewer]] can be used to decode and display trace datas.
   
===Using custom trace configurations in proto buffer binary format===
+
====Using custom trace configurations in proto buffer binary format====
 
{{Warning | Linux<sup>&reg;</sup> environment with Distribution Package is required to be able to use the protobuf configuration templates available in the baseline}}.
 
{{Warning | Linux<sup>&reg;</sup> 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<ref>https://developers.google.com/protocol-buffers/</ref>. When it is written in text format, it must be built to generate the corresponding binary.
 
The configuration file to be passed in the perfetto command line is given in protobuf binary format<ref>https://developers.google.com/protocol-buffers/</ref>. When it is written in text format, it must be built to generate the corresponding binary.
   
====Creating custom trace configuration files====
+
=====Creating custom trace configuration files=====
 
You can create a custom trace configuration file in a text editor, or use a shell command line. Below an example:
 
You can create a custom trace configuration file in a text editor, or use a shell command line. Below an example:
   
Line 119: Line 135:
 
Other examples of custom configuration files are available in the perfetto source package: {{CodeSource | Android | repo=platform/external/perfetto | test/configs}}
 
Other examples of custom configuration files are available in the perfetto source package: {{CodeSource | Android | repo=platform/external/perfetto | test/configs}}
   
====Compiling custom trace configuration files====
+
=====Compiling custom trace configuration files=====
 
Follow the commands below to compile the custom proto configuration:
 
Follow the commands below to compile the custom proto configuration:
 
  {{PC$}} aprotoc --encode=perfetto.protos.TraceConfig \
 
  {{PC$}} aprotoc --encode=perfetto.protos.TraceConfig \
Line 130: Line 146:
 
The output is a protobuf binary format file, /tmp/config.pb.
 
The output is a protobuf binary format file, /tmp/config.pb.
   
====Executing perfetto commands and getting a trace====
+
=====Executing perfetto commands and getting a trace=====
 
*Use adb link if it is connected:
 
*Use adb link if it is connected:
 
  {{PC$}} cat /tmp/config.pb | adb shell perfetto -c - -o /data/misc/perfetto-traces/trace.pb  
 
  {{PC$}} cat /tmp/config.pb | adb shell perfetto -c - -o /data/misc/perfetto-traces/trace.pb  
Line 138: Line 154:
 
Then ''/tmp/trace.pb'' can be open by using the [[#Trace viewer | Trace viewer]].
 
Then ''/tmp/trace.pb'' can be open by using the [[#Trace viewer | Trace viewer]].
   
===Using custom trace configurations in proto buffer text format===
+
====Using custom trace configurations in proto buffer text format====
 
{{Warning | Not supported for current perfetto version}}
 
{{Warning | Not supported for current perfetto version}}
 
{{InternalInfo|
 
{{InternalInfo|
Line 147: Line 163:
 
}}
 
}}
   
===Trace viewer===
+
====Trace viewer====
 
Open the saved trace file through the web UI<ref>https://ui.perfetto.dev</ref>.
 
Open the saved trace file through the web UI<ref>https://ui.perfetto.dev</ref>.
   
== To go further ==
+
=== To go further ===
 
More information and documentation can be found on the perfetto web site<ref>https://perfetto.dev/#/?id=perfetto-performance-instrumentation-and-tracing</ref>.
 
More information and documentation can be found on the perfetto web site<ref>https://perfetto.dev/#/?id=perfetto-performance-instrumentation-and-tracing</ref>.
   
For example, trace files can be converted in specific redeable format.
+
For example, trace files can be converted in specific readable format.
   
 
Additional information are available within the perfetto source package<ref> {{CodeSource | Android | repo=platform/external/perfetto | docs}}</ref>.
 
Additional information are available within the perfetto source package<ref> {{CodeSource | Android | repo=platform/external/perfetto | docs}}</ref>.
  +
  +
</div></div>
   
 
== References ==
 
== References ==