1/*
2 * Copyright (C) 2019 The Android Open Source Project
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 *      http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
17syntax = "proto2";
18
19package perfetto.protos;
20
21// Proto representation of untyped key/value annotations provided in TRACE_EVENT
22// macros. Users of the Perfetto SDK should prefer to use the
23// perfetto::TracedValue API to fill these protos, rather than filling them
24// manually.
25//
26// Debug annotations are intended for debug use and are not considered a stable
27// API of the trace contents. Trace-based metrics that use debug annotation
28// values are prone to breakage, so please rely on typed TrackEvent fields for
29// these instead.
30//
31// DebugAnnotations support nested arrays and dictionaries. Each entry is
32// encoded as a single DebugAnnotation message. Only dictionary entries
33// set the "name" field. The TrackEvent message forms an implicit root
34// dictionary.
35//
36// Example TrackEvent with nested annotations:
37//   track_event {
38//     debug_annotations {
39//       name: "foo"
40//       dict_entries {
41//         name: "a"
42//         bool_value: true
43//       }
44//       dict_entries {
45//         name: "b"
46//         int_value: 123
47//       }
48//     }
49//     debug_annotations {
50//       name: "bar"
51//       array_values {
52//         string_value: "hello"
53//       }
54//       array_values {
55//         string_value: "world"
56//       }
57//     }
58//   }
59//
60// Next ID: 13.
61message DebugAnnotation {
62  // Name fields are set only for dictionary entries.
63  oneof name_field {
64    // interned DebugAnnotationName.
65    uint64 name_iid = 1;
66    // non-interned variant.
67    string name = 10;
68  }
69
70  oneof value {
71    bool bool_value = 2;
72    uint64 uint_value = 3;
73    int64 int_value = 4;
74    double double_value = 5;
75    string string_value = 6;
76    // Pointers are stored in a separate type as the JSON output treats them
77    // differently from other uint64 values.
78    uint64 pointer_value = 7;
79
80    // Deprecated. Use dict_entries / array_values instead.
81    NestedValue nested_value = 8;
82
83    // Legacy instrumentation may not support conversion of nested data to
84    // NestedValue yet.
85    string legacy_json_value = 9;
86  }
87
88  repeated DebugAnnotation dict_entries = 11;
89  repeated DebugAnnotation array_values = 12;
90
91  // Deprecated legacy way to use nested values. Only kept for
92  // backwards-compatibility in TraceProcessor. May be removed in the future -
93  // code filling protos should use |dict_entries| and |array_values| instead.
94  message NestedValue {
95    enum NestedType {
96      // leaf value.
97      UNSPECIFIED = 0;
98      DICT = 1;
99      ARRAY = 2;
100    }
101    optional NestedType nested_type = 1;
102
103    repeated string dict_keys = 2;
104    repeated NestedValue dict_values = 3;
105    repeated NestedValue array_values = 4;
106    optional int64 int_value = 5;
107    optional double double_value = 6;
108    optional bool bool_value = 7;
109    optional string string_value = 8;
110  }
111}
112
113// --------------------
114// Interned data types:
115// --------------------
116
117message DebugAnnotationName {
118  optional uint64 iid = 1;
119  optional string name = 2;
120}
121