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