1# Embedding Perfetto 2 3## Trace Processor 4 5### Building 6 7As with all components in Perfetto, the trace processor can be built in several build systems: 8 9- GN (the native system) 10- Bazel 11- As part of the Android tree 12 13The 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). 14 15The 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. 16 17The 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. 18 19### Library structure 20 21The trace processor library is structured around the `TraceProcessor` class; all API methods exposed by trace processor are member functions on this class. 22 23The C++ header for this class is split between two files: [include/perfetto/trace_processor/trace_processor_storage.h](/include/perfetto/trace_processor/trace_processor_storage.h) and [include/perfetto/trace_processor/trace_processor.h](/include/perfetto/trace_processor/trace_processor.h). 24 25### Reading traces 26 27To 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. 28 29As this is a common task, a helper function `ReadTrace` is provided in [include/perfetto/trace_processor/read_trace.h](/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. 30 31### Executing queries 32 33The `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. 34 35WARNING: embedders should ensure that the iterator is forwarded using `Next` before any other functions are called on the iterator. 36 37WARNING: 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. 38 39### Metrics 40 41Any 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. 42 43Metrics can also be registered at run time using the `RegisterMetric` and `ExtendMetricsProto` functions. These can subsequently be executed with `ComputeMetric`. 44 45WARNING: 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. 46 47### Annotations 48 49The `DescribeSlice` function is exposed to SQL through the `describe_slice` table. This table has the following schema: 50 51| Name | Type | Meaning | 52| :---------- | ------ | ------------------------------------------------------------ | 53| description | string | Provides the description for the given slice | 54| doc_link | string | Provides a hyperlink to documentation which gives more context for the slice | 55 56The 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`: 57 58```sql 59select description, doc_link 60from describe_slice 61where slice_id = 5 62``` 63 64The `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: 65 66```sql 67select ts, dur, description 68from slice s 69join desribe_slice d on s.id = d.slice_id 70where name = 'measure' 71``` 72 73### Creating derived events 74 75As 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. 76 77NOTE: 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. 78 79