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 }