1// Copyright 2020 The 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 15// Local copy of Envoy xDS proto file, used for testing only. 16 17syntax = "proto3"; 18 19package envoy.service.load_stats.v3; 20 21import "src/proto/grpc/testing/xds/v3/base.proto"; 22import "src/proto/grpc/testing/xds/v3/load_report.proto"; 23 24import "google/protobuf/duration.proto"; 25 26// [#protodoc-title: Load reporting service] 27 28service LoadReportingService { 29 // Advanced API to allow for multi-dimensional load balancing by remote 30 // server. For receiving LB assignments, the steps are: 31 // 1, The management server is configured with per cluster/zone/load metric 32 // capacity configuration. The capacity configuration definition is 33 // outside of the scope of this document. 34 // 2. Envoy issues a standard {Stream,Fetch}Endpoints request for the clusters 35 // to balance. 36 // 37 // Independently, Envoy will initiate a StreamLoadStats bidi stream with a 38 // management server: 39 // 1. Once a connection establishes, the management server publishes a 40 // LoadStatsResponse for all clusters it is interested in learning load 41 // stats about. 42 // 2. For each cluster, Envoy load balances incoming traffic to upstream hosts 43 // based on per-zone weights and/or per-instance weights (if specified) 44 // based on intra-zone LbPolicy. This information comes from the above 45 // {Stream,Fetch}Endpoints. 46 // 3. When upstream hosts reply, they optionally add header <define header 47 // name> with ASCII representation of EndpointLoadMetricStats. 48 // 4. Envoy aggregates load reports over the period of time given to it in 49 // LoadStatsResponse.load_reporting_interval. This includes aggregation 50 // stats Envoy maintains by itself (total_requests, rpc_errors etc.) as 51 // well as load metrics from upstream hosts. 52 // 5. When the timer of load_reporting_interval expires, Envoy sends new 53 // LoadStatsRequest filled with load reports for each cluster. 54 // 6. The management server uses the load reports from all reported Envoys 55 // from around the world, computes global assignment and prepares traffic 56 // assignment destined for each zone Envoys are located in. Goto 2. 57 rpc StreamLoadStats(stream LoadStatsRequest) returns (stream LoadStatsResponse) { 58 } 59} 60 61// A load report Envoy sends to the management server. 62// [#not-implemented-hide:] Not configuration. TBD how to doc proto APIs. 63message LoadStatsRequest { 64 // Node identifier for Envoy instance. 65 config.core.v3.Node node = 1; 66 67 // A list of load stats to report. 68 repeated config.endpoint.v3.ClusterStats cluster_stats = 2; 69} 70 71// The management server sends envoy a LoadStatsResponse with all clusters it 72// is interested in learning load stats about. 73// [#not-implemented-hide:] Not configuration. TBD how to doc proto APIs. 74message LoadStatsResponse { 75 // Clusters to report stats for. 76 // Not populated if *send_all_clusters* is true. 77 repeated string clusters = 1; 78 79 // If true, the client should send all clusters it knows about. 80 // Only clients that advertise the "envoy.lrs.supports_send_all_clusters" capability in their 81 // :ref:`client_features<envoy_api_field_config.core.v3.Node.client_features>` field will honor this field. 82 bool send_all_clusters = 4; 83 84 // The minimum interval of time to collect stats over. This is only a minimum for two reasons: 85 // 1. There may be some delay from when the timer fires until stats sampling occurs. 86 // 2. For clusters that were already feature in the previous *LoadStatsResponse*, any traffic 87 // that is observed in between the corresponding previous *LoadStatsRequest* and this 88 // *LoadStatsResponse* will also be accumulated and billed to the cluster. This avoids a period 89 // of inobservability that might otherwise exists between the messages. New clusters are not 90 // subject to this consideration. 91 google.protobuf.Duration load_reporting_interval = 2; 92 93 // Set to *true* if the management server supports endpoint granularity 94 // report. 95 bool report_endpoint_granularity = 3; 96} 97