stats: add built-in log linear histogram support

bazel/external/libcircllhist.BUILD

@@ -0,0 +1,9 @@
+cc_library(
+    name = "libcircllhist",
+    srcs = ["src/circllhist.c"],
+    hdrs = [
+        "src/circllhist.h",
+    ],
+    includes = ["src"],
+    visibility = ["//visibility:public"],
+)

bazel/repositories.bzl

@@ -177,6 +177,7 @@ def envoy_dependencies(path = "@envoy_deps//", skip_targets = []):
     _boringssl()
     _com_google_absl()
     _com_github_bombela_backward()
+    _com_github_circonus_labs_libcircllhist()
     _com_github_cyan4973_xxhash()
     _com_github_eile_tclap()
     _com_github_fmtlib_fmt()
@@ -215,6 +216,16 @@ def _com_github_bombela_backward():
         actual = "@com_github_bombela_backward//:backward",
     )
 
+def _com_github_circonus_labs_libcircllhist():
+    _repository_impl(
+        name = "com_github_circonus_labs_libcircllhist",
+        build_file = "@envoy//bazel/external:libcircllhist.BUILD",
+    )
+    native.bind(
+        name = "libcircllhist",
+        actual = "@com_github_circonus_labs_libcircllhist//:libcircllhist",
+    )
+
 def _com_github_cyan4973_xxhash():
     _repository_impl(
         name = "com_github_cyan4973_xxhash",

bazel/repository_locations.bzl

@@ -12,6 +12,10 @@ REPOSITORY_LOCATIONS = dict(
         commit = "44ae9609e860e3428cd057f7052e505b4819eb84",  # 2018-02-06
         remote = "https://github.com/bombela/backward-cpp",
     ),
+    com_github_circonus_labs_libcircllhist = dict(
+        commit = "eea8653b7e5abd8b5f2701e20e0334802f6d2dfb",  # 2018-04-05
+        remote = "https://github.com/circonus-labs/libcircllhist",
+    ),
     com_github_cyan4973_xxhash = dict(
         commit = "7caf8bd76440c75dfe1070d3acfbd7891aea8fca",  # v0.6.4
         remote = "https://github.com/Cyan4973/xxHash",

include/envoy/stats/stats.h

@@ -2,6 +2,7 @@
 
 #include <chrono>
 #include <cstdint>
+#include <functional>
 #include <list>
 #include <memory>
 #include <string>
@@ -114,6 +115,11 @@ class Metric {
    * Returns the name of the Metric with the portions designated as tags removed.
    */
   virtual const std::string& tagExtractedName() const PURE;
+
+  /**
+   * Indicates whether a metric has been used.
+   */
+  virtual bool used() const PURE;
 };
 
 /**
@@ -128,7 +134,6 @@ class Counter : public virtual Metric {
   virtual void inc() PURE;
   virtual uint64_t latch() PURE;
   virtual void reset() PURE;
-  virtual bool used() const PURE;
   virtual uint64_t value() const PURE;
 };
 
@@ -146,12 +151,34 @@ class Gauge : public virtual Metric {
   virtual void inc() PURE;
   virtual void set(uint64_t value) PURE;
   virtual void sub(uint64_t amount) PURE;
-  virtual bool used() const PURE;
   virtual uint64_t value() const PURE;
 };
 
 typedef std::shared_ptr<Gauge> GaugeSharedPtr;
 
+/**
+ * Holds the computed statistics for a histogram.
+ */
+class HistogramStatistics {
+public:
+  virtual ~HistogramStatistics() {}
+
+  /**
+   * Returns summary representation of the histogram.
+   */
+  virtual std::string summary() const PURE;
+
+  /**
+   * Returns supported quantiles.
+   */
+  virtual const std::vector<double>& supportedQuantiles() const PURE;
+
+  /**
+   * Returns computed quantile values during the period.
+   */
+  virtual const std::vector<double>& computedQuantiles() const PURE;
+};
+
 /**
  * A histogram that records values one at a time.
  * Note: Histograms now incorporate what used to be timers because the only difference between the
@@ -167,6 +194,21 @@ class Histogram : public virtual Metric {
    * Records an unsigned value. If a timer, values are in units of milliseconds.
    */
   virtual void recordValue(uint64_t value) PURE;
+
+  /**
+   * Merges the histogram values collected during the flush interval.
+   */
+  virtual void merge() PURE;
+
+  /**
+   * Returns the interval histogram summary statistics for the flush interval.
+   */
+  virtual const HistogramStatistics& intervalStatistics() const PURE;
+
+  /**
+   * Returns the cumulative histogram summary statistics.
+   */
+  virtual const HistogramStatistics& cumulativeStatistics() const PURE;
 };
 
 typedef std::shared_ptr<Histogram> HistogramSharedPtr;
@@ -194,6 +236,11 @@ class Sink {
    */
   virtual void flushGauge(const Gauge& gauge, uint64_t value) PURE;
 
+  /**
+   * Flush a histogram.
+   */
+  virtual void flushHistogram(const Histogram& histogram) PURE;
+
   /**
    * This will be called after beginFlush(), some number of flushCounter(), and some number of
    * flushGauge(). Sinks can use this to optimize writing if desired.
@@ -263,10 +310,20 @@ class Store : public Scope {
    * @return a list of all known gauges.
    */
   virtual std::list<GaugeSharedPtr> gauges() const PURE;
+
+  /**
+   * @return a list of all known histograms.
+   */
+  virtual std::list<HistogramSharedPtr> histograms() const PURE;
 };
 
 typedef std::unique_ptr<Store> StorePtr;
 
+/**
+ * Callback invoked when a store's mergeHistogram() runs.
+ */
+typedef std::function<void()> PostMergeCb;
+
 /**
  * The root of the stat store.
  */
@@ -294,6 +351,12 @@ class StoreRoot : public Store {
    * down.
    */
   virtual void shutdownThreading() PURE;
+
+  /**
+   * Called during the flush process to merge all the thread local histograms. The passed in
+   * callback will be called on the main thread, but it will happen after the method returns.
+   */
+  virtual void mergeHistograms(PostMergeCb merge_complete_cb) PURE;
 };
 
 typedef std::unique_ptr<StoreRoot> StoreRootPtr;

include/envoy/thread_local/thread_local.h

@@ -46,6 +46,16 @@ class Slot {
    */
   virtual void runOnAllThreads(Event::PostCb cb) PURE;
 
+  /**
+   * Run a callback on all registered threads with a barrier. A shutdown initiated during the
+   * running of the PostCBs may prevent all_threads_complete_cb from being called.
+   * @param cb supplies the callback to run on each thread.
+   * @param all_threads_complete_cb supplies the callback to run on main thread after threads are
+   * done.
+   */
+  virtual void runOnAllThreadsWithBarrier(Event::PostCb cb,
+                                          Event::PostCb all_threads_complete_cb) PURE;
+
   /**
    * Set thread local data on all threads previously registered via registerThread().
    * @param initializeCb supplies the functor that will be called *on each thread*. The functor

source/common/stats/BUILD

@@ -12,6 +12,10 @@ envoy_cc_library(
     name = "stats_lib",
     srcs = ["stats_impl.cc"],
     hdrs = ["stats_impl.h"],
+    external_deps = [
+        "abseil_optional",
+        "libcircllhist",
+    ],
     deps = [
         "//include/envoy/common:time_interface",
         "//include/envoy/server:options_interface",

source/common/stats/stats_impl.h

@@ -21,7 +21,9 @@
 #include "common/common/utility.h"
 #include "common/protobuf/protobuf.h"
 
+#include "absl/strings/str_join.h"
 #include "absl/strings/string_view.h"
+#include "circllhist.h"
 
 namespace Envoy {
 namespace Stats {
@@ -167,9 +169,6 @@ class Utility {
  * RawStatData::size() instead.
  */
 struct RawStatData {
-  struct Flags {
-    static const uint8_t Used = 0x1;
-  };
 
   /**
    * Due to the flexible-array-length of name_, c-style allocation
@@ -284,6 +283,14 @@ class MetricImpl : public virtual Metric {
   const std::string& tagExtractedName() const override { return tag_extracted_name_; }
   const std::vector<Tag>& tags() const override { return tags_; }
 
+protected:
+  /**
+   * Flags used by all stats types to figure out whether they have been used.
+   */
+  struct Flags {
+    static const uint8_t Used = 0x1;
+  };
+
 private:
   const std::string name_;
   const std::string tag_extracted_name_;
@@ -305,13 +312,13 @@ class CounterImpl : public Counter, public MetricImpl {
   void add(uint64_t amount) override {
     data_.value_ += amount;
     data_.pending_increment_ += amount;
-    data_.flags_ |= RawStatData::Flags::Used;
+    data_.flags_ |= Flags::Used;
   }
 
   void inc() override { add(1); }
   uint64_t latch() override { return data_.pending_increment_.exchange(0); }
   void reset() override { data_.value_ = 0; }
-  bool used() const override { return data_.flags_ & RawStatData::Flags::Used; }
+  bool used() const override { return data_.flags_ & Flags::Used; }
   uint64_t value() const override { return data_.value_; }
 
 private:
@@ -333,27 +340,71 @@ class GaugeImpl : public Gauge, public MetricImpl {
   // Stats::Gauge
   virtual void add(uint64_t amount) override {
     data_.value_ += amount;
-    data_.flags_ |= RawStatData::Flags::Used;
+    data_.flags_ |= Flags::Used;
   }
   virtual void dec() override { sub(1); }
   virtual void inc() override { add(1); }
   virtual void set(uint64_t value) override {
     data_.value_ = value;
-    data_.flags_ |= RawStatData::Flags::Used;
+    data_.flags_ |= Flags::Used;
   }
   virtual void sub(uint64_t amount) override {
     ASSERT(data_.value_ >= amount);
     ASSERT(used());
     data_.value_ -= amount;
   }
   virtual uint64_t value() const override { return data_.value_; }
-  bool used() const override { return data_.flags_ & RawStatData::Flags::Used; }
+  bool used() const override { return data_.flags_ & Flags::Used; }
 
 private:
   RawStatData& data_;
   RawStatDataAllocator& alloc_;
 };
 
+/**
+ * Implementation of HistogramStatistics for circllhist.
+ */
+class HistogramStatisticsImpl : public HistogramStatistics {
+public:
+  HistogramStatisticsImpl() : computed_quantiles_(supported_quantiles_.size(), 0.0) {}
+
+  HistogramStatisticsImpl(histogram_t* histogram_ptr)
+      : computed_quantiles_(supported_quantiles_.size(), 0.0) {
+    hist_approx_quantile(histogram_ptr, supported_quantiles_.data(), supported_quantiles_.size(),
+                         computed_quantiles_.data());
+  }
+
+  HistogramStatisticsImpl(const HistogramStatisticsImpl&) = delete;
+  HistogramStatisticsImpl& operator=(HistogramStatisticsImpl const&) = delete;
+
+  std::string summary() const override {
+    std::vector<std::string> summary;
+    for (size_t i = 0; i < supported_quantiles_.size(); ++i) {
+      summary.push_back(
+          fmt::format("P{}: {}", 100 * supported_quantiles_[i],
+                      std::isnan(computed_quantiles_[i]) ? 0 : computed_quantiles_[i]));
+    }
+    return absl::StrJoin(summary, ", ");
+  }
+
+  const std::vector<double>& supportedQuantiles() const override { return supported_quantiles_; }
+
+  const std::vector<double>& computedQuantiles() const override { return computed_quantiles_; }
+
+  /**
+   * Clears the old computed values and refreshes it with values computed from passed histogram.
+   */
+  void refresh(histogram_t* new_histogram_ptr) {
+    computed_quantiles_.clear();
+    hist_approx_quantile(new_histogram_ptr, supported_quantiles_.data(),
+                         supported_quantiles_.size(), computed_quantiles_.data());
+  }
+
+private:
+  const std::vector<double> supported_quantiles_ = {0, 0.25, 0.5, 0.75, 0.90, 0.95, 0.99, 0.999, 1};
+  std::vector<double> computed_quantiles_;
+};
+
 /**
  * Histogram implementation for the heap.
  */
@@ -366,7 +417,21 @@ class HistogramImpl : public Histogram, public MetricImpl {
   // Stats::Histogram
   void recordValue(uint64_t value) override { parent_.deliverHistogramToSinks(*this, value); }
 
+  void merge() override {}
+
+  bool used() const override { return true; }
+
+  const HistogramStatistics& intervalStatistics() const override { return interval_statistics_; }
+
+  const HistogramStatistics& cumulativeStatistics() const override {
+    return cumulative_statistics_;
+  }
+
   Store& parent_;
+
+private:
+  HistogramStatisticsImpl interval_statistics_;
+  HistogramStatisticsImpl cumulative_statistics_;
 };
 
 /**
@@ -446,6 +511,7 @@ class IsolatedStoreImpl : public Store {
   // Stats::Store
   std::list<CounterSharedPtr> counters() const override { return counters_.toList(); }
   std::list<GaugeSharedPtr> gauges() const override { return gauges_.toList(); }
+  std::list<HistogramSharedPtr> histograms() const override { return histograms_.toList(); }
 
 private:
   struct ScopeImpl : public Scope {