| Primiano Tucci | b808373 | 2018-04-09 15:38:37 +0100 | [diff] [blame] | 1 | # Perfetto trace format |
| 2 | |
| 3 | *** note |
| 4 | **This doc is WIP**, stay tuned. |
| 5 | <!-- TODO(primiano): write trace format doc. --> |
| 6 | *** |
| 7 | |
| 8 | A Perfetto trace is guaranteed to be a a linear sequence of `TracePacket(s)` |
| 9 | (see [trace_packet.proto](/protos/perfetto/trace/trace_packet.proto)). |
| 10 | |
| 11 | As a key part of the Perfetto design, the tracing service is agnostic of the |
| 12 | content of TracePacket, modulo the few fields defined in |
| 13 | [trusted_packet.proto](/protos/perfetto/trace/trusted_packet.proto) that are |
| 14 | produced by the service itself. |
| 15 | |
| 16 | Each data source can extend the trace with their app-specific protobuf schema. |
| 17 | *** aside |
| 18 | TODO(primiano): we should reserve an extension range and figure out / comment a |
| 19 | hash to assign sub-message IDs, even without checking them into |
| 20 | trace_packet.proto. |
| 21 | *** |
| 22 | |
| 23 | |
| 24 | **Linearity guarantees** |
| 25 | The tracing service guarantees that all `TracePacket(s)` written by a given |
| 26 | `TraceWriter` are seen in-order, without gaps or duplicates. If, for any reason, |
| 27 | a `TraceWriter` sequence becomes invalid, no more packets are returned to the |
| 28 | Consumer (or written into the trace file). |
| 29 | |
| 30 | However, `TracePacket(s)` written by different `TraceWriter` (hence even |
| 31 | different producers) can be seen in no particular order. |
| 32 | The consumer can re-establish a total order, if interested, using the packet |
| 33 | timestamps (after having synchronized the different clocks onto a global clock). |
