1// Copyright 2018 gRPC authors. 2// 3// Licensed under the Apache License, Version 2.0 (the "License"); 4// you may not use this file except in compliance with the License. 5// You may obtain a copy of the License at 6// 7// http://www.apache.org/licenses/LICENSE-2.0 8// 9// Unless required by applicable law or agreed to in writing, software 10// distributed under the License is distributed on an "AS IS" BASIS, 11// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12// See the License for the specific language governing permissions and 13// limitations under the License. 14 15syntax = "proto3"; 16 17package grpc.lb.v1; 18 19import "google/protobuf/duration.proto"; 20 21// The LoadReporter service. 22service LoadReporter { 23 // Report load from server to lb. 24 rpc ReportLoad(stream LoadReportRequest) 25 returns (stream LoadReportResponse) { 26 }; 27} 28 29message LoadReportRequest { 30 // This message should be sent on the first request to the gRPC server. 31 InitialLoadReportRequest initial_request = 1; 32} 33 34message InitialLoadReportRequest { 35 // The hostname this load reporter client is requesting load for. 36 string load_balanced_hostname = 1; 37 38 // Additional information to disambiguate orphaned load: load that should have 39 // gone to this load reporter client, but was not able to be sent since the 40 // load reporter client has disconnected. load_key is sent in orphaned load 41 // reports; see Load.load_key. 42 bytes load_key = 2; 43 44 // This interval defines how often the server should send load reports to 45 // the load balancer. 46 google.protobuf.Duration load_report_interval = 3; 47} 48 49message LoadReportResponse { 50 // This message should be sent on the first response to the load balancer. 51 InitialLoadReportResponse initial_response = 1; 52 53 // Reports server-wide statistics for load balancing. 54 // This should be reported with every response. 55 LoadBalancingFeedback load_balancing_feedback = 2; 56 57 // A load report for each <tag, user_id> tuple. This could be considered to be 58 // a multimap indexed by <tag, user_id>. It is not strictly necessary to 59 // aggregate all entries into one entry per <tag, user_id> tuple, although it 60 // is preferred to do so. 61 repeated Load load = 3; 62} 63 64message InitialLoadReportResponse { 65 // Initial response returns the Load balancer ID. This must be plain text 66 // (printable ASCII). 67 string load_balancer_id = 1; 68 69 enum ImplementationIdentifier { 70 IMPL_UNSPECIFIED = 0; 71 CPP = 1; // Standard Google C++ implementation. 72 JAVA = 2; // Standard Google Java implementation. 73 GO = 3; // Standard Google Go implementation. 74 } 75 // Optional identifier of this implementation of the load reporting server. 76 ImplementationIdentifier implementation_id = 2; 77 78 // Optional server_version should be a value that is modified (and 79 // monotonically increased) when changes are made to the server 80 // implementation. 81 int64 server_version = 3; 82} 83 84message LoadBalancingFeedback { 85 // Reports the current utilization of the server (typical range [0.0 - 1.0]). 86 float server_utilization = 1; 87 88 // The total rate of calls handled by this server (including errors). 89 float calls_per_second = 2; 90 91 // The total rate of error responses sent by this server. 92 float errors_per_second = 3; 93} 94 95message Load { 96 // The (plain text) tag used by the calls covered by this load report. The 97 // tag is that part of the load balancer token after removing the load 98 // balancer id. Empty is equivalent to non-existent tag. 99 string load_balance_tag = 1; 100 101 // The user identity authenticated by the calls covered by this load 102 // report. Empty is equivalent to no known user_id. 103 string user_id = 3; 104 105 // IP address of the client that sent these requests, serialized in 106 // network-byte-order. It may either be an IPv4 or IPv6 address. 107 bytes client_ip_address = 15; 108 109 // The number of calls started (since the last report) with the given tag and 110 // user_id. 111 int64 num_calls_started = 4; 112 113 // Indicates whether this load report is an in-progress load report in which 114 // num_calls_in_progress is the only valid entry. If in_progress_report is not 115 // set, num_calls_in_progress will be ignored. If in_progress_report is set, 116 // fields other than num_calls_in_progress and orphaned_load will be ignored. 117 // TODO(juanlishen): A Load is either an in_progress_report or not. We should 118 // make this explicit in hierarchy. From the log, I see in_progress_report_ 119 // has a random num_calls_in_progress_ when not set, which might lead to bug 120 // when the balancer process the load report. 121 oneof in_progress_report { 122 // The number of calls in progress (instantaneously) per load balancer id. 123 int64 num_calls_in_progress = 5; 124 } 125 126 // The following values are counts or totals of call statistics that finished 127 // with the given tag and user_id. 128 int64 num_calls_finished_without_error = 6; // Calls with status OK. 129 int64 num_calls_finished_with_error = 7; // Calls with status non-OK. 130 // Calls that finished with a status that maps to HTTP 5XX (see 131 // googleapis/google/rpc/code.proto). Note that this is a subset of 132 // num_calls_finished_with_error. 133 int64 num_calls_finished_with_server_error = 16; 134 135 // Totals are from calls that with _and_ without error. 136 int64 total_bytes_sent = 8; 137 int64 total_bytes_received = 9; 138 google.protobuf.Duration total_latency = 10; 139 140 // Optional metrics reported for the call(s). Requires that metric_name is 141 // unique. 142 repeated CallMetricData metric_data = 11; 143 144 // The following two fields are used for reporting orphaned load: load that 145 // could not be reported to the originating balancer either since the balancer 146 // is no longer connected or because the frontend sent an invalid token. These 147 // fields must not be set with normal (unorphaned) load reports. 148 oneof orphaned_load { 149 // Load_key is the load_key from the initial_request from the originating 150 // balancer. 151 bytes load_key = 12 [deprecated=true]; 152 153 // If true then this load report is for calls that had an invalid token; the 154 // user is probably abusing the gRPC protocol. 155 // TODO(yankaiz): Rename load_key_unknown. 156 bool load_key_unknown = 13; 157 158 // load_key and balancer_id are included in order to identify orphaned load 159 // from different origins. 160 OrphanedLoadIdentifier orphaned_load_identifier = 14; 161 } 162 163 reserved 2; 164} 165 166message CallMetricData { 167 // Name of the metric; may be empty. 168 string metric_name = 1; 169 170 // Number of calls that finished and included this metric. 171 int64 num_calls_finished_with_metric = 2; 172 173 // Sum of metric values across all calls that finished with this metric. 174 double total_metric_value = 3; 175} 176 177message OrphanedLoadIdentifier { 178 // The load_key from the initial_request from the originating balancer. 179 bytes load_key = 1; 180 181 // The unique ID generated by LoadReporter to identify balancers. Here it 182 // distinguishes orphaned load with a same load_key. 183 string load_balancer_id = 2; 184} 185