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 name used to execute the metric and output view in the SQL. 46