stats: Add a new Counter Group metric type

include/envoy/router/router.h

@@ -463,7 +463,8 @@ using ShadowPolicyPtr = std::unique_ptr<ShadowPolicy>;
 /**
  * All virtual cluster stats. @see stats_macro.h
  */
-#define ALL_VIRTUAL_CLUSTER_STATS(COUNTER, GAUGE, HISTOGRAM, TEXT_READOUT, STATNAME)               \
+#define ALL_VIRTUAL_CLUSTER_STATS(COUNTER, GAUGE, HISTOGRAM, TEXT_READOUT, COUNTER_GROUP,          \
+                                  STATNAME)                                                        \
   COUNTER(upstream_rq_retry)                                                                       \
   COUNTER(upstream_rq_retry_limit_exceeded)                                                        \
   COUNTER(upstream_rq_retry_overflow)                                                              \

include/envoy/stats/allocator.h

@@ -55,6 +55,18 @@ class Allocator {
    */
   virtual TextReadoutSharedPtr makeTextReadout(StatName name, StatName tag_extracted_name,
                                                const StatNameTagVector& stat_name_tags) PURE;
+
+  /**
+   * @param name the full name of the stat.
+   * @param tag_extracted_name the name of the stat with tag-values stripped out.
+   * @param tags the tag values.
+   * @param max_entries the maximum number of entries in the group.
+   * @return CounterSharedPtr a counter.
+   */
+  virtual CounterGroupSharedPtr makeCounterGroup(StatName name, StatName tag_extracted_name,
+                                                 const StatNameTagVector& stat_name_tags,
+                                                 size_t max_entries) PURE;
+
   virtual const SymbolTable& constSymbolTable() const PURE;
   virtual SymbolTable& symbolTable() PURE;
 

include/envoy/stats/scope.h

@@ -25,6 +25,7 @@ using CounterOptConstRef = absl::optional<std::reference_wrapper<const Counter>>
 using GaugeOptConstRef = absl::optional<std::reference_wrapper<const Gauge>>;
 using HistogramOptConstRef = absl::optional<std::reference_wrapper<const Histogram>>;
 using TextReadoutOptConstRef = absl::optional<std::reference_wrapper<const TextReadout>>;
+using CounterGroupOptConstRef = absl::optional<std::reference_wrapper<const CounterGroup>>;
 using ScopePtr = std::unique_ptr<Scope>;
 using ScopeSharedPtr = std::shared_ptr<Scope>;
 
@@ -178,6 +179,36 @@ class Scope {
    */
   virtual TextReadout& textReadoutFromString(const std::string& name) PURE;
 
+  /**
+   * Creates a CounterGroup from the stat name. Tag extraction will be performed on the name.
+   * @param name The name of the stat, obtained from the SymbolTable.
+   * @param max_entries The size of the group.
+   * @return a counter group within the scope's namespace with a particular value type.
+   */
+  CounterGroup& counterGroupFromStatName(const StatName& name, size_t max_entries) {
+    return counterGroupFromStatNameWithTags(name, absl::nullopt, max_entries);
+  }
+
+  /**
+   * Creates a CounterGroup from the stat name and tags. If tags are not provided, tag extraction
+   * will be performed on the name.
+   * @param name The name of the stat, obtained from the SymbolTable.
+   * @param tags optionally specified tags.
+   * @param max_entries The size of the group.
+   * @return a counter group within the scope's namespace with a particular value type.
+   */
+  virtual CounterGroup& counterGroupFromStatNameWithTags(const StatName& name,
+                                                         StatNameTagVectorOptConstRef tags,
+                                                         size_t max_entries) PURE;
+
+  /**
+   * TODO(#6667): this variant is deprecated: use counterGroupFromStatName.
+   * @param name The name, expressed as a string.
+   * @param max_entries The size of the group.
+   * @return a counter group within the scope's namespace with a particular value type.
+   */
+  virtual CounterGroup& counterGroupFromString(const std::string& name, size_t max_entries) PURE;
+
   /**
    * @param The name of the stat, obtained from the SymbolTable.
    * @return a reference to a counter within the scope's namespace, if it exists.
@@ -203,6 +234,12 @@ class Scope {
    */
   virtual TextReadoutOptConstRef findTextReadout(StatName name) const PURE;
 
+  /**
+   * @param The name of the stat, obtained from the SymbolTable.
+   * @return a reference to a text readout within the scope's namespace, if it exists.
+   */
+  virtual CounterGroupOptConstRef findCounterGroup(StatName name) const PURE;
+
   /**
    * @return a reference to the symbol table.
    */
@@ -249,6 +286,17 @@ class Scope {
    *         was hit.
    */
   virtual bool iterate(const IterateFn<TextReadout>& fn) const PURE;
+
+  /**
+   * Calls 'fn' for every counter group. Note that in the case of overlapping
+   * scopes, the implementation may call fn more than one time for each
+   * counter group. Iteration stops if `fn` returns false;
+   *
+   * @param fn Function to be run for every counter group, or until fn return false.
+   * @return false if fn(text_readout) return false during iteration, true if every counter group
+   *         was hit.
+   */
+  virtual bool iterate(const IterateFn<CounterGroup>& fn) const PURE;
 };
 
 } // namespace Stats

include/envoy/stats/sink.h

@@ -42,6 +42,8 @@ class MetricSnapshot {
    */
   virtual const std::vector<std::reference_wrapper<const TextReadout>>& textReadouts() PURE;
 
+  // TODO(RyanTheOptimist): Add support for counter groups.
+
   /**
    * @return the time in UTC since epoch when the snapshot was created.
    */

include/envoy/stats/stats.h

@@ -190,5 +190,63 @@ class TextReadout : public virtual Metric {
 
 using TextReadoutSharedPtr = RefcountPtr<TextReadout>;
 
+/**
+ * An group of always incrementing counters with latching capability. Each increment is added
+ * both to a global counter as well as periodic counter. Calling latch() returns the periodic
+ * counter and clears it.
+ */
+class CounterGroup : public Metric {
+public:
+  // Counter group type is used internally to disambiguate isolated store
+  // constructors. In the future we can extend it to specify text encoding or
+  // some such.
+  enum class Type {
+    Default, // No particular meaning.
+  };
+  ~CounterGroup() override = default;
+
+  /**
+   * Adds the specified amount to the counter at the specified index.
+   * @param index The index of the counter to add.
+   * @param amount The value to add to the counter.
+   */
+  virtual void add(size_t index, uint64_t amount) PURE;
+
+  /**
+   * Increments the the counter at the specified index.
+   * @param index The index of the counter to increment.
+   */
+  virtual void inc(size_t index) PURE;
+
+  /**
+   * Returns the value of the periodic counter at the specified index, then resets
+   * that periodic counter.
+   * @param index The index of the counter.
+   * @return The value of the counter at the specified index.
+   */
+  virtual uint64_t latch(size_t index) PURE;
+
+  /**
+   * Resets the the counter at the specified index.
+   * @param index The index of the counter to reset.
+   */
+  virtual void reset(size_t index) PURE;
+
+  /**
+   * Returns the value of the counter at the specified index.
+   * @param index The index of the counter.
+   * @return The value of the counter at the specified index.
+   */
+  virtual uint64_t value(size_t index) const PURE;
+
+  /**
+   * Returns the number of entries in the group.
+   * @return The number of entries in the group.
+   */
+  virtual size_t maxEntries() const PURE;
+};
+
+using CounterGroupSharedPtr = RefcountPtr<CounterGroup>;
+
 } // namespace Stats
 } // namespace Envoy

include/envoy/stats/stats_macros.h

@@ -73,10 +73,12 @@ namespace Envoy {
 #define GENERATE_GAUGE_STRUCT(NAME, MODE) Envoy::Stats::Gauge& NAME##_;
 #define GENERATE_HISTOGRAM_STRUCT(NAME, UNIT) Envoy::Stats::Histogram& NAME##_;
 #define GENERATE_TEXT_READOUT_STRUCT(NAME) Envoy::Stats::TextReadout& NAME##_;
+#define GENERATE_COUNTER_GROUP_STRUCT(NAME, MAX_ENTRIES) Envoy::Stats::CounterGroup& NAME##_;
 
 #define FINISH_STAT_DECL_(X) #X)),
 #define FINISH_STAT_DECL_MODE_(X, MODE) #X), Envoy::Stats::Gauge::ImportMode::MODE),
 #define FINISH_STAT_DECL_UNIT_(X, UNIT) #X), Envoy::Stats::Histogram::Unit::UNIT),
+#define FINISH_STAT_DECL_SIZE_(X, SIZE) #X), SIZE),
 
 static inline std::string statPrefixJoin(absl::string_view prefix, absl::string_view token) {
   if (prefix.empty()) {
@@ -92,12 +94,14 @@ static inline std::string statPrefixJoin(absl::string_view prefix, absl::string_
 #define POOL_GAUGE_PREFIX(POOL, PREFIX) (POOL).gaugeFromString(Envoy::statPrefixJoin(PREFIX, FINISH_STAT_DECL_MODE_
 #define POOL_HISTOGRAM_PREFIX(POOL, PREFIX) (POOL).histogramFromString(Envoy::statPrefixJoin(PREFIX, FINISH_STAT_DECL_UNIT_
 #define POOL_TEXT_READOUT_PREFIX(POOL, PREFIX) (POOL).textReadoutFromString(Envoy::statPrefixJoin(PREFIX, FINISH_STAT_DECL_
+#define POOL_COUNTER_GROUP_PREFIX(POOL, PREFIX) (POOL).counterGroupFromString(Envoy::statPrefixJoin(PREFIX, FINISH_STAT_DECL_SIZE_
 #define POOL_STAT_NAME_PREFIX(POOL, PREFIX) (POOL).symbolTable().textReadoutFromString(Envoy::statPrefixJoin(PREFIX, FINISH_STAT_DECL_
 
 #define POOL_COUNTER(POOL) POOL_COUNTER_PREFIX(POOL, "")
 #define POOL_GAUGE(POOL) POOL_GAUGE_PREFIX(POOL, "")
 #define POOL_HISTOGRAM(POOL) POOL_HISTOGRAM_PREFIX(POOL, "")
 #define POOL_TEXT_READOUT(POOL) POOL_TEXT_READOUT_PREFIX(POOL, "")
+#define POOL_COUNTER_GROUP(POOL) POOL_COUNTER_GROUP_PREFIX(POOL, "")
 
 #define NULL_STAT_DECL_(X) std::string(#X)),
 #define NULL_STAT_DECL_IGNORE_MODE_(X, MODE) std::string(#X)),
@@ -123,6 +127,10 @@ static inline std::string statPrefixJoin(absl::string_view prefix, absl::string_
 #define MAKE_STATS_STRUCT_TEXT_READOUT_HELPER_(NAME)                                               \
   , NAME##_(Envoy::Stats::Utility::textReadoutFromStatNames(scope, {prefix, stat_names.NAME##_}))
 
+#define MAKE_STATS_STRUCT_COUNTER_GROUP_HELPER_(NAME, MAX_ENTRIES)                                 \
+  , NAME##_(Envoy::Stats::Utility::counterGroupFromStatNames(scope, {prefix, stat_names.NAME##_},  \
+                                                             MAX_ENTRIES))
+
 #define MAKE_STATS_STRUCT_STATNAME_HELPER_(name)
 #define GENERATE_STATNAME_STRUCT(name)
 
@@ -134,12 +142,12 @@ static inline std::string statPrefixJoin(absl::string_view prefix, absl::string_
 #define MAKE_STAT_NAMES_STRUCT(StatNamesStruct, ALL_STATS)                                         \
   struct StatNamesStruct {                                                                         \
     explicit StatNamesStruct(Envoy::Stats::SymbolTable& symbol_table)                              \
-        : pool_(symbol_table)                                                                      \
-              ALL_STATS(GENERATE_STAT_NAME_INIT, GENERATE_STAT_NAME_INIT, GENERATE_STAT_NAME_INIT, \
-                        GENERATE_STAT_NAME_INIT, GENERATE_STAT_NAME_INIT) {}                       \
+        : pool_(symbol_table) ALL_STATS(GENERATE_STAT_NAME_INIT, GENERATE_STAT_NAME_INIT,          \
+                                        GENERATE_STAT_NAME_INIT, GENERATE_STAT_NAME_INIT,          \
+                                        GENERATE_STAT_NAME_INIT, GENERATE_STAT_NAME_INIT) {}       \
     Envoy::Stats::StatNamePool pool_;                                                              \
     ALL_STATS(GENERATE_STAT_NAME_STRUCT, GENERATE_STAT_NAME_STRUCT, GENERATE_STAT_NAME_STRUCT,     \
-              GENERATE_STAT_NAME_STRUCT, GENERATE_STAT_NAME_STRUCT)                                \
+              GENERATE_STAT_NAME_STRUCT, GENERATE_STAT_NAME_STRUCT, GENERATE_STAT_NAME_STRUCT)     \
   }
 
 /**
@@ -154,14 +162,14 @@ static inline std::string statPrefixJoin(absl::string_view prefix, absl::string_
   struct 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_) {}                                     \
+        : 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_COUNTER_GROUP_HELPER_, MAKE_STATS_STRUCT_STATNAME_HELPER_) {}      \
     const StatNamesStruct& stat_names_;                                                            \
     ALL_STATS(GENERATE_COUNTER_STRUCT, GENERATE_GAUGE_STRUCT, GENERATE_HISTOGRAM_STRUCT,           \
-              GENERATE_TEXT_READOUT_STRUCT, GENERATE_STATNAME_STRUCT)                              \
+              GENERATE_TEXT_READOUT_STRUCT, GENERATE_COUNTER_GROUP_STRUCT,                         \
+              GENERATE_STATNAME_STRUCT)                                                            \
   }
 
 } // namespace Envoy

include/envoy/stats/store.h

@@ -48,6 +48,11 @@ class Store : public Scope {
    * @return a list of all known histograms.
    */
   virtual std::vector<ParentHistogramSharedPtr> histograms() const PURE;
+
+  /**
+   * @return a list of all known counter groups.
+   */
+  virtual std::vector<CounterGroupSharedPtr> counterGroups() const PURE;
 };
 
 using StorePtr = std::unique_ptr<Store>;

include/envoy/upstream/upstream.h

@@ -503,7 +503,7 @@ class PrioritySet {
 /**
  * All cluster stats. @see stats_macros.h
  */
-#define ALL_CLUSTER_STATS(COUNTER, GAUGE, HISTOGRAM, TEXT_READOUT, STATNAME)                       \
+#define ALL_CLUSTER_STATS(COUNTER, GAUGE, HISTOGRAM, TEXT_READOUT, COUNTER_GROUPS, STATNAME)       \
   COUNTER(assignment_stale)                                                                        \
   COUNTER(assignment_timeout_received)                                                             \
   COUNTER(bind_errors)                                                                             \
@@ -595,7 +595,8 @@ class PrioritySet {
  * stats sink. See envoy.api.v2.endpoint.ClusterStats for the definition of upstream_rq_dropped.
  * These are latched by LoadStatsReporter, independent of the normal stats sink flushing.
  */
-#define ALL_CLUSTER_LOAD_REPORT_STATS(COUNTER, GAUGE, HISTOGRAM, TEXT_READOUT, STATNAME)           \
+#define ALL_CLUSTER_LOAD_REPORT_STATS(COUNTER, GAUGE, HISTOGRAM, TEXT_READOUT, COUNTER_GROUP,      \
+                                      STATNAME)                                                    \
   COUNTER(upstream_rq_dropped)
 
 /**
@@ -607,7 +608,8 @@ class PrioritySet {
  * We also include stat-names in this structure that are used when composing
  * the circuit breaker names, depending on priority settings.
  */
-#define ALL_CLUSTER_CIRCUIT_BREAKERS_STATS(COUNTER, GAUGE, HISTOGRAM, TEXT_READOUT, STATNAME)      \
+#define ALL_CLUSTER_CIRCUIT_BREAKERS_STATS(COUNTER, GAUGE, HISTOGRAM, TEXT_READOUT, COUNTER_GROUP, \
+                                           STATNAME)                                               \
   GAUGE(cx_open, Accumulate)                                                                       \
   GAUGE(cx_pool_open, Accumulate)                                                                  \
   GAUGE(rq_open, Accumulate)                                                                       \
@@ -625,7 +627,8 @@ class PrioritySet {
 /**
  * All stats tracking request/response headers and body sizes. Not used by default.
  */
-#define ALL_CLUSTER_REQUEST_RESPONSE_SIZE_STATS(COUNTER, GAUGE, HISTOGRAM, TEXT_READOUT, STATNAME) \
+#define ALL_CLUSTER_REQUEST_RESPONSE_SIZE_STATS(COUNTER, GAUGE, HISTOGRAM, TEXT_READOUT,           \
+                                                COUNTER_GROUP, STATNAME)                           \
   HISTOGRAM(upstream_rq_headers_size, Bytes)                                                       \
   HISTOGRAM(upstream_rq_body_size, Bytes)                                                          \
   HISTOGRAM(upstream_rs_headers_size, Bytes)                                                       \
@@ -634,7 +637,8 @@ class PrioritySet {
 /**
  * All stats around timeout budgets. Not used by default.
  */
-#define ALL_CLUSTER_TIMEOUT_BUDGET_STATS(COUNTER, GAUGE, HISTOGRAM, TEXT_READOUT, STATNAME)        \
+#define ALL_CLUSTER_TIMEOUT_BUDGET_STATS(COUNTER, GAUGE, HISTOGRAM, TEXT_READOUT, COUNTER_GROUP,   \
+                                         STATNAME)                                                 \
   HISTOGRAM(upstream_rq_timeout_budget_percent_used, Unspecified)                                  \
   HISTOGRAM(upstream_rq_timeout_budget_per_try_percent_used, Unspecified)
 
@@ -666,7 +670,8 @@ MAKE_STATS_STRUCT(ClusterTimeoutBudgetStats, ClusterTimeoutBudgetStatNames,
  * Struct definition for cluster circuit breakers stats. @see stats_macros.h
  */
 struct ClusterCircuitBreakersStats {
-  ALL_CLUSTER_CIRCUIT_BREAKERS_STATS(c, GENERATE_GAUGE_STRUCT, h, tr, GENERATE_STATNAME_STRUCT)
+  ALL_CLUSTER_CIRCUIT_BREAKERS_STATS(c, GENERATE_GAUGE_STRUCT, h, tr, GENERATE_COUNTER_GROUP_STRUCT,
+                                     GENERATE_STATNAME_STRUCT)
 };
 
 using ClusterRequestResponseSizeStatsPtr = std::unique_ptr<ClusterRequestResponseSizeStats>;

source/common/router/context_impl.h

@@ -10,7 +10,7 @@ namespace Router {
 /**
  * All router filter stats. @see stats_macros.h
  */
-#define ALL_ROUTER_STATS(COUNTER, GAUGE, HISTOGRAM, TEXT_READOUT, STATNAME)                        \
+#define ALL_ROUTER_STATS(COUNTER, GAUGE, HISTOGRAM, TEXT_READOUT, COUNTER_GROUP, STATNAME)         \
   COUNTER(no_cluster)                                                                              \
   COUNTER(no_route)                                                                                \
   COUNTER(passthrough_internal_redirect_bad_location)                                              \

source/common/stats/BUILD

@@ -47,6 +47,7 @@ envoy_cc_library(
     hdrs = ["isolated_store_impl.h"],
     deps = [
         ":histogram_lib",
+        ":null_counter_group_lib",
         ":null_counter_lib",
         ":null_gauge_lib",
         ":null_text_readout_lib",
@@ -91,6 +92,16 @@ envoy_cc_library(
     ],
 )
 
+envoy_cc_library(
+    name = "null_counter_group_lib",
+    hdrs = ["null_counter_group.h"],
+    deps = [
+        ":metric_impl_lib",
+        ":symbol_table_lib",
+        "//include/envoy/stats:stats_interface",
+    ],
+)
+
 envoy_cc_library(
     name = "null_gauge_lib",
     hdrs = ["null_gauge.h"],
@@ -237,6 +248,7 @@ envoy_cc_library(
     deps = [
         ":allocator_lib",
         ":histogram_lib",
+        ":null_counter_group_lib",
         ":null_counter_lib",
         ":null_gauge_lib",
         ":null_text_readout_lib",