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 = "97ef5e088fd01fa8ec5a86334a6308ac0d51ea6f",  # 2018-04-07
+        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 this metric has been updated since the server was started.
+   */
+  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
@@ -171,6 +198,60 @@ class Histogram : public virtual Metric {
 
 typedef std::shared_ptr<Histogram> HistogramSharedPtr;
 
+/**
+ * A histogram that is stored in TLS and used to record values per thread. This holds two
+ * histograms, one to collect the values and other as backup that is used for merge process. The
+ * swap happens during the merge process.
+ */
+class ThreadLocalHistogram : public virtual Histogram {
+public:
+  virtual ~ThreadLocalHistogram() {}
+
+  /**
+   * Called in the beginning of merge process. Swaps the histogram used for collection so that we do
+   * not have to lock the histogram in high throughput TLS writes.
+   */
+  virtual void beginMerge() PURE;
+};
+
+class ThreadLocalHistogramImpl;
+
+typedef std::shared_ptr<ThreadLocalHistogramImpl> TlsHistogramSharedPtr;
+
+/**
+ * A histogram that is stored in main thread, manages all thread local histograms and provides
+ * summary view of the histogram.
+ */
+class ParentHistogram : public virtual Metric {
+public:
+  virtual ~ParentHistogram() {}
+
+  /**
+   * This method is called during the main stats flush process for each of the histogram. This
+   * method iterates through the Tls histograms and collects the histogram data of all of them
+   * in to "interval_histogram_". Then the collected "interval_histogram_" is merged to a
+   * "cumulative_histogram".
+   */
+  virtual void merge() PURE;
+
+  /**
+   * This is used to keep track of all worker thread local histograms.
+   */
+  virtual void addTlsHistogram(TlsHistogramSharedPtr hist_ptr) 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<ParentHistogram> ParentHistogramSharedPtr;
+
 /**
  * A sink for stats. Each sink is responsible for writing stats to a backing store.
  */
@@ -194,6 +275,11 @@ class Sink {
    */
   virtual void flushGauge(const Gauge& gauge, uint64_t value) PURE;
 
+  /**
+   * Flush a histogram.
+   */
+  virtual void flushHistogram(const ParentHistogram& 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 +349,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<ParentHistogramSharedPtr> 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 +390,14 @@ 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
+   * which means that the actual flush process will happen on the main thread after this 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,15 @@ 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 runOnAllThreads(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/common/logger.h

@@ -42,7 +42,9 @@ namespace Logger {
   FUNCTION(testing)              \
   FUNCTION(tracing)              \
   FUNCTION(upstream)             \
-  FUNCTION(grpc)
+  FUNCTION(grpc)                 \
+  FUNCTION(stats)
+
 
 enum class Id {
   ALL_LOGGER_IDS(GENERATE_ENUM)

source/common/stats/BUILD

@@ -12,12 +12,17 @@ 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",
         "//include/envoy/stats:stats_interface",
         "//source/common/common:assert_lib",
         "//source/common/common:hash_lib",
+        "//source/common/common:non_copyable",
         "//source/common/common:perf_annotation_lib",
         "//source/common/common:utility_lib",
         "//source/common/config:well_known_names",

source/common/stats/stats_impl.cc

@@ -273,5 +273,32 @@ void RawStatData::initialize(absl::string_view key) {
   name_[xfer_size] = '\0';
 }
 
+const std::vector<double> HistogramStatisticsImpl::supported_quantiles_ = {
+    0, 0.25, 0.5, 0.75, 0.90, 0.95, 0.99, 0.999, 1};
+
+HistogramStatisticsImpl::HistogramStatisticsImpl(const 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());
+}
+
+std::string HistogramStatisticsImpl::summary() const {
+  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], computed_quantiles_[i]));
+  }
+  return absl::StrJoin(summary, ", ");
+}
+
+/**
+ * Clears the old computed values and refreshes it with values computed from passed histogram.
+ */
+void HistogramStatisticsImpl::refresh(const histogram_t* new_histogram_ptr) {
+  computed_quantiles_.clear();
+  hist_approx_quantile(new_histogram_ptr, supported_quantiles_.data(), supported_quantiles_.size(),
+                       computed_quantiles_.data());
+}
+
 } // namespace Stats
 } // namespace Envoy