xds/v3/load_report.proto

// Copyright 2020 The gRPC Authors
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

// Local copy of Envoy xDS proto file, used for testing only.

syntax = "proto3";

package envoy.config.endpoint.v3;

import "src/proto/grpc/testing/xds/v3/address.proto";
import "src/proto/grpc/testing/xds/v3/base.proto";

import "google/protobuf/duration.proto";
import "google/protobuf/struct.proto";

// These are stats Envoy reports to GLB every so often. Report frequency is
// defined by
// :ref:`LoadStatsResponse.load_reporting_interval<envoy_api_field_service.load_stats.v3.LoadStatsResponse.load_reporting_interval>`.
// Stats per upstream region/zone and optionally per subzone.
// [#not-implemented-hide:] Not configuration. TBD how to doc proto APIs.
// [#next-free-field: 9]
message UpstreamLocalityStats {
  // Name of zone, region and optionally endpoint group these metrics were
  // collected from. Zone and region names could be empty if unknown.
  core.v3.Locality locality = 1;

  // The total number of requests successfully completed by the endpoints in the
  // locality.
  uint64 total_successful_requests = 2;

  // The total number of unfinished requests
  uint64 total_requests_in_progress = 3;

  // The total number of requests that failed due to errors at the endpoint,
  // aggregated over all endpoints in the locality.
  uint64 total_error_requests = 4;

  // The total number of requests that were issued by this Envoy since
  // the last report. This information is aggregated over all the
  // upstream endpoints in the locality.
  uint64 total_issued_requests = 8;

  // Stats for multi-dimensional load balancing.
  repeated EndpointLoadMetricStats load_metric_stats = 5;

  // Endpoint granularity stats information for this locality. This information
  // is populated if the Server requests it by setting
  // :ref:`LoadStatsResponse.report_endpoint_granularity<envoy_api_field_service.load_stats.v3.LoadStatsResponse.report_endpoint_granularity>`.
  repeated UpstreamEndpointStats upstream_endpoint_stats = 7;

  // [#not-implemented-hide:] The priority of the endpoint group these metrics
  // were collected from.
  uint32 priority = 6;
}

// [#not-implemented-hide:] Not configuration. TBD how to doc proto APIs.
// [#next-free-field: 8]
message UpstreamEndpointStats {
  // Upstream host address.
  core.v3.Address address = 1;

  // Opaque and implementation dependent metadata of the
  // endpoint. Envoy will pass this directly to the management server.
  google.protobuf.Struct metadata = 6;

  // The total number of requests successfully completed by the endpoints in the
  // locality. These include non-5xx responses for HTTP, where errors
  // originate at the client and the endpoint responded successfully. For gRPC,
  // the grpc-status values are those not covered by total_error_requests below.
  uint64 total_successful_requests = 2;

  // The total number of unfinished requests for this endpoint.
  uint64 total_requests_in_progress = 3;

  // The total number of requests that failed due to errors at the endpoint.
  // For HTTP these are responses with 5xx status codes and for gRPC the
  // grpc-status values:
  //
  //   - DeadlineExceeded
  //   - Unimplemented
  //   - Internal
  //   - Unavailable
  //   - Unknown
  //   - DataLoss
  uint64 total_error_requests = 4;

  // The total number of requests that were issued to this endpoint
  // since the last report. A single TCP connection, HTTP or gRPC
  // request or stream is counted as one request.
  uint64 total_issued_requests = 7;

  // Stats for multi-dimensional load balancing.
  repeated EndpointLoadMetricStats load_metric_stats = 5;
}

// [#not-implemented-hide:] Not configuration. TBD how to doc proto APIs.
message EndpointLoadMetricStats {
  // Name of the metric; may be empty.
  string metric_name = 1;

  // Number of calls that finished and included this metric.
  uint64 num_requests_finished_with_metric = 2;

  // Sum of metric values across all calls that finished with this metric for
  // load_reporting_interval.
  double total_metric_value = 3;
}

// Per cluster load stats. Envoy reports these stats a management server in a
// :ref:`LoadStatsRequest<envoy_api_msg_service.load_stats.v3.LoadStatsRequest>`
// [#not-implemented-hide:] Not configuration. TBD how to doc proto APIs.
// Next ID: 7
// [#next-free-field: 7]
message ClusterStats {
  message DroppedRequests {
    // Identifier for the policy specifying the drop.
    string category = 1;

    // Total number of deliberately dropped requests for the category.
    uint64 dropped_count = 2;
  }

  // The name of the cluster.
  string cluster_name = 1;

  // The eds_cluster_config service_name of the cluster.
  // It's possible that two clusters send the same service_name to EDS,
  // in that case, the management server is supposed to do aggregation on the load reports.
  string cluster_service_name = 6;

  // Need at least one.
  repeated UpstreamLocalityStats upstream_locality_stats = 2;

  // Cluster-level stats such as total_successful_requests may be computed by
  // summing upstream_locality_stats. In addition, below there are additional
  // cluster-wide stats.
  //
  // The total number of dropped requests. This covers requests
  // deliberately dropped by the drop_overload policy and circuit breaking.
  uint64 total_dropped_requests = 3;

  // Information about deliberately dropped requests for each category specified
  // in the DropOverload policy.
  repeated DroppedRequests dropped_requests = 5;

  // Period over which the actual load report occurred. This will be guaranteed to include every
  // request reported. Due to system load and delays between the *LoadStatsRequest* sent from Envoy
  // and the *LoadStatsResponse* message sent from the management server, this may be longer than
  // the requested load reporting interval in the *LoadStatsResponse*.
  google.protobuf.Duration load_report_interval = 4;
}