1 # Life of a Perfetto tracing session 2 3 This document explains how producer, service and consumer interact end-to-end 4 during a tracing session, with references to code and IPC requests / responses. 5 6 1. One or more producers connect to the tracing service and sets up their IPC 7 channels. 8 2. 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. 12 3. A consumer connects to the tracing service and sets up the IPC channel. 13 4. 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. 16 6. The service creates as many new trace buffers as specified in the config. 17 7. 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): 21 8. 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). 25 9. 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). 29 10. The producer creates one or more data source instance, as instructed in 30 the previous step. 31 11. Each data source instance creates one or more 32 [`TraceWriter`](/include/perfetto/tracing/core/trace_writer.h) (typically 33 one for each thread). 34 12. Each `TraceWriter` writes one or more 35 [`TracePacket`](/protos/perfetto/trace/trace_packet.proto). 36 13. 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). 38 14. While writing a `TracePacket`, the `TraceWriter` will unavoidably cross the 39 chunk boundary (typically 4KB, but can configured to be smaller). 40 15. When this happens the `TraceWriter` will release the current chunk and 41 acquire a new chunk through the `SharedMemoryArbiter`. 42 16. 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. 46 17. 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. 52 18. 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). 55 19. 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. 57 20. 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. 60 21. The producer(s) will `Flush()` all their `TraceWriter` and reply to the 61 service flush request. 62 22. 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` 66 23. 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. 69 24. 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. 72 23. 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). 76 24. The service reads the trace buffers and streams all the `TracePacket(s)` 77 back to the consumer. 78 25. 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. 82 26. The consumer sends a `FreeBuffers` (or simply disconnects). 83 27. The service tears down all the trace buffers for the session. 84
