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