data-plane-api/envoy/api/v2/endpoint/load_report.proto

syntax = "proto3";

package envoy.api.v2.endpoint;

import "envoy/api/v2/core/base.proto";

import "validate/validate.proto";
import "gogoproto/gogo.proto";

// These are stats Envoy reports to GLB every so often. Report frequency is
// defined by
// :ref:`LoadStatsResponse.load_reporting_interval<envoy_api_field_load_stats.LoadStatsResponse.load_reporting_interval>`.
// Stats per upstream region/zone and optionally per subzone.
// [#not-implemented-hide:] Not configuration. TBD how to doc proto APIs.
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.Locality locality = 1;

  // The total number of requests sent by this Envoy since the last report. A
  // single HTTP or gRPC request or stream is counted as one request. A TCP
  // connection is also treated as one request. There is no explicit
  // total_requests field below for a locality, but it may be inferred from:
  //
  // .. code-block:: none
  //
  //   total_requests = total_successful_requests + total_requests_in_progress +
  //     total_error_requests
  //
  // 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
  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;

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

  // [#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.
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_load_stats.LoadStatsRequest>`
// [#not-implemented-hide:] Not configuration. TBD how to doc proto APIs.
message ClusterStats {
  // The name of the cluster.
  string cluster_name = 1 [(validate.rules).string.min_bytes = 1];

  // Need at least one.
  repeated UpstreamLocalityStats upstream_locality_stats = 2
      [(validate.rules).repeated .min_items = 1];

  // 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 following total_requests equality holds at the
  // cluster-level:
  //
  // .. code-block:: none
  //
  //   sum_locality(total_successful_requests) + sum_locality(total_requests_in_progress) +
  //     sum_locality(total_error_requests) + total_dropped_requests`
  //
  // The total number of dropped requests. This covers requests
  // deliberately dropped by the drop_overload policy and circuit breaking.
  uint64 total_dropped_requests = 3;
}