protobuf/api/datamodel.proto

/*
 * Copyright 2021 Google LLC
 *
 * 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
 *
 *     https://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.
 */

// Copyright 2009 Google Inc. All Rights Reserved.

syntax = "proto2";

package java.apphosting;

import "entity.proto";

option java_package = "com.google.appengine.tools.appstats.proto2api";
option java_outer_classname = "StatsProtos";
option optimize_for = SPEED;

// Represents some quick statistics on similar RPCs, grouped by their
// service name and call name.
message AggregateRpcStatsProto {
  required string service_call_name = 1;
  required int64 total_amount_of_calls = 3;
  // field actually contains micropennies
  // TODO: Rename this field once the appstats client code is out of the
  // labs jar.
  optional int64 total_cost_of_calls_microdollars = 4;
  repeated BilledOpProto total_billed_ops = 5;
}

// Represents a key-value pair.
message KeyValProto {
  required string key = 1;
  required string value = 2;
}

// Represents a single stack frame (python) or line in a stack trace (Java).
message StackFrameProto {
  required string class_or_file_name = 1;  // filename in Python, class in Java
  optional int32 line_number = 2;          // not always available in Java
  required string function_name = 3;
  repeated KeyValProto variables = 4;  // not available in Java
}

// Billed operations associated with an RPC or a collection of RPCs.
message BilledOpProto {
  enum BilledOp {
    DATASTORE_READ = 0;
    DATASTORE_WRITE = 1;
    DATASTORE_SMALL = 2;
    MAIL_RECIPIENT = 3;
    CHANNEL_OPEN = 4;
    XMPP_STANZA = 5;

    // Implementation never finished must be preserved as it's referenced by
    // the labs jar.
    CHANNEL_PRESENCE = 6;
  }
  required BilledOp op = 1;
  required int32 num_ops = 2;  // the number of times that op was performed
}

// Detailed information about individual datastore RPC calls such as keys of
// entities fetched or written by the call. In addition to the entity keys,
// useful information specific to each call is recorded. E.g., for queries,
// the entity kind and cursor information is recorded; For gets, a flag
// indicating if the requested entity key is successfully retrieved is recorded.
message DatastoreCallDetailsProto {
  optional string query_kind = 1;
  optional .storage_onestore_v3.Reference query_ancestor = 2;
  optional fixed64 query_thiscursor = 3;
  optional fixed64 query_nextcursor = 4;

  // For get calls, not all requested entities are successfully retrieved.
  // We record a bool per requested entity key indicating if the corresponding
  // key was successfully fetched. The actual set of entities requested is
  // recorded in the keys_read field below.
  repeated bool get_successful_fetch = 5;

  // Optional (resource and space intensive) information about the keys of
  // entities that were fetched/written in datastore get/put/query/next
  // calls. Currently, entities accessed in other RPC calls is not recorded.
  // For get calls, keys_read represents the set of keys requested
  // from the datastore -- success status is recorded seperately.
  repeated .storage_onestore_v3.Reference keys_read = 6;
  repeated .storage_onestore_v3.Reference keys_written = 7;
}

// Represents the statistics for a single RPC in a request.
message IndividualRpcStatsProto {
  required string service_call_name = 1;
  optional string request_data_summary = 3;
  optional string response_data_summary = 4;
  optional int64 api_mcycles = 5;
  optional int64 api_milliseconds = 11;
  required int64 start_offset_milliseconds = 6;
  optional int64 duration_milliseconds = 7 [default = 0];
  optional string namespace = 8 [default = ''];
  optional bool was_successful = 9 [default = true];

  // Optional (resource and space intensive) information about the call stack
  // of the rpc invocation.
  repeated StackFrameProto call_stack = 10;

  // Detailed information about individual datastore RPC calls such as keys
  // of entities fetched or written by the call.
  optional DatastoreCallDetailsProto datastore_details = 12;

  // field actually contains micropennies
  // TODO: Rename this field once the appstats client code is out of the
  // labs jar.
  optional int64 call_cost_microdollars = 13;
  repeated BilledOpProto billed_ops = 14;
}

// Represents statistical data for a single request.
// This protocol buffer can contain full, verbose information, or just be
// a smaller, compact summary that takes up less space. In the latter case,
// only fields with a number lower than 100 are populated. This makes it
// very easy to gather a subset of summary-only fields using the protocol
// buffer's descriptor.
message RequestStatProto {
  // The wall time at the start of processing this request.
  // Format is the difference, measured in milliseconds, between the current
  // time and midnight, January 1, 1970 UTC.
  required int64 start_timestamp_milliseconds = 1;

  // The http method, like GET or POST.
  optional string http_method = 2 [default = "GET"];

  // The http path.
  optional string http_path = 3 [default = "/"];

  // The http query string.
  optional string http_query = 4;

  // The http response code.
  optional int32 http_status = 5 [default = 200];

  // The wall time it took for the request to complete.
  // The end time of the request can be computed by adding this value to
  // start_timestamp_milliseconds.
  required int64 duration_milliseconds = 6;

  // The total amount of time spent in API calls, in megacycles.
  optional int64 api_mcycles = 7;

  // The total amount of time spent in processing the rpc, minus API calls,
  // in megacycles.
  optional int64 processor_mcycles = 8;

  // A quick summary of all rpc calls made.
  repeated AggregateRpcStatsProto rpc_stats = 9;

  // =================================================================
  // =================================================================

  // CGI environment variables in the request.
  // This will be optional (can be turned off, since it takes up additional
  // memcache space), and may be completely missing in Java.
  repeated KeyValProto cgi_env = 101;

  // The amount of overhead spent in collecting extra data for statistics,
  // in milliseconds wall time.
  optional int64 overhead_walltime_milliseconds = 102;

  // The email of the user, if a user is logged in.
  optional string user_email = 103;

  // Was the user an administrator at the time of this request?
  optional bool is_admin = 104;

  // Data for each individual RPC performed in this request.
  repeated IndividualRpcStatsProto individual_stats = 107;
}