1Extensions: adding new types to traces
2======================================
3
4NOTE: **extensions are work-in-progress and are not ready to be used at the
5moment**
6
7Currently, it is not possible to add new types to traces while using Perfetto
8without modifying Perfetto proto message definitions upstream.
9
10This page describes ongoing work to use [protobuf
11extensions](https://developers.google.com/protocol-buffers/docs/overview#extensions)
12in order to make it possible to define new typed messages outside of the
13Perfetto repository.
14
15Protozero support
16-----------------
17
18Perfetto uses its own implementation of code generation for protocol buffer
19messages called [Protozero](/docs/design-docs/protozero.md), which is not a
20full-fledged protobuf implementation. Implementation of extensions is fairly
21limited, and all extensions are supposed to be nested inside a message that is
22used in order to provide the class name for generated code.
23
24For example,
25
26    message MyEvent {
27        extend TrackEvent {
28            optional string custom_string = 1000;
29        }
30    }
31
32Is going to generate a subclass of `TrackEvent` called `MyEvent`, that is going
33to have a new method to set `custom_string` in addition to all other protobuf
34fields defined in `TrackEvent`.
35
36Deserialization
37---------------
38
39When analyzing traces, protos are not used directly and instead are parsed into
40database, which can be queried by SQL. In order to make it possible, Perfetto
41has to know field descriptors (the binary representation of the extended proto
42schema) of the extensions. Currently, the only way to do that is to add an
43[ExtensionDescriptor
44packet](reference/trace-packet-proto.autogen#ExtensionDescriptor). In the
45future, there is going to be a way to specify protobuf extensions at compile
46time in order to be able to avoid this overhead in every single trace.
47
48However, an ability to specify extension descriptors in the trace itself will
49still be useful in order to be able to use a pre-compiled trace processor in the
50UI when adding new typed messages during local development.
51
52Deserialization of protobuf extension are supported only for TrackEvent message
53at the moment, and is implemented in trace processor via ProtoToArgsUtils class.
54The extensions will appear in args table, similar to other trace event
55arguments.
56
57Testing extensions support inside Perfetto
58------------------------------------------
59
60Perfetto trace processor is mostly tested by integration tests, where input
61traces are specified most frequently in textproto format. Textproto format
62supports extensions, but the parser has to be aware of all the extensions used.
63In order to make it possible, all the extensions that are used in integration
64tests have to be specified in the `test_extensions.proto` file. Since this file
65is only used in the testing harness and is parsed by protoc, it does not have to
66adhere to the convention of all extensions being inside a wrapper message, which
67helps with making extension identifiers more concise.
68