stats: add ability to view histogram buckets to the /stats endpoint

docs/root/operations/admin.rst

@@ -444,6 +444,13 @@ modify different aspects of the server:
   Full-string matching can be specified with begin- and end-line anchors. (i.e.
   ``/stats?filter=^server.concurrency$``)
 
+  .. http:get:: /stats?histogram_buckets
+
+  Changes histogram output to display buckets with upper bounds (e.g. B0.5, B1, B5, ...).
+  The output for each bucket will be in the form of (interval,cumulative) (e.g. B0.5(0,0)).
+  Buckets do not include values from other buckets with smaller upper bounds;
+  the previous bucket's upper bound acts as a lower bound. Compatible with ``usedonly`` and ``filter``.
+
 .. http:get:: /stats?format=json
 
   Outputs /stats in JSON format. This can be used for programmatic access of stats. Counters and Gauges

docs/root/version_history/current.rst

@@ -29,6 +29,7 @@ Removed Config or Runtime
 New Features
 ------------
 * http3: downstream HTTP/3 support is now GA! Upstream HTTP/3 also GA for specific deployments. See :ref:`here <arch_overview_http3>` for details.
+* stats: histogram_buckets query parameter added to plain text stats to change histogram output to show buckets.
 
 
 Deprecated

envoy/stats/histogram.h

@@ -69,6 +69,12 @@ class HistogramStatistics {
    */
   virtual const std::vector<uint64_t>& computedBuckets() const PURE;
 
+  /**
+   * Returns nonoverlapping version of computedBuckets(). This vector is
+   * guaranteed to be the same length as supportedBuckets().
+   */
+  virtual const std::vector<uint64_t> nonoverlappingComputedBuckets() const PURE;
+
   /**
    * Returns number of values during the period. This number may be an approximation
    * of the number of samples in the histogram, it is not guaranteed that this will be
@@ -161,6 +167,11 @@ class ParentHistogram : public Histogram {
    * Returns the bucket summary representation.
    */
   virtual const std::string bucketSummary() const PURE;
+
+  /**
+   * Returns the bucket summary representation with nonoverlapping buckets.
+   */
+  virtual const std::string nonoverlappingBucketSummary() const PURE;
 };
 
 using ParentHistogramSharedPtr = RefcountPtr<ParentHistogram>;

source/common/stats/histogram_impl.cc

@@ -31,6 +31,18 @@ const std::vector<double>& HistogramStatisticsImpl::supportedQuantiles() const {
                          {0, 0.25, 0.5, 0.75, 0.90, 0.95, 0.99, 0.995, 0.999, 1});
 }
 
+const std::vector<uint64_t> HistogramStatisticsImpl::nonoverlappingComputedBuckets() const {
+  std::vector<uint64_t> buckets;
+  buckets.reserve(computed_buckets_.size());
+  uint64_t previous_computed_bucket = 0;
+  for (size_t i = 0; i < computed_buckets_.size(); ++i) {
+    uint64_t current_computed_bucket = computed_buckets_[i];
+    buckets.push_back(current_computed_bucket - previous_computed_bucket);
+    previous_computed_bucket = current_computed_bucket;
+  }
+  return buckets;
+}
+
 std::string HistogramStatisticsImpl::quantileSummary() const {
   std::vector<std::string> summary;
   const std::vector<double>& supported_quantiles = supportedQuantiles();

source/common/stats/histogram_impl.h

@@ -60,6 +60,7 @@ class HistogramStatisticsImpl final : public HistogramStatistics, NonCopyable {
   const std::vector<double>& computedQuantiles() const override { return computed_quantiles_; }
   ConstSupportedBuckets& supportedBuckets() const override { return supported_buckets_; }
   const std::vector<uint64_t>& computedBuckets() const override { return computed_buckets_; }
+  const std::vector<uint64_t> nonoverlappingComputedBuckets() const override;
   uint64_t sampleCount() const override { return sample_count_; }
   double sampleSum() const override { return sample_sum_; }
 

source/common/stats/thread_local_store.cc

@@ -940,6 +940,26 @@ const std::string ParentHistogramImpl::bucketSummary() const {
   }
 }
 
+const std::string ParentHistogramImpl::nonoverlappingBucketSummary() const {
+  if (used()) {
+    std::vector<std::string> bucket_summary;
+    ConstSupportedBuckets& supported_buckets = interval_statistics_.supportedBuckets();
+    const std::vector<uint64_t> nonoverlapping_interval_buckets =
+        interval_statistics_.nonoverlappingComputedBuckets();
+    const std::vector<uint64_t> nonoverlapping_cumulative_buckets =
+        cumulative_statistics_.nonoverlappingComputedBuckets();
+    bucket_summary.reserve(supported_buckets.size());
+    for (size_t i = 0; i < supported_buckets.size(); ++i) {
+      bucket_summary.push_back(fmt::format("B{:g}({},{})", supported_buckets[i],
+                                           nonoverlapping_interval_buckets[i],
+                                           nonoverlapping_cumulative_buckets[i]));
+    }
+    return absl::StrJoin(bucket_summary, " ");
+  } else {
+    return std::string("No recorded values");
+  }
+}
+
 void ParentHistogramImpl::addTlsHistogram(const TlsHistogramSharedPtr& hist_ptr) {
   Thread::LockGuard lock(merge_lock_);
   tls_histograms_.emplace_back(hist_ptr);

source/common/stats/thread_local_store.h

@@ -106,6 +106,7 @@ class ParentHistogramImpl : public MetricImpl<ParentHistogram> {
   }
   const std::string quantileSummary() const override;
   const std::string bucketSummary() const override;
+  const std::string nonoverlappingBucketSummary() const override;
 
   // Stats::Metric
   SymbolTable& symbolTable() override;

source/server/admin/stats_handler.cc

@@ -80,6 +80,7 @@ Http::Code StatsHandler::handlerStats(absl::string_view url,
   const Http::Utility::QueryParams params = Http::Utility::parseAndDecodeQueryString(url);
 
   const bool used_only = params.find("usedonly") != params.end();
+  const bool histogram_buckets = params.find("histogram_buckets") != params.end();
   absl::optional<std::regex> regex;
   if (!Utility::filterParam(params, response, regex)) {
     return Http::Code::BadRequest;
@@ -113,7 +114,8 @@ Http::Code StatsHandler::handlerStats(absl::string_view url,
 
   if (!format_value.has_value()) {
     // Display plain stats if format query param is not there.
-    statsAsText(all_stats, text_readouts, server_.stats().histograms(), used_only, regex, response);
+    statsAsText(all_stats, text_readouts, server_.stats().histograms(), used_only,
+                histogram_buckets, regex, response);
     return Http::Code::OK;
   }
 
@@ -174,7 +176,8 @@ Http::Code StatsHandler::handlerContention(absl::string_view,
 void StatsHandler::statsAsText(const std::map<std::string, uint64_t>& all_stats,
                                const std::map<std::string, std::string>& text_readouts,
                                const std::vector<Stats::ParentHistogramSharedPtr>& histograms,
-                               bool used_only, const absl::optional<std::regex>& regex,
+                               bool used_only, bool histogram_buckets,
+                               const absl::optional<std::regex>& regex,
                                Buffer::Instance& response) {
   // Display plain stats if format query param is not there.
   for (const auto& text_readout : text_readouts) {
@@ -187,8 +190,16 @@ void StatsHandler::statsAsText(const std::map<std::string, uint64_t>& all_stats,
   std::map<std::string, std::string> all_histograms;
   for (const Stats::ParentHistogramSharedPtr& histogram : histograms) {
     if (shouldShowMetric(*histogram, used_only, regex)) {
-      auto insert = all_histograms.emplace(histogram->name(), histogram->quantileSummary());
-      ASSERT(insert.second); // No duplicates expected.
+      bool success = false;
+      // Display summary of nonoverlapping buckets if histogram_buckets query parameter is found.
+      if (histogram_buckets) {
+        success =
+            all_histograms.emplace(histogram->name(), histogram->nonoverlappingBucketSummary())
+                .second;
+      } else {
+        success = all_histograms.emplace(histogram->name(), histogram->quantileSummary()).second;
+      }
+      ASSERT(success); // No duplicates expected.
     }
   }
   for (const auto& histogram : all_histograms) {

source/server/admin/stats_handler.h

@@ -66,7 +66,7 @@ class StatsHandler : public HandlerContextBase {
   void statsAsText(const std::map<std::string, uint64_t>& all_stats,
                    const std::map<std::string, std::string>& text_readouts,
                    const std::vector<Stats::ParentHistogramSharedPtr>& all_histograms,
-                   bool used_only, const absl::optional<std::regex>& regex,
+                   bool used_only, bool histogram_buckets, const absl::optional<std::regex>& regex,
                    Buffer::Instance& response);
 };
 

test/common/stats/thread_local_store_test.cc

@@ -1567,6 +1567,34 @@ TEST_F(HistogramTest, ParentHistogramBucketSummary) {
             parent_histogram->bucketSummary());
 }
 
+TEST_F(HistogramTest, ParentHistogramNonoverlappingBucketSummary) {
+  ScopePtr scope1 = store_->createScope("scope1.");
+  Histogram& histogram =
+      store_->histogramFromString("histogram", Stats::Histogram::Unit::Unspecified);
+  store_->mergeHistograms([]() -> void {});
+  ASSERT_EQ(1, store_->histograms().size());
+  ParentHistogramSharedPtr parent_histogram = store_->histograms()[0];
+  EXPECT_EQ("No recorded values", parent_histogram->nonoverlappingBucketSummary());
+
+  EXPECT_CALL(sink_, onHistogramComplete(Ref(histogram), 200));
+  histogram.recordValue(200);
+
+  EXPECT_CALL(sink_, onHistogramComplete(Ref(histogram), 300));
+  histogram.recordValue(300);
+
+  store_->mergeHistograms([]() -> void {});
+
+  EXPECT_CALL(sink_, onHistogramComplete(Ref(histogram), 300));
+  histogram.recordValue(300);
+
+  store_->mergeHistograms([]() -> void {});
+
+  EXPECT_EQ("B0.5(0,0) B1(0,0) B5(0,0) B10(0,0) B25(0,0) B50(0,0) B100(0,0) B250(0,1) B500(1,2) "
+            "B1000(0,0) B2500(0,0) B5000(0,0) B10000(0,0) B30000(0,0) B60000(0,0) B300000(0,0) "
+            "B600000(0,0) B1.8e+06(0,0) B3.6e+06(0,0)",
+            parent_histogram->nonoverlappingBucketSummary());
+}
+
 class ThreadLocalRealThreadsTestBase : public Thread::RealThreadsTestHelper,
                                        public ThreadLocalStoreNoMocksTestBase {
 protected:

test/mocks/stats/mocks.h

@@ -201,6 +201,7 @@ class MockParentHistogram : public MockMetric<ParentHistogram> {
   void merge() override {}
   const std::string quantileSummary() const override { return ""; };
   const std::string bucketSummary() const override { return ""; };
+  const std::string nonoverlappingBucketSummary() const override { return ""; };
 
   MOCK_METHOD(bool, used, (), (const));
   MOCK_METHOD(Histogram::Unit, unit, (), (const));

test/server/admin/stats_handler_test.cc

@@ -133,6 +133,36 @@ TEST_P(AdminStatsTest, HandlerStatsPlainText) {
   shutdownThreading();
 }
 
+TEST_P(AdminStatsTest, HandlerStatsPlainTextHistogramBuckets) {
+  const std::string url = "/stats?histogram_buckets";
+  Http::TestResponseHeaderMapImpl response_headers;
+  Buffer::OwnedImpl data;
+  MockAdminStream admin_stream;
+  Configuration::MockStatsConfig stats_config;
+  EXPECT_CALL(stats_config, flushOnAdmin()).WillRepeatedly(testing::Return(false));
+  MockInstance instance;
+  store_->initializeThreading(main_thread_dispatcher_, tls_);
+  EXPECT_CALL(instance, stats()).WillRepeatedly(testing::ReturnRef(*store_));
+  EXPECT_CALL(instance, statsConfig()).WillRepeatedly(testing::ReturnRef(stats_config));
+  StatsHandler handler(instance);
+
+  Stats::Histogram& h1 = store_->histogramFromString("h1", Stats::Histogram::Unit::Unspecified);
+
+  EXPECT_CALL(sink_, onHistogramComplete(Ref(h1), 200));
+  h1.recordValue(200);
+
+  store_->mergeHistograms([]() -> void {});
+
+  Http::Code code = handler.handlerStats(url, response_headers, data, admin_stream);
+  EXPECT_EQ(Http::Code::OK, code);
+  EXPECT_EQ("h1: B0.5(0,0) B1(0,0) B5(0,0) B10(0,0) B25(0,0) B50(0,0) B100(0,0) B250(1,1) "
+            "B500(0,0) B1000(0,0) B2500(0,0) B5000(0,0) B10000(0,0) B30000(0,0) B60000(0,0) "
+            "B300000(0,0) B600000(0,0) B1.8e+06(0,0) B3.6e+06(0,0)\n",
+            data.toString());
+
+  shutdownThreading();
+}
+
 TEST_P(AdminStatsTest, HandlerStatsJson) {
   const std::string url = "/stats?format=json";
   Http::TestResponseHeaderMapImpl response_headers;