docs/getting-started/other-formats.md
In this guide, you'll learn about:
Perfetto is capable of opening and analyzing trace files generated by a variety of external tools and systems, not just its own native protobuf format. You might have existing traces in these formats if:
The main advantages of using Perfetto to examine these external traces are its powerful analysis and visualization capabilities:
Below, we detail the supported formats, provide context on their typical use cases, and outline what to expect when loading them into Perfetto.
Description: The Chrome JSON trace format consists of a JSON array of event
objects. Each object represents a single trace event and typically includes
fields like pid (process ID), tid (thread ID), ts (timestamp in
microseconds), ph (phase, indicating event type like begin, end, instant,
counter, etc.), name (event name), cat (category), and args
(event-specific arguments). This format was originally developed for Chrome's
about:tracing (now chrome://tracing) tool.
Common Scenarios: While Chromium browser developers now primarily use Perfetto's native protobuf format for trace collection, the Chrome JSON format is still encountered in several situations:
Perfetto Support:
B (begin) and E (end) events as slices.X (complete) events as slices.I (instant) events as single points on the timeline.C (counter) events as counter tracks.M (metadata) events for process and thread names, etc.s, t, f (flow) events as connecting arrows between slices.slice, track, process, thread, counter, args). This
allows you to analyze Chrome JSON traces using SQL queries.chrome://tracing tool unless they are critical for
basic trace understanding.B and E pairs).
Overlapping, non-nested events might not be visualized or processed as they
are in the legacy chrome://tracing viewer, which could be more lenient.
For more details, see the
FAQ on overlapping JSON events.How to Generate:
chrome://tracing: Older versions of Chrome used this
interface for saving traces.External Resources:
about:tracing tool context:
The Trace Event Profiling Tool (Chromium Docs)Description: The Firefox Profiler JSON format is primarily known for its use by the Firefox Profiler, a web-based tool for performance analysis. While the format can describe various types of timeline data including "markers" (similar to trace events), its main strength, and Perfetto's primary interest in it, lies in representing CPU profiling data, especially sampled call stacks. This makes it an excellent target format for visualizing flamegraphs and call trees from various profiling sources.
Common Scenarios: The most common reason Perfetto users encounter this format is for:
perf (or Android simpleperf) CPU profiles:
Developers often collect CPU samples using perf record on Linux or
simpleperf on Android. These native profiles can then be converted into the
Firefox Profiler JSON format to leverage the interactive and user-friendly
visualizations offered by tools like profiler.firefox.com or, as relevant
here, for import into Perfetto.Perfetto Support:
perf_sample,
stack_profile_callsite, stack_profile_frame, and
stack_profile_mapping.stringTable and tables with schema + data
arrays (e.g., frameTable.schema and frameTable.data). This is the format
historically generated by tools like perf script report gecko.stringArray and tables with separate column
arrays (e.g., frameTable.func, funcTable.name). This is the format used
by Firefox Profiler's preprocessed output and indicated by the
meta.preprocessedProfileVersion field.How to Generate: The most relevant generation path for Perfetto users
involves converting native CPU profiles from Linux perf or Android
simpleperf.
Other methods (less common for Perfetto import scenarios):
about:profiling or developer tools) and saving the profile.External Resources:
perf tool:
perf Wiki,
man pagesimpleperf tool:
Simpleperf usageDescription: Android Systrace was the legacy system-wide tracing tool
for Android, used primarily before the introduction of Perfetto with Android 9
(Pie). It captures kernel activity via ftrace (e.g., CPU scheduling, I/O) and
userspace annotations via ATrace (e.g., android.os.Trace). Systrace typically
produces an interactive HTML file embedding trace data in a text-based format.
Common Scenarios (Primarily Legacy): You will typically only encounter the Android Systrace format when dealing with older data or legacy workflows, such as:
systrace.py command-line
tool.For any current or new tracing on Android (version 9 Pie and newer), Perfetto is the standard and strongly recommended tool.
Perfetto Support:
slice, sched_slice, ftrace_event), making it
queryable via SQL.How to Generate (Legacy Methods): The methods below describe how Systrace files were historically created and are provided for context when dealing with older traces. These methods are deprecated and should not be used for new trace collection on Android 9 (Pie) or newer.
systrace.py (Deprecated): Historically, these traces were
generated using the systrace.py script from the Android SDK Platform Tools.
An example command might look like:
# python <sdk>/platform-tools/systrace/systrace.py -a <your.app.package.name> -o mytrace.html sched freq idle am wm
External Resources:
perf script)Description: The "Perf textual format" typically refers to the
human-readable textual output generated by the perf script command on Linux.
This command processes a perf.data file (created by perf record) and prints
a chronological log of the recorded events. The output is highly configurable
via perf script options but commonly includes CPU samples with their call
stacks, timestamps, process/thread identifiers, CPU number, and event names.
Common Scenarios: This format is often used for:
perf.data file for quick analysis or
debugging.perf script output to generate flame graphs.perf script outputs from older profiling sessions or
automated systems.Perfetto Support:
perf script.
cpu_profile_stack_sample_table for the samples, and
stack_profile_callsite, stack_profile_frame, stack_profile_mapping for
the call stack information).perf script output to be
visualized as a flamegraph in the Perfetto UI and queried using SQL.perf script is very flexible depending on the
arguments passed to it (e.g., using the -F flag). Perfetto's parser likely
expects a common or default-like output structure for samples. Highly
customized or unusual perf script textual outputs might not parse
correctly or completely.perf script might output (e.g., raw tracepoints if -D is used, or other
event types) may be limited when importing directly as "Perf textual
format."perf.data with a
feature-rich intermediate format, consider converting perf.data to the
Firefox Profiler JSON format, which
Perfetto also supports for sample data.How to Generate:
Record a profile with perf record: First, capture profiling data using
perf record. This creates a perf.data file.
# Example: Profile at 99Hz for 1 seconds with DWARF call graphs
sudo perf record -F 99 -g --call-graph dwarf --output perf.data -- find ~ -name 'foo'
Refer to man perf-record for detailed command options. Ensure debug
symbols for your binaries are accessible for proper symbolization by
perf script.
Generate textual output with perf script: Process the perf.data file
to produce the textual output.
# Default output
sudo perf script -i perf.data > my_perf_output.txt
For more detailed output that is often useful for other tools (and potentially for Perfetto's parser if it looks for specific fields), you might specify the fields:
perf script -i perf.data -F comm,pid,tid,cpu,time,event,ip,sym,dso,trace > my_perf_output_detailed.txt
Refer to man perf-script for its extensive formatting options.
Open this trace in ui.perfetto.dev
Navigate to ui.perfetto.dev and upload the
my_perf_output.txt file into the UI. Once the trace opens, you should be
able select either individual CPU samples or ranges of time containing CPU
samples to get a flamegraph of all the samples in that region.
Here's an example of what that looks like
External Resources:
perf-script man page: man perf-script (or search online, e.g.,
perf-script Linux man page)perf tool general information:
perf Wiki (kernel.org)perf examples:
Brendan Gregg's perf page (Contains
many examples of perf script usage, especially for flame graphs)Description: Simpleperf is Android's profiling tool built on top of the
Linux perf framework. The "Simpleperf proto format" refers to the binary
protobuf format generated by the simpleperf report-sample --protobuf command.
This format contains CPU samples with call stacks, process/thread information,
file mappings, and symbol tables in a compact binary representation. Android
Studio's CPU profiler uses this format internally when displaying simpleperf
profiles.
Common Scenarios: This format is used for:
Perfetto Support:
cpu_profile_stack_sample table with full call
stack informationstack_profile_callsite, stack_profile_frame, stack_profile_mapping)How to Generate:
Record a profile with simpleperf: First, capture profiling data using
simpleperf record.
# Example: Profile an Android app with call graphs
adb shell simpleperf record -p <pid> -g --duration 10
adb pull /data/local/tmp/perf.data simpleperf.data
Refer to simpleperf record --help for detailed command options.
Convert to proto format: Use simpleperf report-sample to convert the
raw recording to protobuf format:
# Convert to proto format with call chains
simpleperf report-sample --protobuf --show-callchain \
-i simpleperf.data -o simpleperf.proto
# Optionally provide symbol directories for better symbolization
simpleperf report-sample --protobuf --show-callchain \
-i simpleperf.data -o simpleperf.proto \
--symdir /path/to/symbols
The --show-callchain flag is required to include call stack information in
the output.
Open in ui.perfetto.dev
Navigate to ui.perfetto.dev and upload the
simpleperf.proto file. The trace will be imported and you can view
flamegraphs of the CPU samples by selecting time ranges in the UI.
Description: The Linux ftrace textual format is the raw, human-readable
output generated by the Linux kernel's ftrace tracing infrastructure. Each
line in this text-based format typically represents a single trace event and
follows a common structure:
TASK-PID CPU# [MARKERS] TIMESTAMP FUNCTION --- ARGS. For example, a
sched_switch event might look like:
bash-1234 [002] ...1 5075.958079: sched_switch: prev_comm=bash prev_pid=1234 prev_prio=120 prev_state=R ==> next_comm=trace-cmd next_pid=5678 next_prio=120.
This format can be quite verbose but is fundamental to how ftrace operates and
is exposed via the tracefs filesystem (usually mounted at
/sys/kernel/tracing).
Common Scenarios: You are likely to encounter or use this format when:
trace-cmd utility, specifically
with commands like trace-cmd report or trace-cmd stream.tracefs, such as
/sys/kernel/tracing/trace.Perfetto Support: Perfetto's support for the ftrace textual format is primarily for legacy compatibility and is maintained on a best-effort basis.
.txt or .ftrace extensions). It visualizes known event types
by parsing the text lines. For instance:
sched_switch events are displayed as scheduling slices on CPU tracks.print events that match the ATrace format are shown as userspace slices.sched_switch, sched_waking,
cpu_frequency, atrace-compatible print events) into their corresponding
structured SQL tables (e.g., sched_slice, slice, counter).ftrace_event catch-all table. Support is typically limited
to events that have specific parsers for creating structured tables.GenericFtraceEvent type),
and more robust support. Importing the textual format should be reserved for
analyzing pre-existing logs.How to Generate (for context on existing logs): These methods describe how
ftrace textual logs are typically created using tracefs (usually mounted at
/sys/kernel/tracing). For new tracing, prefer using Perfetto's ftrace data
source directly.
Using trace-cmd: trace-cmd is a user-space frontend for ftrace.
# Example: Record scheduling and syscall events
sudo trace-cmd record -e sched -e syscalls
# After stopping (Ctrl-C or by duration), generate the textual report:
trace-cmd report > my_ftrace_log.txt
Or for a live stream:
sudo trace-cmd stream -e sched:sched_waking -e irq:irq_handler_entry > my_ftrace_log.txt
(Stop with Ctrl-C). Refer to man trace-cmd for more options.
Directly from tracefs (more manual): You can interact with ftrace via
the /sys/kernel/tracing/ interface.
# Example: Enable sched_switch and printk events
sudo sh -c 'echo sched:sched_switch print > /sys/kernel/tracing/set_event'
# Enable tracing
sudo sh -c 'echo 1 > /sys/kernel/tracing/tracing_on'
# ... allow the system to run or perform actions you want to trace ...
# Capture the trace buffer
sudo cat /sys/kernel/tracing/trace > my_ftrace_log.txt
# Disable tracing and clear events
sudo sh -c 'echo 0 > /sys/kernel/tracing/tracing_on'
sudo sh -c 'echo > /sys/kernel/tracing/set_event' # Clear events
External Resources:
Documentation/trace/ftrace.txt or ftrace.rst in the Linux
kernel source)trace-cmd Man Page: man trace-cmd (or find it online, e.g., on
Arch Linux man pages)Description: The Android Runtime (ART) method tracing format (commonly found
in .trace files) is a binary format specific to Android. It captures detailed
information about the execution of Java and Kotlin methods within an Android
application, essentially logging the entry and exit points of each called
method. This allows for a fine-grained analysis of an app's runtime behavior at
the method level.
Common Scenarios: This format is typically used when:
android.os.Debug.startMethodTracing() API.Perfetto Support:
.trace files can be opened directly in the Perfetto UI. The
method calls are typically visualized as a flamegraph, providing an intuitive
way to see where time is spent. They are also be displayed as nested slices on
the timeline for each thread..trace).
slice table. These slices are associated with their respective threads
and processes.How to Generate:
Android Studio CPU Profiler:
.trace file can then be exported from the Android Studio
profiler interface for use in Perfetto.Programmatically within an app: You can instrument your app's Java/Kotlin
code to start and stop method tracing using the android.os.Debug class:
import android.os.Debug;
// ...
// In your application code:
// To start tracing:
// Debug.startMethodTracing("myAppTraceName");
// The .trace file will typically be saved to a location like:
// /sdcard/Android/data/<your_app_package_name>/files/myAppTraceName.trace
// or /data/data/<your_app_package_name>/files/myAppTraceName.trace depending on Android version and permissions.
// ... execute the code you want to profile ...
// To stop tracing:
// Debug.stopMethodTracing();
After stopping, you'll need to pull the generated .trace file from the
device using ADB (e.g.,
adb pull /sdcard/Android/data/<your_app_package_name>/files/myAppTraceName.trace .).
The exact path can vary, so check your app's specific file storage location.
External Resources:
Debug class documentation:
developer.android.com/reference/android/os/Debug
(See startMethodTracing() and stopMethodTracing())Description: Apple's Instruments tool, part of Xcode, is used for
performance analysis on macOS and iOS. While Instruments saves its full data in
a proprietary .trace package format, Perfetto's support focuses on an XML
format that can be exported from these Instruments traces. This XML export is
primarily useful for extracting CPU profiling data (stack samples).
Common Scenarios: This import path is relevant when:
Perfetto Support:
cpu_profile_stack_sample for the samples themselves, and
stack_profile_callsite, stack_profile_frame, stack_profile_mapping for
the call stack information.How to Generate: Traces are originally collected using the Instruments
application in Xcode or the xctrace command-line utility, which produce a
.trace package. The XML file that Perfetto ingests is an export from such a
trace. (The specific steps for exporting to this XML format from Instruments
would need to be followed within the Instruments tool itself; Perfetto then
consumes the resulting XML file).
External Resources:
.ninja_log)Description: The Ninja build system, known for its speed and use in projects
like Chromium and Android, generates a log file typically named .ninja_log.
This file is a tab-separated text file that records metadata about each command
(build step) executed during the build process. Key information for each entry
includes the start time (in milliseconds), end time (in milliseconds), the
restat mtime (in milliseconds), the primary output file path of the build step,
and a hash of the command itself. The format is versioned, with new versions
occasionally adding fields.
Common Scenarios: This format is used when:
Perfetto Support:
.ninja_log files.
.ninja_log is typically imported as a
distinct slice into the slice table..ninja_log only records completed commands. It doesn't
provide information about dependencies directly in its per-step log format,
though this can sometimes be inferred by analyzing the sequence and timing of
output files.How to Generate:
.ninja_log file in the root of your build output
directory (e.g., out/Default/, build/, etc.) every time it runs a build..ninja_log
as it is a standard feature for build auditing and ninja -t recompact usage.External Resources:
Description: Android logcat is the command-line tool used to access messages
from Android's system-wide logging service, logd. The textual output from
adb logcat is what Perfetto can import. This output can vary significantly
based on the formatting options specified (e.g., via adb logcat -v <format>),
but typically includes a timestamp, log priority (Verbose, Debug, Info, Warn,
Error, Fatal/Assert), a tag identifying the source of the log, the Process ID
(PID), often the Thread ID (TID), and the log message itself.
Common Scenarios: You might work with textual logcat files when:
adb logcat sessions.bugreport.txt or as separate files).Perfetto Support:
android_logs SQL table. This
is the same table used when Perfetto collects logcat data natively via its
Android Log data source.adb logcat output formats, with good support for logcat -v long and
logcat -v threadtime. Other, more esoteric or heavily customized logcat
formats might not be fully parsed.How to Generate Textual Logcat Files:
adb logcat: The primary method is via the adb logcat command,
redirecting its output to a file.
# Dumps logs in 'long' format
adb logcat -d -v long > logcat_dump_long.txt
# Dumps logs in 'threadtime' format (timestamp, PID, TID, priority, tag, message)
adb logcat -d -v threadtime > logcat_dump_threadtime.txt
adb logcat -v long > logcat_stream_long.txt
# Or, for a more parse-friendly streaming format:
adb logcat -v threadtime > logcat_stream_threadtime.txt
adb bugreport. You can often find the logcat output
within the main bugreport.txt file or as separate log files within the bug
report archive.External Resources:
logcat Command-Line Tool (Official Android Documentation):
developer.android.com/studio/command-line/logcatDescription: An Android bugreport is a .zip archive generated by Android
devices, containing a comprehensive snapshot of diagnostic information from an
Android device at a particular point in time. This archive bundles various logs
(like logcat), system properties, process information, stack traces for ANRs and
crashes, and importantly, a system trace (typically a Perfetto trace on modern
Android versions). It also contains detailed dumpstate output, which includes
board-level information and specific service dumps like batterystats.
Common Scenarios: Bugreport zip files are primarily used for:
Perfetto Support:
.zip files.
.pftrace,
.perfetto-trace) in known locations (e.g.,
FS/data/misc/perfetto-traces/, proto/perfetto-trace.gz). The primary
Perfetto trace found is loaded for visualization and SQL querying.dumpstate board-level information (often found in
files like bugreport-*.txt or dumpstate_board.txt) into the
dumpstate SQL table. This table includes system properties, kernel
version, build fingerprints, and other hardware/software details.batterystats section
of the dumpstate into the battery_stats SQL table. This provides
information on battery levels, charging status, and power events over
time.dumpstate) and battery information (from
battery_stats) from the bugreport within a unified Perfetto environment,
without needing to manually extract these components.dumpstate like
batterystats. It generally does not attempt to import or parse legacy
Systrace files (systrace.html or systrace.txt) that might be present in
older bugreports. For analyzing those, you'd typically extract them manually
and open them as per the Android systrace format
section.How to Generate:
Using adb bugreport (from a computer connected to the device): This is
the most common method for developers.
adb bugreport ./my_bugreport_filename.zip
This command instructs the connected Android device to generate a bug report
and saves it as a .zip file to the specified path on your computer.
From Developer Options on the Android device:
.zip file (e.g., via email, a file sharing app, or by
saving it to cloud storage).External Resources:
Description: The Fuchsia trace format (typically found in .fxt files) is a
binary format used by the Fuchsia operating system. It's designed for
high-performance, low-overhead recording of diagnostic information from both
userspace components and the Zircon kernel. The format features compact,
memory-aligned records and is extensible, with trace data often written directly
into Zircon Virtual Memory Objects (VMOs) for efficiency.
Common Scenarios: This format is primarily encountered when:
Perfetto Support:
.fxt files can be opened directly in the Perfetto UI for
visualization. The UI can display various Fuchsia-specific events and system
activities.How to Generate:
ffx (Fuchsia's developer tool): The primary way to record traces
on a Fuchsia system from a development host is using the ffx trace start
command.trace utility: Fuchsia devices also include a trace
utility that can control tracing and save trace data.ktrace: For Zircon kernel-level tracing,
the ktrace command-line utility can be used.External Resources:
Description: The pprof format is a protocol buffer-based format used for
storing CPU profile data. pprof is a tool for visualization and analysis of
profiling data. It reads a collection of profiling samples in profile.proto
format and generates reports to visualize and help analyze the data. It was
developed for and is used by the Go programming language's pprof profiler,
but has since been adopted by a wide range of other profilers for other
languages (e.g. Python, C++, Rust, etc.).
Common Scenarios: The most common reason Perfetto users encounter this format is for:
perf profiles: pprof can read perf.data files
generated by the Linux perf
tool by using the perf_to_profile program from the
perf_data_converter package.Perfetto Support:
Perfetto UI: When a pprof file is opened, Perfetto visualizes the
profiling data as an interactive flamegraph. If the pprof file contains
multiple metrics (e.g., CPU time and memory allocations), the UI allows you
to switch between them, displaying a separate flamegraph for each metric.
This enables intuitive analysis of call stacks and helps identify performance
hotspots across different dimensions.
Here's an example of what that looks like
How to Generate: The most relevant generation path for Perfetto users
involves collecting CPU profiles from Go programs or converting perf.data files.
Collect a CPU profile from a Go program: You can either use the
runtime/pprof package to programmatically collect a profile or use the
net/http/pprof package to expose a profiling endpoint on a running server.
To collect a profile from a running server, you can use the go tool pprof
command:
go tool pprof http://localhost:6060/debug/pprof/profile?seconds=30
This will collect a 30-second CPU profile and open it in the pprof tool.
You can then save the profile to a file using the save command in the
pprof tool.
Convert Linux perf.data to pprof format: Use the perf_to_profile
tool from the perf_data_converter package.
perf_to_profile -i perf.data -o perf.pprof
External Resources:
perf tool:
perf Wikiperf_data_converter GitHub Repository:
https://github.com/google/perf_data_converterDescription: The Collapsed Stack format is a simple text-based format for representing profiling data, commonly used with Brendan Gregg's FlameGraph tools. Each line contains a semicolon-separated stack trace (from root to leaf) followed by a space and a sample count. This format is popular for its simplicity and is often used as an intermediate format when generating flame graphs from various profiling sources.
Format Specification:
frame1;frame2;frame3 count
# Lines starting with # are comments
;)# are treated as commentsCommon Scenarios: This format is typically used when:
perf script that has been processed through
stackcollapse-perf.pl or similar tools.Perfetto Support:
How to Generate:
The most common generation paths involve processing perf output:
# Record a profile
sudo perf record -F 99 -g -- ./my_program
# Convert to collapsed stack format
perf script | stackcollapse-perf.pl > profile.collapsed
# Open in Perfetto
# Navigate to ui.perfetto.dev and upload profile.collapsed
External Resources: