1/*
2 * Copyright (C) 2018 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
21import "protos/perfetto/common/descriptor.proto";
22
23// This file defines the schema for {,un}marshalling arguments and return values
24// when interfacing to the trace processor binary interface.
25
26// The Trace Processor can be used in three modes:
27// 1. Fully native from C++ or directly using trace_processor_shell.
28//    In this case, this file isn't really relevant because no binary
29//    marshalling is involved. Look at include/trace_processor/trace_processor.h
30//    for the public C++ API definition.
31// 2. Using WASM within the HTML ui. In this case these messages are used to
32//    {,un}marshall calls made through the JS<>WASM interop in
33//    src/trace_processor/rpc/wasm_bridge.cc .
34// 3. Using the HTTP+RPC interface, by running trace_processor_shell -D.
35//    In this case these messages are used to {,un}marshall HTTP requests and
36//    response made through src/trace_processor/rpc/httpd.cc .
37
38// Input for the /raw_query endpoint.
39message RawQueryArgs {
40  optional string sql_query = 1;
41
42  // Wall time when the query was queued. Used only for query stats.
43  optional uint64 time_queued_ns = 2;
44}
45
46// Output for the /raw_query endpoint.
47// DEPRECATED, use /query. See QueryResult below.
48message RawQueryResult {
49  message ColumnDesc {
50    optional string name = 1;
51    enum Type {
52      UNKNOWN = 0;
53      LONG = 1;
54      DOUBLE = 2;
55      STRING = 3;
56    }
57    optional Type type = 2;
58  }
59  message ColumnValues {
60    // Only one of this field will be filled for each column (according to the
61    // corresponding descriptor) and that one will have precisely |num_records|
62    // elements.
63    repeated int64 long_values = 1;
64    repeated double double_values = 2;
65    repeated string string_values = 3;
66
67    // This will be set to true or false depending on whether the data at the
68    // given index is NULL.
69    repeated bool is_nulls = 4;
70  }
71  repeated ColumnDesc column_descriptors = 1;
72  optional uint64 num_records = 2;
73  repeated ColumnValues columns = 3;
74  optional string error = 4;
75  optional uint64 execution_time_ns = 5;
76}
77
78// Output for the /query endpoint.
79// Returns a query result set, grouping cells into batches. Batching allows a
80// more efficient encoding of results, at the same time allowing to return
81// O(M) results in a pipelined fashion, without full-memory buffering.
82// Batches are split when either a large number of cells (~thousands) is reached
83// or the string/blob payload becomes too large (~hundreds of KB).
84// Data is batched in cells, scanning results by row -> column. e.g. if a query
85// returns 3 columns and 2 rows, the cells will be emitted in this order:
86// R0C0, R0C1, R0C2, R1C0, R1C1, R1C2.
87message QueryResult {
88  // This determines the number and names of columns.
89  repeated string column_names = 1;
90
91  // If non-emty the query returned an error. Note that some cells might still
92  // be present, if the error happened while iterating.
93  optional string error = 2;
94
95  // A batch contains an array of cell headers, stating the type of each cell.
96  // The payload of each cell is stored in the corresponding xxx_cells field
97  // below (unless the cell is NULL).
98  // So if |cells| contains: [VARINT, FLOAT64, VARINT, STRING], the results will
99  // be available as:
100  // [varint_cells[0], float64_cells[0], varint_cells[1], string_cells[0]].
101  message CellsBatch {
102    enum CellType {
103      CELL_INVALID = 0;
104      CELL_NULL = 1;
105      CELL_VARINT = 2;
106      CELL_FLOAT64 = 3;
107      CELL_STRING = 4;
108      CELL_BLOB = 5;
109    }
110    repeated CellType cells = 1 [packed = true];
111
112    repeated int64 varint_cells = 2 [packed = true];
113    repeated double float64_cells = 3 [packed = true];
114    repeated bytes blob_cells = 4;
115
116    // The string cells are concatenated in a single field. Each cell is
117    // NUL-terminated. This is because JS incurs into a non-negligible overhead
118    // when decoding strings and one decode + split('\0') is measurably faster
119    // than decoding N strings. See goto.google.com/postmessage-benchmark .
120    // \0-concatenated.
121    optional string string_cells = 5;
122
123    // If true this is the last batch for the query result.
124    optional bool is_last_batch = 6;
125
126    // Padding field. Used only to re-align and fill gaps in the binary format.
127    reserved 7;
128  }
129  repeated CellsBatch batch = 3;
130}
131
132// Input for the /status endpoint.
133message StatusArgs {}
134
135// Output for the /status endpoint.
136message StatusResult {
137  // If present and not empty, a trace is already loaded already. This happens
138  // when using the HTTP+RPC mode nad passing a trace file to the shell, via
139  // trace_processor_shell -D trace_file.pftrace .
140  optional string loaded_trace_name = 1;
141}
142
143// Input for the /compute_metric endpoint.
144message ComputeMetricArgs {
145  enum ResultFormat {
146    BINARY_PROTOBUF = 0;
147    TEXTPROTO = 1;
148  }
149  repeated string metric_names = 1;
150  optional ResultFormat format = 2;
151}
152
153// Output for the /compute_metric endpoint.
154message ComputeMetricResult {
155  oneof result {
156    // This is meant to contain a perfetto.protos.TraceMetrics. We're using
157    // bytes instead of the actual type because we do not want to generate
158    // protozero code for the metrics protos. We always encode/decode metrics
159    // using a reflection based mechanism that does not require the compiled C++
160    // code. This allows us to read in new protos at runtime.
161    bytes metrics = 1;
162
163    // A perfetto.protos.TraceMetrics formatted as prototext.
164    string metrics_as_prototext = 3;
165  }
166
167  optional string error = 2;
168}
169
170// Input for the /enable_metatrace endpoint.
171message EnableMetatraceArgs {}
172
173// Output for the /enable_metatrace endpoint.
174message EnableMetatraceResult {}
175
176// Input for the /disable_and_read_metatrace endpoint.
177message DisableAndReadMetatraceArgs {}
178
179// Output for the /disable_and_read_metatrace endpoint.
180message DisableAndReadMetatraceResult {
181  // Bytes of perfetto.protos.Trace message. Stored as bytes
182  // to avoid adding a dependency on trace.proto.
183  optional bytes metatrace = 1;
184  optional string error = 2;
185}
186
187// Convenience wrapper for multiple descriptors, similar to FileDescriptorSet
188// in descriptor.proto.
189message DescriptorSet {
190  repeated DescriptorProto descriptors = 1;
191}
192
193// Input for the /get_metric_descriptors endpoint.
194message GetMetricDescriptorsArgs {}
195
196// Output for the /get_metric_descriptors endpoint.
197message GetMetricDescriptorsResult {
198  optional DescriptorSet descriptor_set = 1;
199}
200