4.4 KiB
Embedding Perfetto
Trace Processor
Building
As with all components in Perfetto, the trace processor can be built in several build systems:
- GN (the native system)
- Bazel
- As part of the Android tree
The trace processor is exposed as a static library //:trace_processor
to Bazel and src/trace_processor:trace_processor
in GN; it is not exposed to Android (but patches to add support for this are welcome).
The trace processor is also built as a WASM target src/trace_processor:trace_processor_wasm
for the Perfetto UI; patches for adding support for other supported build systems are welcome.
The trace processor is also built as a shell binary, trace_processor_shell
which backs the trace_processor
tool described in other parts of the documentation. This is exposed as the trace_processor_shell
target to Android, //:trace_processor_shell
to Bazel and src/trace_processor:trace_processor_shell
in GN.
Library structure
The trace processor library is structured around the TraceProcessor
class; all API methods exposed by trace processor are member functions on this class.
The C++ header for this class is split between two files: include/perfetto/trace_processor/trace_processor_storage.h and include/perfetto/trace_processor/trace_processor.h.
Reading traces
To ingest a trace into trace processor, the Parse
function can be called multiple times to with chunks of the trace and NotifyEndOfFile
can be called at the end.
As this is a common task, a helper function ReadTrace
is provided in include/perfetto/trace_processor/read_trace.h. This will read a trace file directly from the filesystem and calls into appropriate TraceProcessor
functions to perform parsing.
Executing queries
The ExecuteQuery
function can be called with an SQL statement to execute. This will return an iterator which can be used to retrieve rows in a streaming fashion.
WARNING: embedders should ensure that the iterator is forwarded using Next
before any other functions are called on the iterator.
WARNING: embedders should ensure that the status of the iterator is checked after every row and at the end of iteration to verify that the query was successful.
Metrics
Any registered metrics can be computed using using the ComputeMetric
function. Any metric in src/trace_processor/metrics
is built-in to trace processor so can be called without any other steps.
Metrics can also be registered at run time using the RegisterMetric
and ExtendMetricsProto
functions. These can subsequently be executed with ComputeMetric
.
WARNING: embedders should ensure that the path of any registered metric is consistent with the the name used to execute the metric and output view in the SQL.
Annotations
The DescribeSlice
function is exposed to SQL through the describe_slice
table. This table has the following schema:
Name | Type | Meaning |
---|---|---|
description | string | Provides the description for the given slice |
doc_link | string | Provides a hyperlink to documentation which gives more context for the slice |
The table also has a hidden column slice_id
which needs to be set equal to the id of the slice for which to get the description. For example, to get the description and doc link for slice with id 5
:
select description, doc_link
from describe_slice
where slice_id = 5
The describe_slice
table can also be joined with the slice table to obtain descriptions for more than one slice. For example, to get the ts
, dur
and description
for all measure
slices:
select ts, dur, description
from slice s
join desribe_slice d on s.id = d.slice_id
where name = 'measure'
Creating derived events
As creating derived events is tied to the metrics subsystem, the ComputeMetrics
function in the trace processor API should be called with the appropriate metrics. This will create the <metric_name>_event
table/view which can then be queried using the ExectueQuery
function.
NOTE: At some point, there are plans to add an API which does not create the metrics proto but just executes the queries in the metric.