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