1*6dbdd20aSAndroid Build Coastguard Worker# Perfetto public API surface 2*6dbdd20aSAndroid Build Coastguard Worker 3*6dbdd20aSAndroid Build Coastguard Worker**This API surface is not stable yet, don't depend on it** 4*6dbdd20aSAndroid Build Coastguard Worker 5*6dbdd20aSAndroid Build Coastguard WorkerThis folder contains the public perfetto API headers. This allows an app to 6*6dbdd20aSAndroid Build Coastguard Workerinject trace events into perfetto with ~10 lines of code (see examples in 7*6dbdd20aSAndroid Build Coastguard Workerexamples/sdk/). 8*6dbdd20aSAndroid Build Coastguard Worker 9*6dbdd20aSAndroid Build Coastguard WorkerThe ext/ subdirectory expose the API-unstable classes and types that are 10*6dbdd20aSAndroid Build Coastguard Workerexposed to emvbedders that have exceptional requirements in terms of interposing 11*6dbdd20aSAndroid Build Coastguard Workertheir own custom IPC layer. To the day the only case is chromium. Nothing else 12*6dbdd20aSAndroid Build Coastguard Workershould depend on ext/. Contact perfetto-dev@ if you think you need to 13*6dbdd20aSAndroid Build Coastguard Workerdepend on an ext/ header. 14*6dbdd20aSAndroid Build Coastguard Worker 15*6dbdd20aSAndroid Build Coastguard WorkerHeaders in this folder must be hermetic. No ext/ perfetto header must be 16*6dbdd20aSAndroid Build Coastguard Workerleaked from the includes. 17*6dbdd20aSAndroid Build Coastguard Worker 18*6dbdd20aSAndroid Build Coastguard WorkerWhat is a client supposed to do to use tracing? See example below in this page. 19*6dbdd20aSAndroid Build Coastguard Worker 20*6dbdd20aSAndroid Build Coastguard Worker 21*6dbdd20aSAndroid Build Coastguard WorkerSource code layout: what goes where? 22*6dbdd20aSAndroid Build Coastguard Worker------------------------------------ 23*6dbdd20aSAndroid Build Coastguard Worker 24*6dbdd20aSAndroid Build Coastguard Worker**include/perfetto:** 25*6dbdd20aSAndroid Build Coastguard WorkerEmbedders are allowed to access and depend on any folder of this but ext/. 26*6dbdd20aSAndroid Build Coastguard WorkerThis contains classes to: (i) use tracing; (ii) extend the tracing internals 27*6dbdd20aSAndroid Build Coastguard Worker(i.e. implement the Platform). 28*6dbdd20aSAndroid Build Coastguard Worker 29*6dbdd20aSAndroid Build Coastguard WorkerRules: 30*6dbdd20aSAndroid Build Coastguard Worker- This directory should contain only .h files and no .cc files. 31*6dbdd20aSAndroid Build Coastguard Worker- Corresponding .cc files go into `src/`. 32*6dbdd20aSAndroid Build Coastguard Worker- .h files in here can depend only on `include/perfetto/` but not on 33*6dbdd20aSAndroid Build Coastguard Worker `include/perfetto/ext/`, 34*6dbdd20aSAndroid Build Coastguard Worker 35*6dbdd20aSAndroid Build Coastguard Worker**include/perfetto/tracing/internal:** 36*6dbdd20aSAndroid Build Coastguard WorkerThis directory contains headers that are required to implement the public-facing 37*6dbdd20aSAndroid Build Coastguard Workertracing API efficiently but that are not part of the API surface. 38*6dbdd20aSAndroid Build Coastguard WorkerIn an ideal world there would be no need of these headers and everything would 39*6dbdd20aSAndroid Build Coastguard Workerbe handle via forward-declarations and PIMPL patterns. Unfortunately, however, 40*6dbdd20aSAndroid Build Coastguard WorkerPIMPL cannot be used for inline functions, where the implementation needs to be 41*6dbdd20aSAndroid Build Coastguard Workerexposed in the public headers, which in turn need to depend on the memory layout 42*6dbdd20aSAndroid Build Coastguard Workerof structs/classes. 43*6dbdd20aSAndroid Build Coastguard Worker 44*6dbdd20aSAndroid Build Coastguard WorkerRules: 45*6dbdd20aSAndroid Build Coastguard Worker- All classes / types declared in this folder must be wrapped in the 46*6dbdd20aSAndroid Build Coastguard Worker ::perfetto::internal namespace. 47*6dbdd20aSAndroid Build Coastguard Worker- Both public and internal .h headers must not pull other perfetto headers 48*6dbdd20aSAndroid Build Coastguard Worker from ext/. 49*6dbdd20aSAndroid Build Coastguard Worker- .cc files instead can depend on other perfetto classes, as well as .h headers 50*6dbdd20aSAndroid Build Coastguard Worker located in src/. 51*6dbdd20aSAndroid Build Coastguard Worker- Embedders must not depend on the perfetto::internal namespace. 52*6dbdd20aSAndroid Build Coastguard Worker- Internal types cannot be used as input, output or return arguments of public 53*6dbdd20aSAndroid Build Coastguard Worker API functions. 54*6dbdd20aSAndroid Build Coastguard Worker- Internal types cannot be directly exposed to virtual methods that are 55*6dbdd20aSAndroid Build Coastguard Worker intended to be called or overridden by the embedder (e.g. TracingBackend's 56*6dbdd20aSAndroid Build Coastguard Worker methods). For those the solution is to create a matching non-internal base 57*6dbdd20aSAndroid Build Coastguard Worker class with a static factory method. 58*6dbdd20aSAndroid Build Coastguard Worker- We don't guarantee binary compatibility between versions (i.e. this client 59*6dbdd20aSAndroid Build Coastguard Worker library can only be statically linked) but we guarantee source-level 60*6dbdd20aSAndroid Build Coastguard Worker compatibility and ABI of the UNIX socket and shared memory buffers. 61*6dbdd20aSAndroid Build Coastguard Worker 62*6dbdd20aSAndroid Build Coastguard Worker**include/perfetto/public:** 63*6dbdd20aSAndroid Build Coastguard WorkerThis contains headers that can be used when dynamic linking with the perfetto 64*6dbdd20aSAndroid Build Coastguard Workershared library. 65*6dbdd20aSAndroid Build Coastguard Worker 66*6dbdd20aSAndroid Build Coastguard WorkerThese headers are not supposed to be exposed as part of the shared library ABI. 67*6dbdd20aSAndroid Build Coastguard Worker 68*6dbdd20aSAndroid Build Coastguard WorkerAll symbols, macros and types here start with the `perfetto_`, `PERFETTO_` or 69*6dbdd20aSAndroid Build Coastguard Worker`Perfetto` prefix. These prefixes are reserved and should not be used elsewhere 70*6dbdd20aSAndroid Build Coastguard Workerwhen linking with the perfetto shared library. 71*6dbdd20aSAndroid Build Coastguard Worker 72*6dbdd20aSAndroid Build Coastguard Worker**include/perfetto/public/abi:** 73*6dbdd20aSAndroid Build Coastguard WorkerSubset of headers that are part of the shared library ABI (**not stable yet**). 74*6dbdd20aSAndroid Build Coastguard WorkerThese headers are supposed to be hermetic (i.e. they should not include anything 75*6dbdd20aSAndroid Build Coastguard Workeroutside the abi directory). 76*6dbdd20aSAndroid Build Coastguard Worker 77*6dbdd20aSAndroid Build Coastguard WorkerUsage example 78*6dbdd20aSAndroid Build Coastguard Worker------------- 79*6dbdd20aSAndroid Build Coastguard Worker1. Call `perfetto::Tracing::Initialize(...)` once, when starting the app. 80*6dbdd20aSAndroid Build Coastguard Worker While doing so the app can chose the tracing model: 81*6dbdd20aSAndroid Build Coastguard Worker - Fully in-process: the service runs in a thread within the same process. 82*6dbdd20aSAndroid Build Coastguard Worker - System: connects to the traced system daemon via a UNIX socket. This allows 83*6dbdd20aSAndroid Build Coastguard Worker the app to join system-wide tracing sessions. This is available only on 84*6dbdd20aSAndroid Build Coastguard Worker Linux/Android/MacOS for now. 85*6dbdd20aSAndroid Build Coastguard Worker - Private dedicated process: similar to the in-process case, but the service 86*6dbdd20aSAndroid Build Coastguard Worker runs in a dedicated process rather than a thread. This is for performance, 87*6dbdd20aSAndroid Build Coastguard Worker stability and security isolation. Also, this is not implemented yet. 88*6dbdd20aSAndroid Build Coastguard Worker - Custom backend: this is for peculiar cases (mainly chromium) where the 89*6dbdd20aSAndroid Build Coastguard Worker embedder is multi-process but wants to use a different IPC mechanism. The 90*6dbdd20aSAndroid Build Coastguard Worker embedder needs to deal with the larger and clunkier set of perfetto APIs. 91*6dbdd20aSAndroid Build Coastguard Worker Reach out to the team before using this mode. It's very unlikely you need 92*6dbdd20aSAndroid Build Coastguard Worker this unless you are a project rolled into chromium. 93*6dbdd20aSAndroid Build Coastguard Worker 94*6dbdd20aSAndroid Build Coastguard Worker2. Define and register one or more data sources, like this: 95*6dbdd20aSAndroid Build Coastguard Worker```cpp 96*6dbdd20aSAndroid Build Coastguard Worker #include "perfetto/tracing.h" 97*6dbdd20aSAndroid Build Coastguard Worker 98*6dbdd20aSAndroid Build Coastguard Worker class MyDataSource : public perfetto::DataSource<MyDataSource> { 99*6dbdd20aSAndroid Build Coastguard Worker void OnSetup(const SetupArgs&) override {} 100*6dbdd20aSAndroid Build Coastguard Worker void OnStart(const StartArgs&) override {} 101*6dbdd20aSAndroid Build Coastguard Worker void OnStop(const StopArgs&) override {} 102*6dbdd20aSAndroid Build Coastguard Worker }; 103*6dbdd20aSAndroid Build Coastguard Worker ... 104*6dbdd20aSAndroid Build Coastguard Worker perfetto::DataSourceDescriptor dsd; 105*6dbdd20aSAndroid Build Coastguard Worker dsd.set_name("my_data_source"); 106*6dbdd20aSAndroid Build Coastguard Worker MyDataSource::Register(dsd); 107*6dbdd20aSAndroid Build Coastguard Worker``` 108*6dbdd20aSAndroid Build Coastguard Worker 109*6dbdd20aSAndroid Build Coastguard Worker3. Optionally define a new proto schema in `trace_packet.proto` 110*6dbdd20aSAndroid Build Coastguard Worker 111*6dbdd20aSAndroid Build Coastguard Worker4. Emit trace events 112*6dbdd20aSAndroid Build Coastguard Worker```cpp 113*6dbdd20aSAndroid Build Coastguard Worker MyDataSource::Trace([](MyDataSource::TraceContext ctx) { 114*6dbdd20aSAndroid Build Coastguard Worker auto trace_packet = ctx.NewTracePacket(); 115*6dbdd20aSAndroid Build Coastguard Worker trace_packet->set_timestamp(...); 116*6dbdd20aSAndroid Build Coastguard Worker auto* my_custom_proto = trace_packet->set_my_custom_proto(); 117*6dbdd20aSAndroid Build Coastguard Worker }); 118*6dbdd20aSAndroid Build Coastguard Worker``` 119*6dbdd20aSAndroid Build Coastguard Worker 120*6dbdd20aSAndroid Build Coastguard WorkerThe passed lambda will be called only if tracing is enabled and the data source 121*6dbdd20aSAndroid Build Coastguard Workerwas enabled in the trace config. It might be called multiple times, one for each 122*6dbdd20aSAndroid Build Coastguard Workeractive tracing session, in case of concurrent tracing sessions (or even within a 123*6dbdd20aSAndroid Build Coastguard Workersingle tracing session, if the data source is listed twice in the trace config). 124