github.com/cockroachdb/cockroach@v20.2.0-alpha.1+incompatible/pkg/roachpb/app_stats.proto (about)

     1  // Copyright 2017 The Cockroach Authors.
     2  //
     3  // Use of this software is governed by the Business Source License
     4  // included in the file licenses/BSL.txt.
     5  //
     6  // As of the Change Date specified in that file, in accordance with
     7  // the Business Source License, use of this software will be governed
     8  // by the Apache License, Version 2.0, included in the file
     9  // licenses/APL.txt.
    10  
    11  syntax = "proto2";
    12  package cockroach.sql;
    13  option go_package = "roachpb";
    14  
    15  import "gogoproto/gogo.proto";
    16  import "google/protobuf/timestamp.proto";
    17  
    18  // N.B. When fields are added to this struct, make sure to update
    19  // (*StatementStatistics).Add and (*StatementStatistics).AlmostEqual
    20  // in app_stats.go.
    21  message StatementStatistics {
    22    // Count is the total number of times this statement was executed
    23    // since the begin of the reporting period.
    24    // When transmitted to the reporting server, this value gets
    25    // quantized into buckets (few <10, dozens 10+, 100 or more).
    26    optional int64 count = 1 [(gogoproto.nullable) = false];
    27  
    28    // FirstAttemptCount collects the total number of times a first
    29    // attempt was executed (either the one time in explicitly committed
    30    // statements, or the first time in implicitly committed statements
    31    // with implicit retries).
    32    // The proportion of statements that could be executed without retry
    33    // can be computed as FirstAttemptCount / Count.
    34    // The cumulative number of retries can be computed with
    35    // Count - FirstAttemptCount.
    36    //
    37    // When transmitted to the reporting server, this value gets
    38    // simplified so that the proportion of statements that could be
    39    // executed without retry remains as FirstAttemptCount / Count.
    40    optional int64 first_attempt_count = 2 [(gogoproto.nullable) = false];
    41  
    42    // MaxRetries collects the maximum observed number of automatic
    43    // retries in the reporting period.
    44    // When transmitted to the reporting server, this value gets
    45    // quantized into buckets (few <10, dozens 10+, 100 or more).
    46    optional int64 max_retries = 3 [(gogoproto.nullable) = false];
    47  
    48    // DEPRECATED: LastErr collects the last error encountered.
    49    // Use sensitive_info.last_err instead.
    50    optional string legacy_last_err = 4 [(gogoproto.nullable) = false];
    51  
    52    // DEPRECATED: LastErrRedacted collects the last error, redacted for reporting.
    53    optional string legacy_last_err_redacted = 11 [(gogoproto.nullable) = false];
    54  
    55    // NumRows collects the number of rows returned or observed.
    56    optional NumericStat num_rows = 5 [(gogoproto.nullable) = false];
    57  
    58    // Phase latencies:
    59  
    60    // ParseLat is the time to transform the SQL string into an AST.
    61    optional NumericStat parse_lat = 6 [(gogoproto.nullable) = false];
    62  
    63    // PlanLat is the time to transform the AST into a logical query plan.
    64    optional NumericStat plan_lat = 7 [(gogoproto.nullable) = false];
    65  
    66    // RunLat is the time to run the query and fetch/compute the result rows.
    67    optional NumericStat run_lat = 8 [(gogoproto.nullable) = false];
    68  
    69    // ServiceLat is the time to service the query, from start of parse to end of execute.
    70    optional NumericStat service_lat = 9 [(gogoproto.nullable) = false];
    71  
    72    // OverheadLat is the difference between ServiceLat and the sum of parse+plan+run latencies.
    73    // We store it separately (as opposed to computing it post-hoc) because the combined
    74    // variance for the overhead cannot be derived from the variance of the separate latencies.
    75    optional NumericStat overhead_lat = 10 [(gogoproto.nullable) = false];
    76  
    77    // SensitiveInfo is info that needs to be scrubbed or redacted before being
    78    // sent to the reg cluster.
    79    optional SensitiveInfo sensitive_info = 12 [(gogoproto.nullable) = false];
    80  
    81    optional int64 bytes_read = 13 [(gogoproto.nullable) = false];
    82  
    83    optional int64 rows_read = 14 [(gogoproto.nullable) = false];
    84  
    85    // Note: be sure to update `sql/app_stats.go` when adding/removing fields here!
    86  }
    87  
    88  message SensitiveInfo {
    89    option (gogoproto.equal) = true;
    90    // LastErr collects the last error encountered.
    91    // It is only reported once it's been redacted.
    92    optional string last_err = 1 [(gogoproto.nullable) = false];
    93  
    94    // MostRecentPlanDescription is a serialized representation of the logical plan most recently captured for this query.
    95    optional ExplainTreePlanNode most_recent_plan_description = 2 [(gogoproto.nullable) = false];
    96  
    97    // Timestamp is the time at which the logical plan was last sampled.
    98    optional google.protobuf.Timestamp most_recent_plan_timestamp = 3 [(gogoproto.nullable) = false, (gogoproto.stdtime) = true];
    99  }
   100  
   101  // N.B. When this changes, make sure to update (*NumericStat).AlmostEqual
   102  // in app_stats.go.
   103  message NumericStat {
   104    // NumericStat keeps track of two running values --- the running mean and
   105    // the running sum of squared differences from the mean. Using this along
   106    // with the total count of values, we can compute variance using Welford's
   107    // method. This is more reliable than keeping track of the sum of
   108    // squared values, which is liable to overflow. See
   109    // https://en.wikipedia.org/wiki/Algorithms_for_calculating_variance#Online_algorithm
   110    optional double mean = 1 [(gogoproto.nullable) = false];
   111    optional double squared_diffs = 2 [(gogoproto.nullable) = false];
   112  }
   113  
   114  message StatementStatisticsKey {
   115    optional string query = 1 [(gogoproto.nullable) = false];
   116    optional string app = 2 [(gogoproto.nullable) = false];
   117    optional bool distSQL = 3 [(gogoproto.nullable) = false];
   118    optional bool failed = 4 [(gogoproto.nullable) = false];
   119    optional bool opt = 5 [(gogoproto.nullable) = false];
   120    optional bool implicit_txn = 6 [(gogoproto.nullable) = false];
   121  }
   122  
   123  // CollectedStats wraps collected timings and metadata for some query's execution.
   124  message CollectedStatementStatistics {
   125    optional StatementStatisticsKey key = 1 [(gogoproto.nullable) = false];
   126    optional StatementStatistics stats = 2 [(gogoproto.nullable) = false];
   127  }
   128  
   129  // ExplainTreePlanNode is a serialized representation of an EXPLAIN tree for a logical plan.
   130  message ExplainTreePlanNode {
   131    option (gogoproto.equal) = true;
   132    // Name is the type of node this is, e.g. "scan" or "index-join".
   133    optional string name = 1 [(gogoproto.nullable) = false];
   134  
   135    message Attr {
   136      option (gogoproto.equal) = true;
   137      optional string key = 1 [(gogoproto.nullable) = false];
   138      optional string value = 2 [(gogoproto.nullable) = false];
   139    }
   140  
   141    // Attrs are attributes of this plan node.
   142    // Often there are many attributes with the same key, e.g. "render".
   143    repeated Attr attrs = 2;
   144  
   145    // Children are the nodes that feed into this one, e.g. two scans for a join.
   146    repeated ExplainTreePlanNode children = 3;
   147  }
   148  
   149  // TxnStats contains statistics about transactions of one application.
   150  // N.B. When field are added to this struct, make sure to updated
   151  // (*TxnStats).Add in app_stats.go.
   152  message TxnStats {
   153    optional int64 txn_count = 1 [(gogoproto.nullable) = false];
   154  
   155    optional NumericStat txn_time_sec = 2 [(gogoproto.nullable) = false];
   156  
   157    optional int64 committed_count = 3 [(gogoproto.nullable) = false];
   158  
   159    optional int64 implicit_count = 4 [(gogoproto.nullable) = false];
   160  
   161    // Note: be sure to update `sql/app_stats.go` when adding/removing fields here!
   162  }