1# Life of a Perfetto tracing session
2
3This document explains how producer, service and consumer interact end-to-end
4during a tracing session, with references to code and IPC requests / responses.
5
61.  One or more producers connect to the tracing service and sets up their IPC
7    channels.
82.  Each producer advertises one or more data sources through the
9    [`RegisterDataSource`](/protos/perfetto/ipc/producer_port.proto#34) IPC.
10    Nothing more happens on the Producer until this point. Nothing traces by
11    default.
123.  A consumer connects to the tracing service and sets up the IPC channel.
134.  The consumer starts a tracing session sending a
14    [trace config](trace-config.md) to the service through the
15    [`EnableTracing`](/protos/perfetto/ipc/consumer_port.proto#65) IPC.
166.  The service creates as many new trace buffers as specified in the config.
177.  The service iterates through the
18    [`data_sources`](/protos/perfetto/config/trace_config.proto#50) section of
19    the trace config: for each entry, if a matching data source is found in the
20    producer(s) (accordingly to what advertised in step 2):
218.  The service sends a
22    [`SetupTracing`](/protos/perfetto/ipc/producer_port.proto#112) IPC message,
23    passing a shared memory buffer  to the producer(s) (only once for each
24    producer).
259.  The service sends a
26    [`StartDataSource`](/protos/perfetto/ipc/producer_port.proto#105) IPC message
27    to each producer, for each data source configured in the trace config and
28    present in the producer (if any).
2910. The producer creates one or more data source instance, as instructed in
30    the previous step.
3111. Each data source instance creates one or more
32    [`TraceWriter`](/include/perfetto/tracing/core/trace_writer.h) (typically
33    one for each thread).
3412. Each `TraceWriter` writes one or more
35    [`TracePacket`](/protos/perfetto/trace/trace_packet.proto).
3613. While doing so, each `TraceWriter` takes ownership of shared memory buffer's
37    chunks, using the [`SharedMemoryArbiter`](/include/perfetto/tracing/core/shared_memory_arbiter.h).
3814. While writing a `TracePacket`, the `TraceWriter` will unavoidably cross the
39    chunk boundary (typically 4KB, but can configured to be smaller).
4015. When this happens the `TraceWriter` will release the current chunk and
41    acquire a new chunk through the `SharedMemoryArbiter`.
4216. The `SharedMemoryArbiter` will, out-of-band, send a
43    [`CommitDataRequest`](/protos/perfetto/ipc/producer_port.proto#41) to the
44    service, requesting it to move some chunks of the shared memory buffer into
45    the final trace buffer.
4617. If one or more long `TracePacket` were fragmented over several chunks, it is
47    possible that some of these chunks are gone from the the shared memory
48    buffer and committed into the final trace buffer (step 16). In this case,
49    the `SharedMemoryArbiter` will send an other `CommitDataRequest` IPC message
50    to request the out-of-band patching of the chunk data into the final trace
51    buffer.
5218. The service will check if the given chunk, identified by the tuple
53    `{ProducerID (unspoofable), WriterID, ChunkID}` is still present in the
54    trace buffer and if so will proceed to patch it (% sanity checks).
5519. The consumer sends a [`FlushRequest`](/perfetto/ipc/consumer_port.proto#52)
56    to the service, asking it commit all data on flight in the trace buffers.
5720. The service, in turn, issues a
58    [`Flush`](/protos/perfetto/ipc/producer_port.proto#132) request to all
59    producers involved in the trace session.
6021. The producer(s) will `Flush()` all their `TraceWriter` and reply to the
61    service flush request.
6222. Once the service has received an ACK to all flush requests from all
63    producers (or the
64    [flush timeout](/protos/perfetto/ipc/consumer_port.proto#117) has expired)
65    it replies to the consumer's `FlushRequest`
6623. The consumer optionally sends a
67    [`DisableTracing`](/protos/perfetto/ipc/consumer_port.proto#38) IPC request
68    to stop tracing and freeze the content of the trace buffers.
6924. The service will in turn broadcast a
70    [`StopDataSource`](/protos/perfetto/ipc/producer_port.proto#110) request for
71    each data source in each Producer.
7223. At this point the Consumer issues a
73    [`ReadBuffers`](/protos/perfetto/ipc/consumer_port.proto#41) IPC request
74    (unless it did previously pass a file descriptor to the service when
75    enabling the trace through the `write_into_file` field of the trace config).
7624. The service reads the trace buffers and streams all the `TracePacket(s)`
77    back to the consumer.
7825. If a trace packet stored in the trace buffer is incomplete (e.g., a fragment
79    is missing) or is marked as pending out-of-band patching, the given writer
80    sequence is interrupted and no more packets for that sequence are read.
81    Other packets for other `TraceWriter` sequences will be unaffected.
8226. The consumer sends a `FreeBuffers` (or simply disconnects).
8327. The service tears down all the trace buffers for the session.
84