...

Text file src/github.com/datawire/ambassador/v2/api/envoy/service/load_stats/v3/lrs.proto

Documentation: github.com/datawire/ambassador/v2/api/envoy/service/load_stats/v3

     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