• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
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: 18.
61// Reserved ID: 15
62message DebugAnnotation {
63  // Name fields are set only for dictionary entries.
64  oneof name_field {
65    // interned DebugAnnotationName.
66    uint64 name_iid = 1;
67    // non-interned variant.
68    string name = 10;
69  }
70
71  oneof value {
72    bool bool_value = 2;
73    uint64 uint_value = 3;
74    int64 int_value = 4;
75    double double_value = 5;
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    // interned and non-interned variants of strings.
88    string string_value = 6;
89    // Corresponds to |debug_annotation_string_values| field in InternedData.
90    uint64 string_value_iid = 17;
91  }
92
93  // Used to embed arbitrary proto messages (which are also typically used to
94  // represent typed TrackEvent arguments). |proto_type_name| or
95  // |proto_type_name_iid| are storing the full name of the proto messages (e.g.
96  // .perfetto.protos.DebugAnnotation) and |proto_value| contains the serialised
97  // proto messages. See |TracedValue::WriteProto| for more details.
98  oneof proto_type_descriptor {
99    string proto_type_name = 16;
100    // interned DebugAnnotationValueTypeName.
101    uint64 proto_type_name_iid = 13;
102  }
103  optional bytes proto_value = 14;
104
105  repeated DebugAnnotation dict_entries = 11;
106  repeated DebugAnnotation array_values = 12;
107
108  // Deprecated legacy way to use nested values. Only kept for
109  // backwards-compatibility in TraceProcessor. May be removed in the future -
110  // code filling protos should use |dict_entries| and |array_values| instead.
111  message NestedValue {
112    enum NestedType {
113      // leaf value.
114      UNSPECIFIED = 0;
115      DICT = 1;
116      ARRAY = 2;
117    }
118    optional NestedType nested_type = 1;
119
120    repeated string dict_keys = 2;
121    repeated NestedValue dict_values = 3;
122    repeated NestedValue array_values = 4;
123    optional int64 int_value = 5;
124    optional double double_value = 6;
125    optional bool bool_value = 7;
126    optional string string_value = 8;
127  }
128}
129
130// --------------------
131// Interned data types:
132// --------------------
133
134message DebugAnnotationName {
135  optional uint64 iid = 1;
136  optional string name = 2;
137}
138
139// See the |proto_type_descriptor| comment.
140message DebugAnnotationValueTypeName {
141  optional uint64 iid = 1;
142  optional string name = 2;
143}
144