1# Service-based model 2 3 4 5## Service 6 7The tracing service is a long-lived entity (a system daemon on Linux/Android, 8a service in Chrome) that has the following responsibilities: 9 10* Maintains a registry of active producers and their data sources. 11* Owns the trace buffers. 12* Handles multiplexing of several tracing sessions. 13* Routes the trace config from the consumers to the corresponding producers. 14* Tells the Producers when and what to trace. 15* Moves data from the Producer's shared memory buffer to the central non-shared 16 trace buffers. 17 18## Producer 19 20A producer is an untrusted entity that offers the ability to contribute to the 21trace. In a multiprocess model, a producer almost always corresponds to a client 22process of the tracing service. It advertises its ability to contribute to the trace with one or more data sources. 23Each producer has exactly: 24 25* One shared memory buffer, shared exclusively with the tracing service. 26* One IPC channel with the tracing service. 27 28A producer is completely decoupled (both technically and conceptually) from 29consumer(s). A producer knows nothing about: 30 31* How many consumer(s) are connected to the service. 32* How many tracing sessions are active. 33* How many other producer(s) are registered or active. 34* Trace data written by other producer(s). 35 36NOTE: In rare circumstances a process can host more than one producer and hence more 37than one shared memory buffer. This can be the case for a process bundling 38third-party libraries that in turn include the Perfetto client library. 39Concrete example: at some point in the future Chrome might expose one Producer for tracing within the main project, one for V8 and one for Skia (for each child 40process). 41 42## Consumer 43A consumer is a trusted entity (a cmdline client on Linux/Android, an interface 44of the Browser process in Chrome) that controls (non-exclusively) the tracing service and reads back (destructively) the trace buffers. 45A consumer has the ability to: 46* Send a [trace config](#) to the service, determining: 47 * How many trace buffers to create. 48 * How big the trace buffers should be. 49 * The policy for each buffer (*ring-buffer* or *stop-when-full*). 50 * Which data sources to enable. 51 * The configuration for each data source. 52 * The target buffer for the data produced by each data source configured. 53* Enable and disable tracing. 54* Read back the trace buffers: 55 * Streaming data over the IPC channel. 56 * Passing a file descriptor to the service and instructing it to periodically 57 save the trace buffers into the file. 58 59## Data source 60 61A data source is a capability, exposed by a Producer, of providing some tracing 62data. A data source almost always defines its own schema (a protobuf) consisting 63of: 64* At most one `DataSourceConfig` sub-message: 65 66 ([example](/protos/perfetto/config/ftrace/ftrace_config.proto)) 67* One or more `TracePacket` sub-messages 68 ([example](/protos/perfetto/trace/ps/process_tree.proto)) 69 70Different producers may expose the same data source. Concrete example: 71*** aside 72At some point in the near future we might offer, as part of Perfetto, a library 73for in-process heap profiling. In such case more than one producer, linking 74against the updated Perfetto library, will expose the heap profiler data source, 75for its own process. 76** 77 78## IPC channel 79In a multiprocess scenario, each producer and each consumer interact with the 80service using an IPC channel. IPC is used only in non-fast-path interactions, 81mostly handshakes such as enabling/disabling trace (consumer), (un)registering 82and starting/stopping data sources (producer). The IPC is typically NOT employed 83to transport the protobufs for the trace. 84Perfetto provides a POSIX-friendly IPC implementation, based on protobufs over a 85UNIX socket (see 86[Socket protocol](/docs/design-docs/api-and-abi#socket-protocol)). 87 88That IPC implementation is not mandated. Perfetto allows the embedder: 89 90* Wrap its own IPC subsystem (e.g., Perfetto in Chromium uses Mojo) 91* Not use an IPC mechanism at all and just short circuit the 92 Producer <> Service <> Consumer interaction via `PostTask(s)`. 93 94## Shared memory buffer 95Producer(s) write tracing data, in the form of protobuf-encoded binary blobs, 96directly into its shared memory buffer, using a special library called 97[ProtoZero](/docs/design-docs/protozero.md). The shared memory buffer: 98 99* Has a fixed and typically small size (configurable, default: 128 KB). 100* Is an ABI and must maintain backwards compatibility. 101* Is shared by all data sources of the producer. 102* Is independent of the number and the size of the trace buffers. 103* Is independent of the number of Consumer(s). 104* Is partitioned in *chunks* of variable size. 105 106Each chunk: 107 108* Is owned exclusively by one Producer thread (or shared through a mutex). 109* Contains a linear sequence of `TracePacket(s)`, or 110 fragments of that. A `TracePacket` can span across several chunks, the 111 fragmentation is not exposed to the consumers (consumers always see whole 112 packets as if they were never fragmented). 113* Can be owned and written by exactly one `TraceWriter`. 114* Is part of a reliable and ordered sequence, identified by the `WriterID`: 115 packets in a sequence are guaranteed to be read back in order, without gaps 116 and without repetitions. 117 118See the comments in 119[shared_memory_abi.h](/include/perfetto/ext/tracing/core/shared_memory_abi.h) 120for more details about the binary format of this buffer. 121
){kind=link}