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