[bp/1.37] [stack] stats number limit and scope level stats matcher support (#44085)

Commit Message: [bp/1.37] [stack] stats number limit and scope level
stats matcher support
Additional Description:
Risk Level:
Testing:
Docs Changes:
Release Notes:
Platform Specific Features:
[Optional Runtime guard:]
[Optional Fixes #Issue]
[Optional Fixes commit #PR or SHA]
[Optional Deprecated:]
[Optional [API
Considerations](https://github.com/envoyproxy/envoy/blob/main/api/review_checklist.md):]

---------

Signed-off-by: Xuyang Tao <taoxuy@google.com>
Signed-off-by: wbpcode/wangbaiping <wbphub@gmail.com>
Signed-off-by: wbpcode <wbphub@gmail.com>
Signed-off-by: Jonh Wendell <jwendell@redhat.com>
Co-authored-by: Xuyang Tao <taoxuy@google.com>
Co-authored-by: Jonh Wendell <jwendell@redhat.com>

Author: 3 people

changelogs/current.yaml

@@ -22,5 +22,14 @@ removed_config_or_runtime:
 # *Normally occurs at the end of the* :ref:`deprecation period <deprecated>`
 
 new_features:
+- area: stats
+  change: |
+    Added support to limit the number of stats stored in each stats scope in the stats libarary.
+- area: stats
+  change: |
+    Added support for cluster-level stats matcher, allowing more granular control over which stats
+    are enabled and reported at the cluster level. This the stats matcher could be configured via
+    the xDS API dynamically on a per-cluster basis.
+    See :ref:`envoy.stats_matcher <well_known_metadata_envoy_stats_matcher>` for more details.
 
 deprecated:

docs/root/configuration/advanced/metadata_configurations.rst

@@ -17,3 +17,61 @@ modifying Envoy's core API or implementation.
 For instance, users can add extra attributes to routes, such as the route owner or upstream service maintainer, to metadata.
 They can then enable Envoy to log these attributes to the access log or report them to StatsD, among other possibilities.
 Moreover, users can write a filter/extension to read these attributes and execute any specific logic.
+
+.. _well_known_metadata:
+
+Well-Known Metadata
+-------------------
+
+The following ``typed_filter_metadata`` or ``filter_metadata`` keys are recognized by Envoy and control built-in behavior.
+Each entry specifies where the metadata can be configured.
+
+.. _well_known_metadata_envoy_stats_matcher:
+
+``envoy.stats_matcher``
+~~~~~~~~~~~~~~~~~~~~~~~
+
+**Type:** :ref:`envoy.config.metrics.v3.StatsMatcher <envoy_v3_api_msg_config.metrics.v3.StatsMatcher>`
+
+**Applicable to:** Upstream cluster (:ref:`Cluster.metadata <envoy_v3_api_field_config.cluster.v3.Cluster.metadata>`)
+
+**Fields:** ``typed_filter_metadata``
+
+When present in a cluster's ``typed_filter_metadata``, Envoy uses the provided
+:ref:`StatsMatcher <envoy_v3_api_msg_config.metrics.v3.StatsMatcher>` as the stats matcher for that
+cluster's stats scope. This per-cluster matcher **replaces** (not supplements) the global stats
+matcher configured in the bootstrap :ref:`StatsConfig
+<envoy_v3_api_msg_config.metrics.v3.StatsConfig>`. Child scopes created under the cluster scope
+inherit the matcher unless overridden.
+
+This allows fine-grained control over which stats are created per cluster — for example, enabling a
+minimal set of stats on high-cardinality clusters to reduce memory and CPU overhead.
+
+Example:
+
+.. code-block:: yaml
+
+  clusters:
+  - name: my_cluster
+    connect_timeout: 0.25s
+    type: STATIC
+    lb_policy: ROUND_ROBIN
+    metadata:
+      typed_filter_metadata:
+        envoy.stats_matcher:
+          "@type": type.googleapis.com/envoy.config.metrics.v3.StatsMatcher
+          inclusion_list:
+            patterns:
+            - prefix: "cluster.my_cluster.upstream_cx"
+    load_assignment:
+      cluster_name: my_cluster
+      endpoints:
+      - lb_endpoints:
+        - endpoint:
+            address:
+              socket_address:
+                address: 127.0.0.1
+                port_value: 10001
+
+In this example, only stats whose names start with ``cluster.my_cluster.upstream_cx`` are created
+for ``my_cluster``, all other cluster stats are suppressed.

docs/root/configuration/observability/statistics.rst

@@ -35,6 +35,9 @@ Server related statistics are rooted at *server.* with following statistics:
   static_unknown_fields, Counter, Number of messages in static configuration with unknown fields
   dynamic_unknown_fields, Counter, Number of messages in dynamic configuration with unknown fields
   wip_protos, Counter, Number of messages and fields marked as work-in-progress being used
+  stats_overflow.counter, Counter, Total number of counter lookup or creation attempts dropped due to reaching the configured limit on label cardinality.
+  stats_overflow.gauge, Counter, Total number of gauge lookup or creation attempts dropped due to reaching the configured limit on label cardinality.
+  stats_overflow.histogram, Counter, Total number of histogram lookup or creation attempts dropped due to reaching the configured limit on label cardinality.
 
 .. _server_compilation_settings_statistics:
 

envoy/stats/scope.h

@@ -6,6 +6,7 @@
 
 #include "envoy/common/pure.h"
 #include "envoy/stats/histogram.h"
+#include "envoy/stats/stats_matcher.h"
 #include "envoy/stats/tag.h"
 
 #include "absl/types/optional.h"
@@ -28,6 +29,17 @@ using TextReadoutOptConstRef = absl::optional<std::reference_wrapper<const TextR
 using ConstScopeSharedPtr = std::shared_ptr<const Scope>;
 using ScopeSharedPtr = std::shared_ptr<Scope>;
 
+// Settings for limiting the number of counters, gauges and histograms allowed
+// in a scope. This currently only supports thread local stats.
+struct ScopeStatsLimitSettings {
+  // Max number of counters allowed in this scope. 0 means no limit.
+  uint32_t max_counters = 0;
+  // Max number of gauges allowed in this scope. 0 means no limit.
+  uint32_t max_gauges = 0;
+  // Max number of histograms allowed in this scope. 0 means no limit.
+  uint32_t max_histograms = 0;
+};
+
 template <class StatType> using IterateFn = std::function<bool(const RefcountPtr<StatType>&)>;
 
 /**
@@ -73,8 +85,14 @@ class Scope : public std::enable_shared_from_this<Scope> {
    * @param name supplies the scope's namespace prefix.
    * @param evictable whether unused metrics can be deleted from the scope caches. This requires
    * that the metrics are not stored by reference.
+   * @param limits metric limits for counters, gauges and histograms allowed in this scope.
+   * @param matcher optional per-scope stats matcher; replaces the store-level matcher when set.
+   * NOTE: If the scope specific matcher is set, then the sub scope will inherit the same matcher
+   * unless another matcher is explicitly set.
    */
-  virtual ScopeSharedPtr createScope(const std::string& name, bool evictable = false) PURE;
+  virtual ScopeSharedPtr createScope(const std::string& name, bool evictable = false,
+                                     const ScopeStatsLimitSettings& limits = {},
+                                     StatsMatcherSharedPtr matcher = nullptr) PURE;
 
   /**
    * Allocate a new scope. NOTE: The implementation should correctly handle overlapping scopes
@@ -84,8 +102,14 @@ class Scope : public std::enable_shared_from_this<Scope> {
    * @param name supplies the scope's namespace prefix.
    * @param evictable whether unused metrics can be deleted from the scope caches. This requires
    * that the metrics are not stored by reference.
+   * @param limits metric limits for counters, gauges and histograms allowed in this scope.
+   * @param matcher optional per-scope stats matcher; replaces the store-level matcher when set.
+   * NOTE: If the scope specific matcher is set, then the sub scope will inherit the same matcher
+   * unless another matcher is explicitly set.
    */
-  virtual ScopeSharedPtr scopeFromStatName(StatName name, bool evictable = false) PURE;
+  virtual ScopeSharedPtr scopeFromStatName(StatName name, bool evictable = false,
+                                           const ScopeStatsLimitSettings& limits = {},
+                                           StatsMatcherSharedPtr matcher = nullptr) PURE;
 
   /**
    * Creates a Counter from the stat name. Tag extraction will be performed on the name.

envoy/stats/stats_matcher.h

@@ -84,6 +84,7 @@ class StatsMatcher {
 };
 
 using StatsMatcherPtr = std::unique_ptr<const StatsMatcher>;
+using StatsMatcherSharedPtr = std::shared_ptr<const StatsMatcher>;
 
 } // namespace Stats
 } // namespace Envoy

envoy/stats/store.h

@@ -177,8 +177,10 @@ class Store {
   /**
    * @return a scope of the given name.
    */
-  ScopeSharedPtr createScope(const std::string& name, bool evictable = false) {
-    return rootScope()->createScope(name, evictable);
+  ScopeSharedPtr createScope(const std::string& name, bool evictable = false,
+                             const ScopeStatsLimitSettings& limits = {},
+                             StatsMatcherSharedPtr matcher = nullptr) {
+    return rootScope()->createScope(name, evictable, limits, std::move(matcher));
   }
 
   /**

source/common/stats/isolated_store_impl.cc

@@ -46,8 +46,8 @@ IsolatedStoreImpl::IsolatedStoreImpl(SymbolTable& symbol_table)
         return alloc_.makeTextReadout(joiner.nameWithTags(), joiner.tagExtractedName(),
                                       tagVectorFromOpt(tags));
       }),
-      null_counter_(new NullCounterImpl(symbol_table)),
-      null_gauge_(new NullGaugeImpl(symbol_table)) {}
+      null_counter_(symbol_table), null_gauge_(symbol_table), null_histogram_(symbol_table),
+      null_text_readout_(symbol_table) {}
 
 ScopeSharedPtr IsolatedStoreImpl::rootScope() {
   if (lazy_default_scope_ == nullptr) {
@@ -63,20 +63,27 @@ ConstScopeSharedPtr IsolatedStoreImpl::constRootScope() const {
 
 IsolatedStoreImpl::~IsolatedStoreImpl() = default;
 
-ScopeSharedPtr IsolatedScopeImpl::createScope(const std::string& name, bool) {
+ScopeSharedPtr IsolatedScopeImpl::createScope(const std::string& name, bool,
+                                              const ScopeStatsLimitSettings& limits,
+                                              StatsMatcherSharedPtr matcher) {
   StatNameManagedStorage stat_name_storage(Utility::sanitizeStatsName(name), symbolTable());
-  return scopeFromStatName(stat_name_storage.statName(), false);
+  return scopeFromStatName(stat_name_storage.statName(), false, limits, std::move(matcher));
 }
 
-ScopeSharedPtr IsolatedScopeImpl::scopeFromStatName(StatName name, bool) {
+ScopeSharedPtr IsolatedScopeImpl::scopeFromStatName(StatName name, bool,
+                                                    const ScopeStatsLimitSettings&,
+                                                    StatsMatcherSharedPtr matcher) {
   SymbolTable::StoragePtr prefix_name_storage = symbolTable().join({prefix(), name});
-  ScopeSharedPtr scope = store_.makeScope(StatName(prefix_name_storage.get()));
+  // Use explicit matcher if provided; otherwise inherit scope_matcher_.
+  StatsMatcherSharedPtr child_matcher = matcher ? std::move(matcher) : scope_matcher_;
+  ScopeSharedPtr scope =
+      store_.makeScope(StatName(prefix_name_storage.get()), std::move(child_matcher));
   addScopeToStore(scope);
   return scope;
 }
 
-ScopeSharedPtr IsolatedStoreImpl::makeScope(StatName name) {
-  return std::make_shared<IsolatedScopeImpl>(name, *this);
+ScopeSharedPtr IsolatedStoreImpl::makeScope(StatName name, StatsMatcherSharedPtr matcher) {
+  return std::make_shared<IsolatedScopeImpl>(name, *this, std::move(matcher));
 }
 
 } // namespace Stats