router: per-cluster histograms w/ timeout budget (#9227)

This change adds a pair of histograms to track timeout budget usage: one for the
per-request timeout and one for the global timeout.  The histograms are scaled
such that 100% of the timeout budget is a value of 10000 so that four digits of
the percentage used can be recorded.

Risk Level: Low (new stats only).
Testing: Unit tests added/modified.
Docs Changes: Added notes about historgrams.
Release Notes: Added comment with link to docs.

Fixes #6122

Signed-off-by: Matthew Gumport <mgumport@lyft.com>

Mirrored from https://github.com/envoyproxy/envoy @ ebab713091fc21818d229e1f9f99b1ee8334eb87

envoy/api/v2/cluster.proto

@@ -30,7 +30,7 @@ option (udpa.annotations.file_migrate).move_to_package = "envoy.config.cluster.v
 // [#protodoc-title: Cluster configuration]
 
 // Configuration for a single upstream cluster.
-// [#next-free-field: 47]
+// [#next-free-field: 48]
 message Cluster {
   // Refer to :ref:`service discovery type <arch_overview_service_discovery_types>`
   // for an explanation on each type.
@@ -789,6 +789,13 @@ message Cluster {
   // maybe by allowing LRS to go on the ADS stream, or maybe by moving some of the negotiation
   // from the LRS stream here.]
   core.ConfigSource lrs_server = 42;
+
+  // If track_timeout_budgets is true, the :ref:`timeout budget histograms
+  // <config_cluster_manager_cluster_stats_timeout_budgets>` will be published for each
+  // request. These show what percentage of a request's per try and global timeout was used. A value
+  // of 0 would indicate that none of the timeout was used or that the timeout was infinite. A value
+  // of 100 would indicate that the request took the entirety of the timeout given to it.
+  bool track_timeout_budgets = 47;
 }
 
 // [#not-implemented-hide:] Extensible load balancing policy configuration.

envoy/config/cluster/v3alpha/cluster.proto

@@ -29,7 +29,7 @@ option java_multiple_files = true;
 // [#protodoc-title: Cluster configuration]
 
 // Configuration for a single upstream cluster.
-// [#next-free-field: 47]
+// [#next-free-field: 48]
 message Cluster {
   option (udpa.annotations.versioning).previous_message_type = "envoy.api.v2.Cluster";
 
@@ -825,6 +825,13 @@ message Cluster {
   // maybe by allowing LRS to go on the ADS stream, or maybe by moving some of the negotiation
   // from the LRS stream here.]
   core.v3alpha.ConfigSource lrs_server = 42;
+
+  // If track_timeout_budgets is true, the :ref:`timeout budget histograms
+  // <config_cluster_manager_cluster_stats_timeout_budgets>` will be published for each
+  // request. These show what percentage of a request's per try and global timeout was used. A value
+  // of 0 would indicate that none of the timeout was used or that the timeout was infinite. A value
+  // of 100 would indicate that the request took the entirety of the timeout given to it.
+  bool track_timeout_budgets = 47;
 }
 
 // [#not-implemented-hide:] Extensible load balancing policy configuration.