grpc 1.76.0 → 1.78.0.pre1

data/src/core/telemetry/instrument.h

@@ -29,11 +29,20 @@
 //     unique  combination of label values within a domain creates a separate
 //     instance of the instrumentation storage.
 //
+// *   **Collection Scope:** Defines a scope for collecting metrics, identified
+//     by a set of labels of interest. Metric collection via
+//     `GetStorage`+`Increment` will be filtered according to these labels.
+//     Scopes can be hierarchical.
+//     On destruction, metrics collected in this scope are aggregated into the
+//     parent scopes.
+//
 // *   **Storage:** An object holding the current values for all instruments
-//     within a domain, for a *specific combination* of label values. Storage
-//     objects are ref-counted and managed by the domain. You obtain a
-//     `RefCountedPtr<Storage>` using `Domain::GetStorage(...)`, passing the
-//     current label values.
+//     within a domain, for a *specific combination* of filtered label values.
+//     Its lifetime is managed by one or more `CollectionScope`s. You obtain a
+//     `RefCountedPtr<Storage>` using `Domain::GetStorage(scope, ...)`, passing
+//     the current label values. If a child scope's filtered labels match its
+//     parent's filtered labels for a given metric, the parent's `Storage`
+//     instance is reused (shared).
 //
 // *   **Backend:** Determines how the metric data is stored and aggregated
 //     within a Storage object. Examples include `LowContentionBackend` and
@@ -105,7 +114,8 @@
 //   };
 //
 // To increment the counter:
-//   auto storage = MyDomain::GetStorage("label_val1", "label_val2");
+//   auto scope = CreateCollectionScope({}, {}); // Or some other scope
+//   auto storage = MyDomain::GetStorage(scope, "label_val1", "label_val2");
 //   storage->Increment(MyDomain::kMyCounter);
 //
 // To set the gauge (inside a callback):
@@ -116,6 +126,9 @@
 // The `MetricsQuery` class is used to fetch metric data. You can filter by
 // label values, select specific metrics, and collapse labels (aggregate over
 // them). The results are emitted to a `MetricsSink` interface.
+// `MetricsQuery::Run(scope, sink)` operates on a given `CollectionScope`,
+// querying all unique storage instances reachable from that scope and its
+// children.
 //
 // ## Aggregability
 //
@@ -126,6 +139,35 @@
 //     includes gauges is not meaningful, as summing up current values from
 //     different sources makes no sense. The `MetricsSink` will receive
 //     individual gauge readings for each label set matching the filter.
+//
+// ## Collection Scope Hierarchy
+//
+// Collection scopes form a DAG. The typical layout is to have a collection of
+// root scopes, a trunk scope ("the global scope"), and a set of leaf scopes:
+//
+// ┌────────┐     ┌────────┐
+// │ Root 1 │     │ Root 2 │     ...
+// └───┬────┘     └───┬────┘
+//     │              │
+//     └──────────────┤
+//                    │
+//             ┌──────▼───────┐
+//             │ Global Scope │
+//             └──────┬───────┘
+//                    │
+//     ┌──────────────┤
+//     │              │
+// ┌───▼────┐     ┌───▼────┐
+// │ Leaf 1 │     │ Leaf 2 │     ...
+// └────────┘     └────────┘
+//
+// The root scopes correspond to global stats plugins in the higher level
+// system. The leaf scopes correspond to per-channel stats plugins. The global
+// (trunk) scope is not associated with any stats plugin, but allows
+// non-channel-related metrics to be aggregated into the global stats plugins.
+//
+// When creating a storage instance systems should use the most specific scope
+// (lowest in the tree) that matches the current context.
 
 #ifndef GRPC_SRC_CORE_TELEMETRY_INSTRUMENT_H
 #define GRPC_SRC_CORE_TELEMETRY_INSTRUMENT_H
@@ -134,40 +176,50 @@
 #include <grpc/support/port_platform.h>
 
 #include <algorithm>
-#include <array>
 #include <atomic>
+#include <cstddef>
 #include <cstdint>
 #include <memory>
 #include <optional>
 #include <string>
 #include <tuple>
+#include <type_traits>
 #include <utility>
 #include <variant>
 #include <vector>
 
+#include "src/core/channelz/channelz.h"
+#include "src/core/telemetry/histogram.h"
+#include "src/core/util/avl.h"
+#include "src/core/util/dual_ref_counted.h"
+#include "src/core/util/grpc_check.h"
+#include "src/core/util/per_cpu.h"
+#include "src/core/util/ref_counted.h"
+#include "src/core/util/ref_counted_ptr.h"
+#include "src/core/util/single_set_ptr.h"
+#include "src/core/util/sync.h"
 #include "absl/base/thread_annotations.h"
 #include "absl/container/flat_hash_map.h"
 #include "absl/container/flat_hash_set.h"
 #include "absl/container/node_hash_map.h"
+#include "absl/functional/any_invocable.h"
+#include "absl/functional/function_ref.h"
+#include "absl/hash/hash.h"
 #include "absl/log/log.h"
 #include "absl/strings/str_cat.h"
 #include "absl/strings/string_view.h"
 #include "absl/types/span.h"
-#include "src/core/telemetry/histogram.h"
-#include "src/core/util/avl.h"
-#include "src/core/util/dual_ref_counted.h"
-#include "src/core/util/match.h"
-#include "src/core/util/per_cpu.h"
-#include "src/core/util/ref_counted_ptr.h"
-#include "src/core/util/sync.h"
 
 namespace grpc_core {
 
 class InstrumentTest;
+class GlobalCollectionScopeManager;
+
+static constexpr absl::string_view kOmittedLabel = "<omitted>";
 
 namespace instrument_detail {
 class QueryableDomain;
-class StorageSet;
+class DomainStorage;
 }  // namespace instrument_detail
 
 class CollectionScope;
@@ -175,13 +227,14 @@ class CollectionScope;
 class InstrumentMetadata {
  public:
   struct CounterShape {};
+  struct UpDownCounterShape {};
   struct DoubleGaugeShape {};
   struct IntGaugeShape {};
   struct UintGaugeShape {};
   using HistogramShape = HistogramBuckets;
 
-  using Shape = std::variant<CounterShape, HistogramShape, DoubleGaugeShape,
-                             IntGaugeShape, UintGaugeShape>;
+  using Shape = std::variant<CounterShape, UpDownCounterShape, HistogramShape,
+                             DoubleGaugeShape, IntGaugeShape, UintGaugeShape>;
 
   // A description of a metric.
   struct Description {
@@ -218,20 +271,60 @@ using HistogramCollectionHook = absl::AnyInvocable<void(
     absl::Span<const std::string> labels, int64_t value)>;
 void RegisterHistogramCollectionHook(HistogramCollectionHook hook);
 
-// A CollectionScope ensures that all metric updates in its lifetime are visible
-// to a MetricsQuery.
-class CollectionScope {
+// Defines a scope for collecting metrics, identified by a set of labels of
+// interest. Metric collection via GetStorage+Increment will be filtered
+// according to these labels. Scopes can be hierarchical. On destruction,
+// metrics collected in this scope are aggregated into the parent scope.
+class CollectionScope : public RefCounted<CollectionScope> {
  public:
-  explicit CollectionScope(
-      std::vector<std::unique_ptr<instrument_detail::StorageSet>> storage_sets);
+  CollectionScope(std::vector<RefCountedPtr<CollectionScope>> parents,
+                  absl::Span<const std::string> labels,
+                  size_t child_shards_count, size_t storage_shards_count);
+  ~CollectionScope() override;
 
   size_t TestOnlyCountStorageHeld() const;
 
+  void ForEachUniqueStorage(
+      absl::FunctionRef<void(instrument_detail::DomainStorage*)> cb);
+
+  bool ObservesLabel(absl::string_view label) const {
+    return labels_of_interest_.contains(label);
+  }
+
+  bool IsRoot() const { return parents_.empty(); }
+
  private:
+  friend class GlobalCollectionScopeManager;
   friend class MetricsQuery;
-  std::vector<instrument_detail::StorageSet*> GetStorageSets();
+  friend class instrument_detail::QueryableDomain;
+
+  struct StorageShard {
+    mutable Mutex mu;
+    absl::flat_hash_map<std::pair<instrument_detail::QueryableDomain*,
+                                  std::vector<std::string>>,
+                        RefCountedPtr<instrument_detail::DomainStorage>>
+        storage ABSL_GUARDED_BY(mu);
+  };
 
-  std::vector<std::unique_ptr<instrument_detail::StorageSet>> storage_sets_;
+  struct ChildShard {
+    Mutex mu;
+    absl::flat_hash_set<CollectionScope*> children ABSL_GUARDED_BY(mu);
+  };
+
+  ChildShard& child_shard(CollectionScope* child) {
+    return child_shards_[absl::HashOf(child) % child_shards_.size()];
+  }
+
+  std::vector<RefCountedPtr<CollectionScope>> parents_;
+  absl::flat_hash_set<std::string> labels_of_interest_;
+  std::vector<ChildShard> child_shards_;
+  std::vector<StorageShard> storage_shards_;
+
+  void ForEachUniqueStorage(
+      absl::FunctionRef<void(instrument_detail::DomainStorage*)> cb,
+      absl::flat_hash_set<instrument_detail::DomainStorage*>& visited);
+
+  void TestOnlyReset();
 };
 
 namespace instrument_detail {
@@ -245,28 +338,28 @@ class GaugeStorage {
   explicit GaugeStorage(QueryableDomain* domain);
 
   void SetDouble(uint64_t offset, double value) {
-    DCHECK_LT(offset, double_gauges_.size());
+    GRPC_DCHECK_LT(offset, double_gauges_.size());
     double_gauges_[offset] = value;
   }
   void SetInt(uint64_t offset, int64_t value) {
-    DCHECK_LT(offset, int_gauges_.size());
+    GRPC_DCHECK_LT(offset, int_gauges_.size());
     int_gauges_[offset] = value;
   }
   void SetUint(uint64_t offset, uint64_t value) {
-    DCHECK_LT(offset, uint_gauges_.size());
+    GRPC_DCHECK_LT(offset, uint_gauges_.size());
     uint_gauges_[offset] = value;
   }
 
   std::optional<double> GetDouble(uint64_t offset) const {
-    DCHECK_LT(offset, double_gauges_.size());
+    GRPC_DCHECK_LT(offset, double_gauges_.size());
     return double_gauges_[offset];
   }
   std::optional<int64_t> GetInt(uint64_t offset) const {
-    DCHECK_LT(offset, int_gauges_.size());
+    GRPC_DCHECK_LT(offset, int_gauges_.size());
     return int_gauges_[offset];
   }
   std::optional<uint64_t> GetUint(uint64_t offset) const {
-    DCHECK_LT(offset, uint_gauges_.size());
+    GRPC_DCHECK_LT(offset, uint_gauges_.size());
     return uint_gauges_[offset];
   }
 
@@ -276,51 +369,29 @@ class GaugeStorage {
   std::vector<std::optional<uint64_t>> uint_gauges_;
 };
 
-class DomainStorage : public DualRefCounted<DomainStorage> {
+class DomainStorage : public DualRefCounted<DomainStorage>,
+                      public channelz::DataSource {
  public:
   DomainStorage(QueryableDomain* domain, std::vector<std::string> label);
 
   void Orphaned() override;
 
   virtual uint64_t SumCounter(size_t index) = 0;
+  virtual void Add(DomainStorage* other) = 0;
 
+  // Returns the label values of the CollectionScope that owns this storage.
+  // This is the full set of labels published by the domain, with unused labels
+  // in the scope set to kOmittedLabel.
   absl::Span<const std::string> label() const { return label_; }
   QueryableDomain* domain() const { return domain_; }
 
   virtual void FillGaugeStorage(GaugeStorage& gauge_storage) = 0;
 
- private:
-  QueryableDomain* domain_;
-  const std::vector<std::string> label_;
-};
-
-// Interface for a set of storage objects for a domain.
-// Each StorageSet is a collection of storage objects for a domain, one storage
-// object per unique set of labels.
-// The StorageSet subscribes to new label sets being created, so that all
-// storage in a time period can be exported.
-class StorageSet {
- public:
-  StorageSet(QueryableDomain* domain, size_t map_shards_size);
-  virtual ~StorageSet();
-  void ExportMetrics(
-      MetricsSink& sink,
-      absl::Span<const InstrumentMetadata::Description* const> metrics);
-  size_t TestOnlyCountStorageHeld() const;
-  QueryableDomain* domain() const { return domain_; }
-
-  void AddStorage(WeakRefCountedPtr<DomainStorage> storage);
+  void AddData(channelz::DataSink sink) override;
 
  private:
-  struct MapShard {
-    mutable Mutex mu;
-    AVL<absl::Span<const std::string>, WeakRefCountedPtr<DomainStorage>>
-        storage_map ABSL_GUARDED_BY(mu);
-  };
-
   QueryableDomain* domain_;
-  std::unique_ptr<MapShard[]> map_shards_;
-  const size_t map_shards_size_;
+  const std::vector<std::string> label_;
 };
 
 // A registry of metrics.
@@ -372,20 +443,44 @@ class QueryableDomain {
   // Reset the internal state of this domain. For test use only.
   void TestOnlyReset();
 
-  static std::unique_ptr<CollectionScope> CreateCollectionScope();
   size_t TestOnlyCountStorageHeld() const;
 
+  // Returns the number of slots allocated for each metric type.
+  uint64_t allocated_counter_slots() const { return allocated_counter_slots_; }
+  uint64_t allocated_double_gauge_slots() const {
+    return allocated_double_gauge_slots_;
+  }
+  uint64_t allocated_int_gauge_slots() const {
+    return allocated_int_gauge_slots_;
+  }
+  uint64_t allocated_uint_gauge_slots() const {
+    return allocated_uint_gauge_slots_;
+  }
+
+  RefCountedPtr<DomainStorage> GetDomainStorage(
+      RefCountedPtr<CollectionScope> scope,
+      absl::Span<const std::string> label);
+
+  absl::string_view name() const { return name_; }
+
+  RefCountedPtr<channelz::BaseNode> channelz_node() {
+    if (!channelz_.is_set()) {
+      return channelz_.Set(new ChannelzState(this))->channelz_node();
+    }
+    return channelz_->channelz_node();
+  }
+
  protected:
-  QueryableDomain(std::vector<std::string> label_names, size_t map_shards_size)
+  QueryableDomain(std::string name, std::vector<std::string> label_names,
+                  size_t map_shards_size)
       : label_names_(std::move(label_names)),
         map_shards_size_(label_names_.empty() ? 1 : map_shards_size),
-        map_shards_(std::make_unique<MapShard[]>(map_shards_size_)) {}
+        map_shards_(std::make_unique<MapShard[]>(map_shards_size_)),
+        name_(std::move(name)) {}
 
   // QueryableDomain should never be destroyed.
   ~QueryableDomain() { LOG(FATAL) << "QueryableDomain destroyed."; }
 
-  RefCountedPtr<DomainStorage> GetDomainStorage(std::vector<std::string> label);
-
   // Called by InstrumentDomain when construction is complete.
   void Constructed();
 
@@ -393,6 +488,9 @@ class QueryableDomain {
   const InstrumentMetadata::Description* AllocateCounter(
       absl::string_view name, absl::string_view description,
       absl::string_view unit);
+  const InstrumentMetadata::Description* AllocateUpDownCounter(
+      absl::string_view name, absl::string_view description,
+      absl::string_view unit);
   const InstrumentMetadata::Description* AllocateHistogram(
       absl::string_view name, absl::string_view description,
       absl::string_view unit, HistogramBuckets bounds);
@@ -406,20 +504,7 @@ class QueryableDomain {
       absl::string_view name, absl::string_view description,
       absl::string_view unit);
 
-  // Returns the number of slots allocated for each metric type.
-  uint64_t allocated_counter_slots() const { return allocated_counter_slots_; }
-  uint64_t allocated_double_gauge_slots() const {
-    return allocated_double_gauge_slots_;
-  }
-  uint64_t allocated_int_gauge_slots() const {
-    return allocated_int_gauge_slots_;
-  }
-  uint64_t allocated_uint_gauge_slots() const {
-    return allocated_uint_gauge_slots_;
-  }
-
  private:
-  friend class StorageSet;
   friend class DomainStorage;
   friend class GaugeStorage;
 
@@ -429,15 +514,28 @@ class QueryableDomain {
         storage_map ABSL_GUARDED_BY(mu);
   };
 
-  void RegisterStorageSet(StorageSet* storage_set);
-  void UnregisterStorageSet(StorageSet* storage_set);
+  struct ChannelzState final : public channelz::DataSource {
+    explicit ChannelzState(QueryableDomain* domain)
+        : DataSource(MakeRefCounted<channelz::MetricsDomainNode>(
+              std::string(domain->name()))),
+          domain(domain) {
+      SourceConstructed();
+    }
+    ~ChannelzState() { SourceDestructing(); }
+    QueryableDomain* const domain;
+    void AddData(channelz::DataSink sink) override { domain->AddData(sink); }
+    RefCountedPtr<channelz::BaseNode> channelz_node() {
+      return DataSource::channelz_node();
+    }
+  };
 
-  std::unique_ptr<StorageSet> CreateStorageSet();
   virtual RefCountedPtr<DomainStorage> CreateDomainStorage(
       std::vector<std::string> label) = 0;
   void DomainStorageOrphaned(DomainStorage* storage);
   MapShard& GetMapShard(absl::Span<const std::string> label);
 
+  void AddData(channelz::DataSink sink);
+
   // Allocate `size` elements in the domain.
   // Counters will allocate one element. Histograms will allocate one per
   // bucket.
@@ -459,15 +557,11 @@ class QueryableDomain {
   uint64_t allocated_int_gauge_slots_ = 0;
   uint64_t allocated_uint_gauge_slots_ = 0;
 
-  Mutex storage_sets_mu_;
-  std::vector<StorageSet*> storage_sets_ ABSL_GUARDED_BY(storage_sets_mu_);
-
   const size_t map_shards_size_;
   std::unique_ptr<MapShard[]> map_shards_;
 
-  mutable Mutex active_storage_sets_mu_;
-  std::vector<StorageSet*> active_storage_sets_
-      ABSL_GUARDED_BY(active_storage_sets_mu_);
+  std::string name_;
+  SingleSetPtr<ChannelzState> channelz_;
 };
 
 // An InstrumentDomain is a collection of metrics with a common set of labels.
@@ -486,11 +580,14 @@ struct Counter {
 };
 
 // An InstrumentHandle is a handle to a single metric in an
-// InstrumentDomainImpl. kType is used in using statements to disambiguate
-// between different InstrumentHandle specializations. Backed, Label... are
-// per InstrumentDomainImpl.
+// instrument domain. It has a Shape (how the metric behaves).
 template <typename Shape, typename Domain>
 class InstrumentHandle {
+ public:
+  absl::string_view name() const { return description_->name; }
+  absl::string_view description() const { return description_->description; }
+  absl::string_view unit() const { return description_->unit; }
+
  private:
   friend Domain;
 
@@ -512,7 +609,7 @@ template <typename T>
 using StdString = std::string;
 
 template <typename T>
-using ConstCharPtr = const char*;
+using AbslStringView = absl::string_view;
 
 }  // namespace instrument_detail
 
@@ -523,9 +620,17 @@ class LowContentionBackend final {
  public:
   explicit LowContentionBackend(size_t size);
 
-  void Increment(size_t index) {
-    counters_[index].fetch_add(1, std::memory_order_relaxed);
+  void Add(size_t index, uint64_t amount) {
+    counters_[index].fetch_add(amount, std::memory_order_relaxed);
+  }
+  void Subtract(size_t index, uint64_t amount) {
+    uint64_t old_value =
+        counters_[index].fetch_sub(amount, std::memory_order_relaxed);
+    // Every decrement should have a corresponding increment.
+    GRPC_DCHECK(old_value >= amount);
   }
+  void Increment(size_t index) { Add(index, 1); }
+  void Decrement(size_t index) { Subtract(index, 1); }
 
   uint64_t Sum(size_t index);
 
@@ -541,14 +646,21 @@ class HighContentionBackend final {
  public:
   explicit HighContentionBackend(size_t size);
 
-  void Increment(size_t index) {
-    counters_.this_cpu()[index].fetch_add(1, std::memory_order_relaxed);
+  void Add(size_t index, uint64_t amount) {
+    counters_.this_cpu()[index].fetch_add(amount, std::memory_order_relaxed);
+  }
+  void Subtract(size_t index, uint64_t amount) {
+    counters_.this_cpu()[index].fetch_sub(amount, std::memory_order_relaxed);
   }
+  void Increment(size_t index) { Add(index, 1); }
+  void Decrement(size_t index) { Subtract(index, 1); }
 
   uint64_t Sum(size_t index);
 
  private:
-  PerCpu<std::unique_ptr<std::atomic<uint64_t>[]>> counters_{
+  // Since Increments and Decrements can happen on different CPUs, we need to
+  // use a int64_t counter. The sum should still be a uint64_t.
+  PerCpu<std::unique_ptr<std::atomic<int64_t>[]>> counters_{
       PerCpuOptions().SetMaxShards(16)};
 };
 
@@ -558,16 +670,24 @@ class MetricsSink {
  public:
   // Called once per label per metric, with the value of that metric for that
   // label.
-  virtual void Counter(absl::Span<const std::string> label,
+  virtual void Counter(absl::Span<const std::string> label_keys,
+                       absl::Span<const std::string> label_values,
                        absl::string_view name, uint64_t value) = 0;
-  virtual void Histogram(absl::Span<const std::string> label,
+  virtual void UpDownCounter(absl::Span<const std::string> label_keys,
+                             absl::Span<const std::string> label_values,
+                             absl::string_view name, uint64_t value) = 0;
+  virtual void Histogram(absl::Span<const std::string> label_keys,
+                         absl::Span<const std::string> label_values,
                          absl::string_view name, HistogramBuckets bounds,
                          absl::Span<const uint64_t> counts) = 0;
-  virtual void DoubleGauge(absl::Span<const std::string> labels,
+  virtual void DoubleGauge(absl::Span<const std::string> label_keys,
+                           absl::Span<const std::string> label_values,
                            absl::string_view name, double value) = 0;
-  virtual void IntGauge(absl::Span<const std::string> labels,
+  virtual void IntGauge(absl::Span<const std::string> label_keys,
+                        absl::Span<const std::string> label_values,
                         absl::string_view name, int64_t value) = 0;
-  virtual void UintGauge(absl::Span<const std::string> labels,
+  virtual void UintGauge(absl::Span<const std::string> label_keys,
+                         absl::Span<const std::string> label_values,
                          absl::string_view name, uint64_t value) = 0;
 
  protected:
@@ -589,22 +709,22 @@ class MetricsQuery {
   // remaining dimensions, etc.
   MetricsQuery& CollapseLabels(absl::Span<const std::string> labels);
   // Only include metrics that are in `metrics`.
-  MetricsQuery& OnlyMetrics(absl::Span<const std::string> metrics);
+  MetricsQuery& OnlyMetrics(std::vector<std::string> metrics);
 
   // Returns the metrics that are selected by this query.
   std::optional<absl::Span<const std::string>> selected_metrics() const {
     return only_metrics_;
   }
 
+  // Runs the query, outputting the results to `sink`.
+  void Run(RefCountedPtr<CollectionScope> scope, MetricsSink& sink) const;
+
+ private:
   // Adapts `sink` by including the filtering requested, and then calls `fn`
   // with the filtering sink. This is mainly an implementation detail.
   void Apply(absl::Span<const std::string> label_names,
              absl::FunctionRef<void(MetricsSink&)> fn, MetricsSink& sink) const;
 
-  // Runs the query, outputting the results to `sink`.
-  void Run(std::unique_ptr<CollectionScope> scope, MetricsSink& sink) const;
-
- private:
   void ApplyLabelChecks(absl::Span<const std::string> label_names,
                         absl::FunctionRef<void(MetricsSink&)> fn,
                         MetricsSink& sink) const;
@@ -642,6 +762,8 @@ class InstrumentDomainImpl final : public QueryableDomain {
  public:
   using Self = InstrumentDomainImpl<Backend, N, Tag>;
   using CounterHandle = InstrumentHandle<Counter, Self>;
+  using UpDownCounterHandle =
+      InstrumentHandle<InstrumentMetadata::UpDownCounterShape, Self>;
   using DoubleGaugeHandle =
       InstrumentHandle<InstrumentMetadata::DoubleGaugeShape, Self>;
   using IntGaugeHandle =
@@ -682,16 +804,16 @@ class InstrumentDomainImpl final : public QueryableDomain {
    protected:
     explicit GaugeProvider(RefCountedPtr<Storage> storage)
         : storage_(std::move(storage)) {
-      DCHECK(storage_ != nullptr);
+      GRPC_DCHECK(storage_ != nullptr);
     }
-    ~GaugeProvider() { DCHECK(storage_ == nullptr); }
+    ~GaugeProvider() { GRPC_DCHECK(storage_ == nullptr); }
 
     void ProviderConstructed() {
-      DCHECK(storage_ != nullptr);
+      GRPC_DCHECK(storage_ != nullptr);
       storage_->RegisterGaugeProvider(this);
     }
     void ProviderDestructing() {
-      DCHECK(storage_ != nullptr);
+      GRPC_DCHECK(storage_ != nullptr);
       storage_->UnregisterGaugeProvider(this);
       storage_.reset();
     }
@@ -708,16 +830,35 @@ class InstrumentDomainImpl final : public QueryableDomain {
 
     // Increments the counter specified by `handle` by 1 for this storages
     // labels.
-    void Increment(CounterHandle handle) {
-      DCHECK_EQ(handle.instrument_domain_, domain());
-      backend_.Increment(handle.offset_);
+    void Increment(CounterHandle handle, uint64_t amount = 1) {
+      GRPC_DCHECK_EQ(handle.instrument_domain_, domain());
+      backend_.Add(handle.offset_, amount);
+    }
+
+    void Increment(UpDownCounterHandle handle, uint64_t amount = 1) {
+      GRPC_DCHECK_EQ(handle.instrument_domain_, domain());
+      backend_.Add(handle.offset_, amount);
+    }
+
+    void Decrement(UpDownCounterHandle handle, uint64_t amount = 1) {
+      GRPC_DCHECK_EQ(handle.instrument_domain_, domain());
+      backend_.Subtract(handle.offset_, amount);
+    }
+
+    void Add(DomainStorage* other) override {
+      GRPC_DCHECK_EQ(domain(), other->domain());
+      for (size_t i = 0; i < domain()->allocated_counter_slots(); ++i) {
+        uint64_t amount = other->SumCounter(i);
+        if (amount == 0) continue;
+        backend_.Add(i, amount);
+      }
     }
 
     template <typename Shape>
     void Increment(const HistogramHandle<Shape>& handle, int64_t value) {
-      DCHECK_EQ(handle.instrument_domain_, domain());
+      GRPC_DCHECK_EQ(handle.instrument_domain_, domain());
       CallHistogramCollectionHooks(handle.description_, label(), value);
-      backend_.Increment(handle.offset_ + handle.shape_->BucketFor(value));
+      backend_.Add(handle.offset_ + handle.shape_->BucketFor(value), 1);
     }
 
    private:
@@ -758,10 +899,10 @@ class InstrumentDomainImpl final : public QueryableDomain {
   };
 
   GPR_ATTRIBUTE_NOINLINE explicit InstrumentDomainImpl(
-      std::vector<std::string> label_names,
+      std::string name, std::vector<std::string> label_names,
       size_t map_shards = std::min(16u, gpr_cpu_num_cores()))
-      : QueryableDomain(std::move(label_names), map_shards) {
-    CHECK_EQ(this->label_names().size(), N);
+      : QueryableDomain(std::move(name), std::move(label_names), map_shards) {
+    GRPC_CHECK_EQ(this->label_names().size(), N);
     Constructed();
   }
 
@@ -777,6 +918,14 @@ class InstrumentDomainImpl final : public QueryableDomain {
                          Counter{}};
   }
 
+  UpDownCounterHandle RegisterUpDownCounter(absl::string_view name,
+                                            absl::string_view description,
+                                            absl::string_view unit) {
+    return UpDownCounterHandle{this,
+                               AllocateUpDownCounter(name, description, unit),
+                               InstrumentMetadata::UpDownCounterShape{}};
+  }
+
   template <typename Shape, typename... Args>
   HistogramHandle<Shape> RegisterHistogram(absl::string_view name,
                                            absl::string_view description,
@@ -812,13 +961,14 @@ class InstrumentDomainImpl final : public QueryableDomain {
   // GetStorage: returns a pointer to the storage for the given key, creating
   // it if necessary.
   template <typename... Args>
-  RefCountedPtr<Storage> GetStorage(Args&&... labels) {
+  RefCountedPtr<Storage> GetStorage(RefCountedPtr<CollectionScope> scope,
+                                    Args&&... labels) {
     static_assert(sizeof...(Args) == N, "Incorrect number of labels provided");
-    std::vector<std::string> label_names;
-    label_names.reserve(N);
-    (label_names.emplace_back(absl::StrCat(labels)), ...);
+    std::vector<std::string> label_values;
+    label_values.reserve(N);
+    (label_values.emplace_back(absl::StrCat(labels)), ...);
     return DownCastRefCountedPtr<Storage>(
-        GetDomainStorage(std::move(label_names)));
+        GetDomainStorage(std::move(scope), label_values));
   }
 
   RefCountedPtr<DomainStorage> CreateDomainStorage(
@@ -852,20 +1002,23 @@ class InstrumentDomain {
     static auto* domain = new instrument_detail::InstrumentDomainImpl<
         typename Derived::Backend,
         std::tuple_size_v<decltype(Derived::kLabels)>, Derived>(
+        absl::StrCat(Derived::kName),
         instrument_detail::MakeLabelFromTuple(Derived::kLabels));
     return domain;
   }
 
   // Returns an InstrumentStorageRefPtr<Derived>.
   template <typename... Args>
-  static auto GetStorage(Args&&... labels) {
-    return Domain()->GetStorage(std::forward<Args>(labels)...);
+  static auto GetStorage(RefCountedPtr<CollectionScope> scope,
+                         Args&&... labels) {
+    return Domain()->GetStorage(std::move(scope),
+                                std::forward<Args>(labels)...);
   }
 
  protected:
   template <typename... Label>
   static constexpr auto Labels(Label... labels) {
-    return std::tuple<instrument_detail::ConstCharPtr<Label>...>{labels...};
+    return std::tuple<instrument_detail::AbslStringView<Label>...>{labels...};
   }
 
   static auto RegisterCounter(absl::string_view name,
@@ -874,6 +1027,12 @@ class InstrumentDomain {
     return Domain()->RegisterCounter(name, description, unit);
   }
 
+  static auto RegisterUpDownCounter(absl::string_view name,
+                                    absl::string_view description,
+                                    absl::string_view unit) {
+    return Domain()->RegisterUpDownCounter(name, description, unit);
+  }
+
   template <typename Shape, typename... Args>
   static auto RegisterHistogram(absl::string_view name,
                                 absl::string_view description,
@@ -923,9 +1082,23 @@ using GaugeProvider = typename InstrumentDomainImpl<DomainType>::GaugeProvider;
 // Reset all registered instruments. For test use only.
 void TestOnlyResetInstruments();
 
-inline std::unique_ptr<CollectionScope> CreateCollectionScope() {
-  return instrument_detail::QueryableDomain::CreateCollectionScope();
-}
+// Create a new collection scope.
+// `parent` is the parent scope, or nullptr for a root scope.
+// `labels` is a list of labels that this scope is interested in. The scope's
+// labels of interest will be the union of its own labels and its parent's
+// labels.
+// `child_shards_count` and `storage_shards_count` are performance tuning
+// parameters for sharding internal data structures.
+RefCountedPtr<CollectionScope> CreateCollectionScope(
+    std::vector<RefCountedPtr<CollectionScope>> parents,
+    absl::Span<const std::string> labels, size_t child_shards_count = 1,
+    size_t storage_shards_count = 1);
+
+RefCountedPtr<CollectionScope> CreateRootCollectionScope(
+    absl::Span<const std::string> labels, size_t child_shards_count = 1,
+    size_t storage_shards_count = 1);
+
+RefCountedPtr<CollectionScope> GlobalCollectionScope();
 
 }  // namespace grpc_core