add deferred_creation util into stats

envoy/stats/stats.h

@@ -218,5 +218,44 @@ using SizeFn = std::function<void(std::size_t)>;
  */
 template <typename Stat> using StatFn = std::function<void(Stat&)>;
 
+/**
+ * Interface for stats lazy initialization.
+ * To save memory and CPU consumption from unused stats, Envoy can enable the bootstrap config
+ * :ref:`enable_deferred_creation_stats
+ * <envoy_v3_api_field_config.bootstrap.v3.Bootstrap.enable_deferred_creation_stats>`.
+ * A 'StatsStructType' is only created when any of its field is referenced.
+ * See more context: https://github.com/envoyproxy/envoy/issues/23575
+ */
+template <typename StatsStructType> class DeferredCreationCompatibleInterface {
+public:
+  // Helper function to get-or-create and return the StatsStructType object.
+  virtual StatsStructType& instantiate() PURE;
+
+  virtual ~DeferredCreationCompatibleInterface() = default;
+};
+
+// Template that lazily initializes a StatsStruct.
+// The bootstrap config :ref:`enable_deferred_creation_stats
+// <envoy_v3_api_field_config.bootstrap.v3.Bootstrap.enable_deferred_creation_stats>` decides if
+// stats lazy initialzation is enabled or not.
+template <typename StatsStructType> class DeferredCreation;
+template <typename StatsStructType> class DirectStats;
+
+// A helper class for a lazy compatible stats struct type.
+template <typename StatsStructType> class DeferredCreationCompatibleStats {
+public:
+  DeferredCreationCompatibleStats(
+      std::unique_ptr<DeferredCreationCompatibleInterface<StatsStructType>> d)
+      : data_(std::move(d)) {}
+  // Allows move construct and assign.
+  DeferredCreationCompatibleStats& operator=(DeferredCreationCompatibleStats&&) = default;
+  DeferredCreationCompatibleStats(DeferredCreationCompatibleStats&&) = default;
+
+  inline StatsStructType* operator->() { return &data_->instantiate(); };
+  inline StatsStructType& operator*() { return data_->instantiate(); };
+
+private:
+  std::unique_ptr<DeferredCreationCompatibleInterface<StatsStructType>> data_;
+};
 } // namespace Stats
 } // namespace Envoy

envoy/stats/stats_macros.h

@@ -158,16 +158,17 @@ static inline std::string statPrefixJoin(absl::string_view prefix, absl::string_
  */
 #define MAKE_STATS_STRUCT(StatsStruct, StatNamesStruct, ALL_STATS)                                 \
   struct StatsStruct {                                                                             \
+    using StatNameType = StatNamesStruct;                                                          \
+    static const absl::string_view typeName() { return #StatsStruct; }                             \
     StatsStruct(const StatNamesStruct& stat_names, Envoy::Stats::Scope& scope,                     \
                 Envoy::Stats::StatName prefix = Envoy::Stats::StatName())                          \
         : stat_names_(stat_names)                                                                  \
               ALL_STATS(MAKE_STATS_STRUCT_COUNTER_HELPER_, MAKE_STATS_STRUCT_GAUGE_HELPER_,        \
                         MAKE_STATS_STRUCT_HISTOGRAM_HELPER_,                                       \
                         MAKE_STATS_STRUCT_TEXT_READOUT_HELPER_,                                    \
                         MAKE_STATS_STRUCT_STATNAME_HELPER_) {}                                     \
-    const StatNamesStruct& stat_names_;                                                            \
+    const StatNameType& stat_names_;                                                               \
     ALL_STATS(GENERATE_COUNTER_STRUCT, GENERATE_GAUGE_STRUCT, GENERATE_HISTOGRAM_STRUCT,           \
               GENERATE_TEXT_READOUT_STRUCT, GENERATE_STATNAME_STRUCT)                              \
   }
-
 } // namespace Envoy

source/common/stats/BUILD

@@ -36,6 +36,18 @@ envoy_cc_library(
     ],
 )
 
+envoy_cc_library(
+    name = "deferred_creation",
+    hdrs = ["deferred_creation.h"],
+    deps = [
+        "//envoy/stats:stats_interface",
+        "//source/common/common:cleanup_lib",
+        "//source/common/common:thread_lib",
+        "//source/common/stats:symbol_table_lib",
+        "//source/common/stats:utility_lib",
+    ],
+)
+
 envoy_cc_library(
     name = "histogram_lib",
     srcs = ["histogram_impl.cc"],

source/common/stats/deferred_creation.h

@@ -0,0 +1,112 @@
+#pragma once
+
+#include "envoy/common/pure.h"
+#include "envoy/stats/scope.h"
+#include "envoy/stats/stats.h"
+
+#include "source/common/common/cleanup.h"
+#include "source/common/common/thread.h"
+#include "source/common/stats/symbol_table.h"
+#include "source/common/stats/utility.h"
+
+namespace Envoy {
+namespace Stats {
+
+/**
+ * Lazy-initialization wrapper for StatsStructType, intended for deferred instantiation of a block
+ * of stats that might not be needed in a given Envoy process.
+ *
+ * This class is thread-safe -- instantiations can occur on multiple concurrent threads.
+ * This is used when
+ * :ref:`enable_deferred_creation_stats
+ * <envoy_v3_api_field_config.bootstrap.v3.Bootstrap.enable_deferred_creation_stats>` is enabled.
+ */
+template <typename StatsStructType>
+class DeferredCreation : public DeferredCreationCompatibleInterface<StatsStructType> {
+public:
+  // Capture the stat names object and the scope with a ctor, that can be used to instantiate a
+  // StatsStructType object later.
+  // Caller should make sure scope and stat_names outlive this object.
+  DeferredCreation(const typename StatsStructType::StatNameType& stat_names,
+                   Stats::ScopeSharedPtr scope)
+      : initialized_([&scope]() -> Gauge& {
+          Stats::StatNamePool pool(scope->symbolTable());
+          return Stats::Utility::gaugeFromElements(
+              *scope, {pool.add(StatsStructType::typeName()), pool.add("initialized")},
+              Stats::Gauge::ImportMode::HiddenAccumulate);
+        }()),
+        ctor_([&, stats_scope = std::move(scope)]() -> StatsStructType* {
+          initialized_.inc();
+          // Reset ctor_ to save some RAM.
+          Cleanup reset_ctor([&] { ctor_ = nullptr; });
+          return new StatsStructType(stat_names, *stats_scope);
+        }) {
+    if (initialized_.value() > 0) {
+      instantiate();
+    }
+  }
+  ~DeferredCreation() {
+    if (ctor_ == nullptr) {
+      initialized_.dec();
+    }
+  }
+
+private:
+  inline StatsStructType& instantiate() override { return *internal_stats_.get(ctor_); }
+
+  // In order to preserve stat value continuity across a config reload, we need to automatically
+  // re-instantiate lazy stats when they are constructed, if there is already a live instantiation
+  // to the same stats. Consider the following alternate scenarios:
+
+  // Scenario 1: a cluster is instantiated but receives no requests, so its traffic-related stats
+  // are never instantiated. When this cluster gets reloaded on a config update, a new lazy-init
+  // block is created, but the stats should again not be instantiated.
+
+  // Scenario 2: a cluster is instantiated and receives traffic, so its traffic-related stats are
+  // instantiated. We must ensure that a new instance for the same cluster gets its lazy-stats
+  // instantiated before the previous cluster of the same name is destructed.
+
+  // To do that we keep an "initialized" gauge in the cluster's scope, which will be associated by
+  // name to the previous generation's cluster's lazy-init block. We use the value in this shared
+  // gauge to determine whether to instantiate the lazy block on construction.
+  // TODO(#26106): See #14610. The initialized_ gauge could be disabled in a
+  // corner case where a user disables stats with suffix "initialized". In which case, the
+  // initialized_ will be a NullGauge, which breaks the above scenario 2.
+  // TODO(#26106): Consider hiding this Gauge from being exported, through using the
+  // stats flags mask.
+  Gauge& initialized_;
+  // TODO(#26957): Clean up this ctor_ by moving its ownership to AtomicPtr, and drop
+  // the setter lambda when the nested object is created.
+  std::function<StatsStructType*()> ctor_;
+  Thread::AtomicPtr<StatsStructType, Thread::AtomicPtrAllocMode::DeleteOnDestruct> internal_stats_;
+};
+
+// Non-DeferredCreation wrapper over StatsStructType. This is used when
+// :ref:`enable_deferred_creation_stats
+// <envoy_v3_api_field_config.bootstrap.v3.Bootstrap.enable_deferred_creation_stats>` is not
+// enabled.
+template <typename StatsStructType>
+class DirectStats : public DeferredCreationCompatibleInterface<StatsStructType> {
+public:
+  DirectStats(const typename StatsStructType::StatNameType& stat_names, Stats::Scope& scope)
+      : stats_(stat_names, scope) {}
+
+private:
+  inline StatsStructType& instantiate() override { return stats_; }
+  StatsStructType stats_;
+};
+
+template <typename StatsStructType>
+DeferredCreationCompatibleStats<StatsStructType>
+createDeferredCompatibleStats(Stats::ScopeSharedPtr scope,
+                              const typename StatsStructType::StatNameType& stat_names,
+                              bool deferred_creation) {
+  if (deferred_creation) {
+    return {std::make_unique<DeferredCreation<StatsStructType>>(stat_names, scope)};
+  } else {
+    return {std::make_unique<DirectStats<StatsStructType>>(stat_names, *scope)};
+  }
+}
+
+} // namespace Stats
+} // namespace Envoy

test/common/stats/BUILD

@@ -226,6 +226,42 @@ envoy_cc_benchmark_binary(
     ],
 )
 
+envoy_cc_test(
+    name = "deferred_creation_stats_test",
+    srcs = ["deferred_creation_stats_test.cc"],
+    deps = [
+        "//envoy/stats:stats_interface",
+        "//source/common/memory:stats_lib",
+        "//source/common/stats:deferred_creation",
+        "//source/common/stats:thread_local_store_lib",
+        "//test/test_common:utility_lib",
+    ],
+)
+
+envoy_cc_benchmark_binary(
+    name = "deferred_creation_stats_benchmark",
+    srcs = ["deferred_creation_stats_speed_test.cc"],
+    external_deps = [
+        "benchmark",
+    ],
+    deps = [
+        ":real_thread_test_base",
+        "//source/common/common:random_generator_lib",
+        "//source/common/common:utility_lib",
+        "//source/common/runtime:runtime_lib",
+        "//source/common/stats:deferred_creation",
+        "//source/common/stats:isolated_store_lib",
+        "//source/common/stats:symbol_table_lib",
+        "//source/exe:process_wide_lib",
+    ],
+)
+
+envoy_benchmark_test(
+    name = "deferred_creation_stats_benchmark_test",
+    size = "large",
+    benchmark_binary = "deferred_creation_stats_benchmark",
+)
+
 envoy_benchmark_test(
     name = "symbol_table_benchmark_test",
     benchmark_binary = "symbol_table_benchmark",