add additional scope level stats matcher to enable/disable stats (#43923)

wbpcode · wbpcode · commit 5f5fc23b8d9a · 2026-03-23T11:16:02.000Z
Signed-off-by: wbpcode/wangbaiping &lt;wbphub@gmail.com&gt;
diff --git a/changelogs/current.yaml b/changelogs/current.yaml
@@ -20,5 +20,11 @@ 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:
diff --git a/docs/root/configuration/advanced/metadata_configurations.rst b/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.
diff --git a/source/common/stats/stats_matcher_impl.cc b/source/common/stats/stats_matcher_impl.cc
@@ -14,28 +14,28 @@ namespace Stats {
 
 // TODO(ambuc): Refactor this into common/matchers.cc, since StatsMatcher is really just a thin
 // wrapper around what might be called a StringMatcherList.
-StatsMatcherImpl::StatsMatcherImpl(const envoy::config::metrics::v3::StatsConfig& config,
+StatsMatcherImpl::StatsMatcherImpl(const envoy::config::metrics::v3::StatsMatcher& stats_matcher,
                                    SymbolTable& symbol_table,
                                    Server::Configuration::CommonFactoryContext& context)
     : symbol_table_(symbol_table), stat_name_pool_(std::make_unique<StatNamePool>(symbol_table)) {
 
-  switch (config.stats_matcher().stats_matcher_case()) {
+  switch (stats_matcher.stats_matcher_case()) {
   case envoy::config::metrics::v3::StatsMatcher::StatsMatcherCase::kRejectAll:
     // In this scenario, there are no matchers to store.
-    is_inclusive_ = !config.stats_matcher().reject_all();
+    is_inclusive_ = !stats_matcher.reject_all();
     break;
   case envoy::config::metrics::v3::StatsMatcher::StatsMatcherCase::kInclusionList:
     // If we have an inclusion list, we are being default-exclusive.
-    for (const auto& stats_matcher : config.stats_matcher().inclusion_list().patterns()) {
-      matchers_.push_back(Matchers::StringMatcherImpl(stats_matcher, context));
+    for (const auto& pattern : stats_matcher.inclusion_list().patterns()) {
+      matchers_.push_back(Matchers::StringMatcherImpl(pattern, context));
       optimizeLastMatcher();
     }
     is_inclusive_ = false;
     break;
   case envoy::config::metrics::v3::StatsMatcher::StatsMatcherCase::kExclusionList:
     // If we have an exclusion list, we are being default-inclusive.
-    for (const auto& stats_matcher : config.stats_matcher().exclusion_list().patterns()) {
-      matchers_.push_back(Matchers::StringMatcherImpl(stats_matcher, context));
+    for (const auto& pattern : stats_matcher.exclusion_list().patterns()) {
+      matchers_.push_back(Matchers::StringMatcherImpl(pattern, context));
       optimizeLastMatcher();
     }
     FALLTHRU;
diff --git a/source/common/stats/stats_matcher_impl.h b/source/common/stats/stats_matcher_impl.h
@@ -21,7 +21,10 @@ namespace Stats {
 class StatsMatcherImpl : public StatsMatcher {
 public:
   StatsMatcherImpl(const envoy::config::metrics::v3::StatsConfig& config, SymbolTable& symbol_table,
-                   Server::Configuration::CommonFactoryContext& context);
+                   Server::Configuration::CommonFactoryContext& context)
+      : StatsMatcherImpl(config.stats_matcher(), symbol_table, context) {}
+  StatsMatcherImpl(const envoy::config::metrics::v3::StatsMatcher& stats_matcher,
+                   SymbolTable& symbol_table, Server::Configuration::CommonFactoryContext& context);
 
   // Default constructor simply allows everything.
   StatsMatcherImpl() = default;
diff --git a/source/common/upstream/BUILD b/source/common/upstream/BUILD
@@ -397,6 +397,7 @@ envoy_cc_library(
         "@envoy_api//envoy/config/core/v3:pkg_cc_proto",
         "//source/common/stats:deferred_creation",
         "@envoy_api//envoy/config/endpoint/v3:pkg_cc_proto",
+        "@envoy_api//envoy/config/metrics/v3:pkg_cc_proto",
         "@envoy_api//envoy/config/upstream/local_address_selector/v3:pkg_cc_proto",
         "@envoy_api//envoy/extensions/filters/http/upstream_codec/v3:pkg_cc_proto",
         "@envoy_api//envoy/extensions/transport_sockets/raw_buffer/v3:pkg_cc_proto",
@@ -424,6 +425,7 @@ envoy_cc_library(
         "//source/common/protobuf",
         "//source/common/protobuf:utility_lib",
         "//source/common/runtime:runtime_lib",
+        "//source/common/stats:stats_matcher_lib",
         "//source/server:transport_socket_config_lib",
     ],
 )
diff --git a/source/common/upstream/prod_cluster_info_factory.cc b/source/common/upstream/prod_cluster_info_factory.cc
@@ -13,7 +13,7 @@ namespace Upstream {
 ClusterInfoConstSharedPtr
 ProdClusterInfoFactory::createClusterInfo(const CreateClusterInfoParams& params) {
   Envoy::Stats::ScopeSharedPtr scope =
-      params.stats_.createScope(fmt::format("cluster.{}.", params.cluster_.name()));
+      generateStatsScope(params.cluster_, params.server_context_, false);
 
   Envoy::Server::Configuration::TransportSocketFactoryContextImpl factory_context(
       params.server_context_, *scope, params.server_context_.messageValidationVisitor());
diff --git a/source/common/upstream/upstream_impl.cc b/source/common/upstream/upstream_impl.cc
@@ -16,6 +16,8 @@
 #include "envoy/config/core/v3/health_check.pb.h"
 #include "envoy/config/core/v3/protocol.pb.h"
 #include "envoy/config/endpoint/v3/endpoint_components.pb.h"
+#include "envoy/config/metrics/v3/stats.pb.h"
+#include "envoy/config/metrics/v3/stats.pb.validate.h"
 #include "envoy/config/upstream/local_address_selector/v3/default_local_address_selector.pb.h"
 #include "envoy/event/dispatcher.h"
 #include "envoy/event/timer.h"
@@ -55,6 +57,7 @@
 #include "source/common/runtime/runtime_features.h"
 #include "source/common/runtime/runtime_impl.h"
 #include "source/common/stats/deferred_creation.h"
+#include "source/common/stats/stats_matcher_impl.h"
 #include "source/common/upstream/cluster_factory_impl.h"
 #include "source/common/upstream/health_checker_impl.h"
 #include "source/common/upstream/locality_pool.h"
@@ -174,12 +177,6 @@ HostVector filterHosts(const absl::node_hash_set<HostSharedPtr>& hosts,
   return net_hosts;
 }
 
-Stats::ScopeSharedPtr generateStatsScope(const envoy::config::cluster::v3::Cluster& config,
-                                         Stats::Store& stats) {
-  return stats.createScope(fmt::format(
-      "cluster.{}.", config.alt_stat_name().empty() ? config.name() : config.alt_stat_name()));
-}
-
 Network::ConnectionSocket::OptionsSharedPtr
 buildBaseSocketOptions(const envoy::config::cluster::v3::Cluster& cluster_config,
                        const envoy::config::core::v3::BindConfig& bootstrap_bind_config) {
@@ -419,6 +416,39 @@ const absl::string_view ClusterImplBase::DoNotValidateAlpnRuntimeKey =
 const absl::string_view ClusterImplBase::DropOverloadRuntimeKey =
     "load_balancing_policy.drop_overload_limit";
 
+constexpr absl::string_view StatsMatcherMetadataKey = "envoy.stats_matcher";
+
+Stats::ScopeSharedPtr
+generateStatsScope(const envoy::config::cluster::v3::Cluster& config,
+                   Server::Configuration::ServerFactoryContext& server_context,
+                   bool use_alt_stat_name) {
+  auto& stats = server_context.serverScope().store();
+  Stats::StatsMatcherSharedPtr scope_matcher;
+
+  // Check for a per-cluster stats matcher in typed_filter_metadata under the specific key. If
+  // present, unpack it as StatsMatcher and use it to restrict which stats are created for this
+  // cluster's scope.
+  const auto& typed_meta = config.metadata().typed_filter_metadata();
+  if (auto it = typed_meta.find(StatsMatcherMetadataKey); it != typed_meta.end()) {
+    envoy::config::metrics::v3::StatsMatcher stats_matcher_proto;
+    if (auto status = MessageUtil::unpackTo(it->second, stats_matcher_proto); status.ok()) {
+      MessageUtil::validate(stats_matcher_proto, server_context.messageValidationVisitor());
+      scope_matcher = std::make_shared<Stats::StatsMatcherImpl>(
+          stats_matcher_proto, stats.symbolTable(), server_context);
+    } else {
+      ENVOY_LOG_TO_LOGGER(Envoy::Logger::Registry::getLog(Envoy::Logger::Id::upstream), warn,
+                          "Failed to unpack stats matcher for cluster {}: {}", config.name(),
+                          status.message());
+    }
+  }
+
+  return stats.createScope(
+      fmt::format("cluster.{}.", (!config.alt_stat_name().empty() && use_alt_stat_name)
+                                     ? config.alt_stat_name()
+                                     : config.name()),
+      false, {}, std::move(scope_matcher));
+}
+
 // TODO(pianiststickman): this implementation takes a lock on the hot path and puts a copy of the
 // stat name into every host that receives a copy of that metric. This can be improved by putting
 // a single copy of the stat name into a thread-local key->index map so that the lock can be avoided
@@ -1554,7 +1584,7 @@ ClusterImplBase::ClusterImplBase(const envoy::config::cluster::v3::Cluster& clus
           cluster_context.serverFactoryContext().mainThreadDispatcher())) {
   auto& server_context = cluster_context.serverFactoryContext();
 
-  auto stats_scope = generateStatsScope(cluster, server_context.serverScope().store());
+  auto stats_scope = generateStatsScope(cluster, server_context);
   transport_factory_context_ =
       std::make_unique<Server::Configuration::TransportSocketFactoryContextImpl>(
           server_context, *stats_scope, cluster_context.messageValidationVisitor());
diff --git a/source/common/upstream/upstream_impl.h b/source/common/upstream/upstream_impl.h
@@ -82,6 +82,11 @@ using UpstreamNetworkFilterConfigProviderManager =
     Filter::FilterConfigProviderManager<Network::FilterFactoryCb,
                                         Server::Configuration::UpstreamFactoryContext>;
 
+Stats::ScopeSharedPtr
+generateStatsScope(const envoy::config::cluster::v3::Cluster& config,
+                   Server::Configuration::ServerFactoryContext& server_context,
+                   bool use_alt_stat_name = true);
+
 class LegacyLbPolicyConfigHelper {
 public:
   struct Result {
diff --git a/test/common/upstream/BUILD b/test/common/upstream/BUILD
@@ -560,6 +560,22 @@ envoy_cc_test(
     ],
 )
 
+envoy_cc_test(
+    name = "prod_cluster_info_factory_test",
+    srcs = ["prod_cluster_info_factory_test.cc"],
+    rbe_pool = "6gig",
+    deps = [
+        ":utility_lib",
+        "//source/common/upstream:prod_cluster_info_factory_lib",
+        "//source/extensions/transport_sockets/raw_buffer:config",
+        "//test/mocks/runtime:runtime_mocks",
+        "//test/mocks/server:server_factory_context_mocks",
+        "//test/test_common:utility_lib",
+        "@envoy_api//envoy/config/cluster/v3:pkg_cc_proto",
+        "@envoy_api//envoy/config/metrics/v3:pkg_cc_proto",
+    ],
+)
+
 envoy_cc_test(
     name = "upstream_impl_test",
     srcs = ["upstream_impl_test.cc"],
diff --git a/test/common/upstream/prod_cluster_info_factory_test.cc b/test/common/upstream/prod_cluster_info_factory_test.cc
@@ -0,0 +1,138 @@
+#include "envoy/config/cluster/v3/cluster.pb.h"
+#include "envoy/config/metrics/v3/stats.pb.h"
+
+#include "source/common/upstream/prod_cluster_info_factory.h"
+#include "source/extensions/transport_sockets/raw_buffer/config.h"
+
+#include "test/common/upstream/utility.h"
+#include "test/mocks/runtime/mocks.h"
+#include "test/mocks/server/server_factory_context.h"
+#include "test/test_common/utility.h"
+
+#include "gmock/gmock.h"
+#include "gtest/gtest.h"
+
+using testing::NiceMock;
+using testing::ReturnRef;
+
+namespace Envoy {
+namespace Upstream {
+namespace {
+
+class ProdClusterInfoFactoryTest : public testing::Test {
+protected:
+  ProdClusterInfoFactoryTest() { ON_CALL(server_context_, api()).WillByDefault(ReturnRef(*api_)); }
+
+  ClusterInfoConstSharedPtr createClusterInfo(const envoy::config::cluster::v3::Cluster& cluster) {
+    return factory_.createClusterInfo({server_context_, cluster, bind_config_,
+                                       server_context_.store_, server_context_.ssl_context_manager_,
+                                       false, server_context_.thread_local_});
+  }
+
+  NiceMock<Server::Configuration::MockServerFactoryContext> server_context_;
+  NiceMock<Random::MockRandomGenerator> random_;
+  Api::ApiPtr api_ = Api::createApiForTest(server_context_.store_, random_);
+  envoy::config::core::v3::BindConfig bind_config_;
+  ProdClusterInfoFactory factory_;
+};
+
+// Verify that a cluster without a stats matcher in metadata creates all stats normally.
+TEST_F(ProdClusterInfoFactoryTest, NoMetadataStatsMatcher) {
+  const std::string yaml = R"EOF(
+    name: my_cluster
+    connect_timeout: 0.25s
+    type: STATIC
+    lb_policy: ROUND_ROBIN
+    load_assignment:
+      endpoints:
+        - lb_endpoints:
+          - endpoint:
+              address:
+                socket_address:
+                  address: 127.0.0.1
+                  port_value: 11001
+  )EOF";
+
+  auto info = createClusterInfo(parseClusterFromV3Yaml(yaml));
+  ASSERT_NE(nullptr, info);
+  info->trafficStats();
+
+  // Without a scope matcher, stats of any name are accepted.
+  EXPECT_NE("", info->statsScope().counterFromString("upstream_cx_total").name());
+  EXPECT_NE("", info->statsScope().counterFromString("upstream_rq_total").name());
+}
+
+// Verify that a cluster with typed_filter_metadata["envoy.stats_matcher"] applies an inclusion
+// list: only stats matching the prefix are created; all others are rejected.
+TEST_F(ProdClusterInfoFactoryTest, MetadataStatsMatcherInclusionList) {
+  const std::string yaml = R"EOF(
+    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:
+      endpoints:
+        - lb_endpoints:
+          - endpoint:
+              address:
+                socket_address:
+                  address: 127.0.0.1
+                  port_value: 11001
+  )EOF";
+
+  auto info = createClusterInfo(parseClusterFromV3Yaml(yaml));
+  ASSERT_NE(nullptr, info);
+  info->trafficStats();
+
+  // "cluster.my_cluster.upstream_cx_total" starts with the inclusion prefix — accepted.
+  EXPECT_NE("", info->statsScope().counterFromString("upstream_cx_total").name());
+
+  // "cluster.my_cluster.upstream_rq_total" does not match the prefix — rejected.
+  EXPECT_EQ("", info->statsScope().counterFromString("upstream_rq_total").name());
+}
+
+// Verify that a cluster with an exclusion list rejects only the listed stats.
+TEST_F(ProdClusterInfoFactoryTest, MetadataStatsMatcherExclusionList) {
+  const std::string yaml = R"EOF(
+    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
+          exclusion_list:
+            patterns:
+              - prefix: "cluster.my_cluster.upstream_rq"
+    load_assignment:
+      endpoints:
+        - lb_endpoints:
+          - endpoint:
+              address:
+                socket_address:
+                  address: 127.0.0.1
+                  port_value: 11001
+  )EOF";
+
+  auto info = createClusterInfo(parseClusterFromV3Yaml(yaml));
+  ASSERT_NE(nullptr, info);
+  info->trafficStats();
+
+  // "cluster.my_cluster.upstream_cx_total" does not match the exclusion prefix — accepted.
+  EXPECT_NE("", info->statsScope().counterFromString("upstream_cx_total").name());
+
+  // "cluster.my_cluster.upstream_rq_total" matches the exclusion prefix — rejected.
+  EXPECT_EQ("", info->statsScope().counterFromString("upstream_rq_total").name());
+}
+
+} // namespace
+} // namespace Upstream
+} // namespace Envoy
diff --git a/test/common/upstream/upstream_impl_test.cc b/test/common/upstream/upstream_impl_test.cc
