protos/perfetto/trace_processor/trace_processor.proto

/*
 * Copyright (C) 2018 The Android Open Source Project
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

syntax = "proto2";

package perfetto.protos;

import "protos/perfetto/common/descriptor.proto";

// This file defines the schema for {,un}marshalling arguments and return values
// when interfacing to the trace processor binary interface.

// The Trace Processor can be used in three modes:
// 1. Fully native from C++ or directly using trace_processor_shell.
//    In this case, this file isn't really relevant because no binary
//    marshalling is involved. Look at include/trace_processor/trace_processor.h
//    for the public C++ API definition.
// 2. Using WASM within the HTML ui. In this case these messages are used to
//    {,un}marshall calls made through the JS<>WASM interop in
//    src/trace_processor/rpc/wasm_bridge.cc .
// 3. Using the HTTP+RPC interface, by running trace_processor_shell -D.
//    In this case these messages are used to {,un}marshall HTTP requests and
//    response made through src/trace_processor/rpc/httpd.cc .

// Input for the /raw_query endpoint.
message RawQueryArgs {
  optional string sql_query = 1;

  // Wall time when the query was queued. Used only for query stats.
  optional uint64 time_queued_ns = 2;
}

// Output for the /raw_query endpoint.
// DEPRECATED, use /query. See QueryResult below.
message RawQueryResult {
  message ColumnDesc {
    optional string name = 1;
    enum Type {
      UNKNOWN = 0;
      LONG = 1;
      DOUBLE = 2;
      STRING = 3;
    }
    optional Type type = 2;
  }
  message ColumnValues {
    // Only one of this field will be filled for each column (according to the
    // corresponding descriptor) and that one will have precisely |num_records|
    // elements.
    repeated int64 long_values = 1;
    repeated double double_values = 2;
    repeated string string_values = 3;

    // This will be set to true or false depending on whether the data at the
    // given index is NULL.
    repeated bool is_nulls = 4;
  }
  repeated ColumnDesc column_descriptors = 1;
  optional uint64 num_records = 2;
  repeated ColumnValues columns = 3;
  optional string error = 4;
  optional uint64 execution_time_ns = 5;
}

// Output for the /query endpoint.
// Returns a query result set, grouping cells into batches. Batching allows a
// more efficient encoding of results, at the same time allowing to return
// O(M) results in a pipelined fashion, without full-memory buffering.
// Batches are split when either a large number of cells (~thousands) is reached
// or the string/blob payload becomes too large (~hundreds of KB).
// Data is batched in cells, scanning results by row -> column. e.g. if a query
// returns 3 columns and 2 rows, the cells will be emitted in this order:
// R0C0, R0C1, R0C2, R1C0, R1C1, R1C2.
message QueryResult {
  // This determines the number and names of columns.
  repeated string column_names = 1;

  // If non-emty the query returned an error. Note that some cells might still
  // be present, if the error happened while iterating.
  optional string error = 2;

  // A batch contains an array of cell headers, stating the type of each cell.
  // The payload of each cell is stored in the corresponding xxx_cells field
  // below (unless the cell is NULL).
  // So if |cells| contains: [VARINT, FLOAT64, VARINT, STRING], the results will
  // be available as:
  // [varint_cells[0], float64_cells[0], varint_cells[1], string_cells[0]].
  message CellsBatch {
    enum CellType {
      CELL_INVALID = 0;
      CELL_NULL = 1;
      CELL_VARINT = 2;
      CELL_FLOAT64 = 3;
      CELL_STRING = 4;
      CELL_BLOB = 5;
    }
    repeated CellType cells = 1 [packed = true];

    repeated int64 varint_cells = 2 [packed = true];
    repeated double float64_cells = 3 [packed = true];
    repeated bytes blob_cells = 4;

    // The string cells are concatenated in a single field. Each cell is
    // NUL-terminated. This is because JS incurs into a non-negligible overhead
    // when decoding strings and one decode + split('\0') is measurably faster
    // than decoding N strings. See goto.google.com/postmessage-benchmark .
    // \0-concatenated.
    optional string string_cells = 5;

    // If true this is the last batch for the query result.
    optional bool is_last_batch = 6;

    // Padding field. Used only to re-align and fill gaps in the binary format.
    reserved 7;
  }
  repeated CellsBatch batch = 3;
}

// Input for the /status endpoint.
message StatusArgs {}

// Output for the /status endpoint.
message StatusResult {
  // If present and not empty, a trace is already loaded already. This happens
  // when using the HTTP+RPC mode nad passing a trace file to the shell, via
  // trace_processor_shell -D trace_file.pftrace .
  optional string loaded_trace_name = 1;
}

// Input for the /compute_metric endpoint.
message ComputeMetricArgs {
  enum ResultFormat {
    BINARY_PROTOBUF = 0;
    TEXTPROTO = 1;
  }
  repeated string metric_names = 1;
  optional ResultFormat format = 2;
}

// Output for the /compute_metric endpoint.
message ComputeMetricResult {
  oneof result {
    // This is meant to contain a perfetto.protos.TraceMetrics. We're using
    // bytes instead of the actual type because we do not want to generate
    // protozero code for the metrics protos. We always encode/decode metrics
    // using a reflection based mechanism that does not require the compiled C++
    // code. This allows us to read in new protos at runtime.
    bytes metrics = 1;

    // A perfetto.protos.TraceMetrics formatted as prototext.
    string metrics_as_prototext = 3;
  }

  optional string error = 2;
}

// Input for the /enable_metatrace endpoint.
message EnableMetatraceArgs {}

// Output for the /enable_metatrace endpoint.
message EnableMetatraceResult {}

// Input for the /disable_and_read_metatrace endpoint.
message DisableAndReadMetatraceArgs {}

// Output for the /disable_and_read_metatrace endpoint.
message DisableAndReadMetatraceResult {
  // Bytes of perfetto.protos.Trace message. Stored as bytes
  // to avoid adding a dependency on trace.proto.
  optional bytes metatrace = 1;
  optional string error = 2;
}

// Convenience wrapper for multiple descriptors, similar to FileDescriptorSet
// in descriptor.proto.
message DescriptorSet {
  repeated DescriptorProto descriptors = 1;
}

// Input for the /get_metric_descriptors endpoint.
message GetMetricDescriptorsArgs {}

// Output for the /get_metric_descriptors endpoint.
message GetMetricDescriptorsResult {
  optional DescriptorSet descriptor_set = 1;
}