stats: strip inner custom namespaces in prometheus names

The Prometheus formatter only stripped a registered custom stat
namespace when it was the leading segment of the tag-extracted name.
This worked for listener/root-scoped Wasm custom stats but not for
upstream Wasm stats scoped under a cluster, where after tag extraction
the namespace ends up in the middle (e.g. `cluster.wasmcustom.foo`),
producing names like `envoy_cluster_wasmcustom_foo`.

Add `CustomStatNamespaces::stripRegisteredInnerNamespace()` and call it
from the Prometheus formatter to strip a registered namespace appearing
as a non-leading, non-trailing segment, without hard-coding `wasmcustom`
or a specific scope depth. Gated by
`envoy.reloadable_features.strip_scoped_custom_stat_namespace`
(default true).

Signed-off-by: Yueshang zuo <zuoyueshang.zys@alibaba-inc.com>

Author: yueshangzuo

changelogs/current/minor_behavior_changes/stats__prometheus-formatter-strips-inner-custom-stat-namespaces.rst

@@ -0,0 +1,9 @@
+The prometheus formatter now strips a registered custom stat namespace (e.g. ``wasmcustom``) when
+it appears as a non-leading, non-trailing segment of a tag-extracted stat name, so that custom
+metrics created on a non-root scope render with the standard ``envoy_`` prefix and without the
+internal namespace. For example an upstream Wasm counter that previously rendered as
+``envoy_cluster_wasmcustom_upstream_rq_2xx`` now renders as ``envoy_cluster_upstream_rq_2xx``,
+matching listener Wasm and native cluster metrics. The ``cluster_name`` and other extracted labels
+are preserved. This primarily fixes upstream HTTP filter Wasm metrics emitted under cluster scope.
+This behavioral change can be temporarily reverted by setting runtime guard
+``envoy.reloadable_features.strip_scoped_custom_stat_namespace`` to ``false``.

envoy/stats/custom_stat_namespaces.h

@@ -1,5 +1,7 @@
 #pragma once
 
+#include <string>
+
 #include "envoy/common/pure.h"
 
 #include "absl/strings/string_view.h"
@@ -46,6 +48,15 @@ class CustomStatNamespaces {
    */
   virtual absl::optional<absl::string_view>
   stripRegisteredPrefix(const absl::string_view stat_name) const PURE;
+
+  /**
+   * Like stripRegisteredPrefix, but for a registered namespace appearing as a non-leading,
+   * non-trailing segment of the dotted stat name (e.g. "cluster.wasmcustom.<m>"). Returns
+   * std::string rather than string_view because the result spans both sides of the removed
+   * segment.
+   */
+  virtual absl::optional<std::string>
+  stripRegisteredInnerNamespace(absl::string_view stat_name) const PURE;
 };
 
 } // namespace Stats

source/common/runtime/runtime_features.cc

@@ -106,6 +106,7 @@ RUNTIME_GUARD(envoy_reloadable_features_skip_dns_lookup_for_proxied_requests);
 RUNTIME_GUARD(envoy_reloadable_features_skip_pending_overflow_count_on_active_rq);
 RUNTIME_GUARD(envoy_reloadable_features_ssl_socket_report_connection_reset);
 RUNTIME_GUARD(envoy_reloadable_features_strict_stats_matcher_unpacked);
+RUNTIME_GUARD(envoy_reloadable_features_strip_scoped_custom_stat_namespace);
 RUNTIME_GUARD(envoy_reloadable_features_tcp_proxy_odcds_over_ads_fix);
 RUNTIME_GUARD(envoy_reloadable_features_test_feature_true);
 RUNTIME_GUARD(envoy_reloadable_features_tls_certificate_compression_brotli);

source/common/stats/custom_stat_namespaces_impl.cc

@@ -1,8 +1,13 @@
 #include "source/common/stats/custom_stat_namespaces_impl.h"
 
+#include <vector>
+
 #include "source/common/common/assert.h"
 #include "source/common/common/thread.h"
 
+#include "absl/strings/str_join.h"
+#include "absl/strings/str_split.h"
+
 namespace Envoy {
 namespace Stats {
 
@@ -29,5 +34,28 @@ CustomStatNamespacesImpl::stripRegisteredPrefix(const absl::string_view stat_nam
   return absl::nullopt;
 };
 
+absl::optional<std::string>
+CustomStatNamespacesImpl::stripRegisteredInnerNamespace(absl::string_view stat_name) const {
+  ASSERT_IS_MAIN_OR_TEST_THREAD();
+  if (namespaces_.empty()) {
+    return absl::nullopt;
+  }
+
+  std::vector<absl::string_view> segments = absl::StrSplit(stat_name, '.');
+  // Need at least scope.namespace.leaf for an inner segment to exist.
+  if (segments.size() < 3) {
+    return absl::nullopt;
+  }
+
+  // Skip the leading scope segment and the trailing leaf.
+  for (size_t i = 1; i + 1 < segments.size(); ++i) {
+    if (registered(segments[i])) {
+      segments.erase(segments.begin() + i);
+      return absl::StrJoin(segments, ".");
+    }
+  }
+  return absl::nullopt;
+}
+
 } // namespace Stats
 } // namespace Envoy

source/common/stats/custom_stat_namespaces_impl.h

@@ -16,6 +16,8 @@ class CustomStatNamespacesImpl : public CustomStatNamespaces {
   void registerStatNamespace(const absl::string_view name) override;
   absl::optional<absl::string_view>
   stripRegisteredPrefix(const absl::string_view stat_name) const override;
+  absl::optional<std::string>
+  stripRegisteredInnerNamespace(absl::string_view stat_name) const override;
 
 private:
   absl::flat_hash_set<std::string> namespaces_;

source/server/admin/BUILD

@@ -224,6 +224,7 @@ envoy_cc_library(
         ":utils_lib",
         "//envoy/stats:custom_stat_namespaces_interface",
         "//source/common/buffer:buffer_lib",
+        "//source/common/runtime:runtime_lib",
         "//source/common/stats:histogram_lib",
         "//source/common/upstream:host_utility_lib",
         "@prometheus_metrics_model//:client_model_cc_proto",

source/server/admin/prometheus_stats.cc

@@ -8,6 +8,7 @@
 #include "source/common/common/macros.h"
 #include "source/common/common/regex.h"
 #include "source/common/protobuf/protobuf.h"
+#include "source/common/runtime/runtime_features.h"
 #include "source/common/stats/histogram_impl.h"
 #include "source/common/upstream/host_utility.h"
 
@@ -956,6 +957,17 @@ PrometheusStatsFormatter::metricName(std::string&& extracted_name,
     return sanitized_name;
   }
 
+  // Inner-segment custom namespace (e.g. upstream Wasm under a cluster scope).
+  if (Runtime::runtimeFeatureEnabled(
+          "envoy.reloadable_features.strip_scoped_custom_stat_namespace")) {
+    absl::optional<std::string> inner_namespace_stripped =
+        custom_namespaces.stripRegisteredInnerNamespace(extracted_name);
+    if (inner_namespace_stripped.has_value()) {
+      sanitizeNameInPlace(inner_namespace_stripped.value());
+      return absl::StrCat("envoy_", inner_namespace_stripped.value());
+    }
+  }
+
   // If it does not have a custom namespace, add namespacing prefix to avoid conflicts, as per best
   // practice: https://prometheus.io/docs/practices/naming/#metric-names Also, naming conventions on
   // https://prometheus.io/docs/concepts/data_model/

source/server/admin/prometheus_stats.h

@@ -126,10 +126,12 @@ class PrometheusStatsFormatter {
                                      const Http::RequestHeaderMap& headers);
 
   /**
-   * Format the given metric name, and prefixed with "envoy_" if it does not have a custom
-   * stat namespace. If it has a custom stat namespace AND the name without the custom namespace
-   * has a valid prometheus namespace, the trimmed name is returned.
-   * Otherwise, return nullopt.
+   * Format a tag-extracted name for Prometheus output:
+   *   - leading registered custom namespace -> stripped, no "envoy_" prefix.
+   *   - inner registered custom namespace   -> stripped, "envoy_" prefix kept.
+   *     Gated by "envoy.reloadable_features.strip_scoped_custom_stat_namespace".
+   *   - otherwise                           -> "envoy_" prefix added.
+   * Returns nullopt if the result would not be a valid Prometheus name.
    */
   static absl::optional<std::string>
   metricName(std::string&& extracted_name,

test/common/stats/custom_stat_namespaces_impl_test.cc

@@ -32,5 +32,53 @@ TEST(CustomStatNamespacesImpl, StripRegisteredPrefix) {
   EXPECT_EQ(actual.value(), "my.extension.metric");
 }
 
+TEST(CustomStatNamespacesImpl, StripRegisteredInnerNamespace) {
+  CustomStatNamespacesImpl namespaces;
+
+  // Empty registry.
+  EXPECT_FALSE(namespaces.stripRegisteredInnerNamespace("cluster.foo.metric").has_value());
+
+  namespaces.registerStatNamespace("wasmcustom");
+
+  // Depth 1.
+  {
+    const absl::optional<std::string> actual =
+        namespaces.stripRegisteredInnerNamespace("cluster.wasmcustom.upstream_rq_2xx");
+    EXPECT_TRUE(actual.has_value());
+    EXPECT_EQ(actual.value(), "cluster.upstream_rq_2xx");
+  }
+
+  // Depth 2.
+  {
+    const absl::optional<std::string> actual =
+        namespaces.stripRegisteredInnerNamespace("scope.subscope.wasmcustom.metric");
+    EXPECT_TRUE(actual.has_value());
+    EXPECT_EQ(actual.value(), "scope.subscope.metric");
+  }
+
+  // Multi-token leaf.
+  {
+    const absl::optional<std::string> actual =
+        namespaces.stripRegisteredInnerNamespace("cluster.wasmcustom.foo.bar.baz");
+    EXPECT_TRUE(actual.has_value());
+    EXPECT_EQ(actual.value(), "cluster.foo.bar.baz");
+  }
+
+  // Leading match: caller should use stripRegisteredPrefix instead.
+  EXPECT_FALSE(namespaces.stripRegisteredInnerNamespace("wasmcustom.metric").has_value());
+
+  // Trailing match: that's the metric leaf, not a namespace boundary.
+  EXPECT_FALSE(namespaces.stripRegisteredInnerNamespace("cluster.foo.wasmcustom").has_value());
+
+  // No registered segment in the middle.
+  EXPECT_FALSE(namespaces.stripRegisteredInnerNamespace("cluster.foo.bar.metric").has_value());
+
+  // Substring within a segment doesn't count.
+  EXPECT_FALSE(namespaces.stripRegisteredInnerNamespace("cluster.wasmcustomx.metric").has_value());
+
+  // No dot at all.
+  EXPECT_FALSE(namespaces.stripRegisteredInnerNamespace("wasmcustom").has_value());
+}
+
 } // namespace Stats
 } // namespace Envoy

test/server/admin/BUILD

@@ -210,6 +210,7 @@ envoy_cc_test(
         "//test/mocks/thread_local:thread_local_mocks",
         "//test/mocks/upstream:cluster_manager_mocks",
         "//test/test_common:stats_utility_lib",
+        "//test/test_common:test_runtime_lib",
         "//test/test_common:utility_lib",
     ],
 )