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