xref: /aosp_15_r20/external/perfetto/include/README.md (revision 6dbdd20afdafa5e3ca9b8809fa73465d530080dc)
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