stats: add built-in log linear histogram support

bazel/external/libcircllhist.BUILD

@@ -0,0 +1,17 @@
+cc_library(
+    name = "libcircllhist",
+    srcs = ["src/circllhist.c"],
+    hdrs = [
+        "src/circllhist.h",
+        "src/circllhist_config.h",  # Generated.
+    ],
+    includes = ["src"],
+    visibility = ["//visibility:public"],
+)
+
+genrule(
+    name = "circllhist_config",
+    srcs = ["src/circllhist_config.h.in"],
+    outs = ["src/circllhist_config.h"],
+    cmd = "cp $< $@",
+)

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 = "bb73e93ba23b5746ea15d95c21ee8536168c486c",  # 2018-03-18
+        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

@@ -263,6 +263,11 @@ class Store : public Scope {
    * @return a list of all known gauges.
    */
   virtual std::list<GaugeSharedPtr> gauges() const PURE;
+
+  virtual std::list<HistogramSharedPtr> histograms() const {
+    std::list<HistogramSharedPtr> empty_list;
+    return empty_list;
+  }
 };
 
 typedef std::unique_ptr<Store> StorePtr;
@@ -294,6 +299,8 @@ class StoreRoot : public Store {
    * down.
    */
   virtual void shutdownThreading() PURE;
+
+  virtual void mergeHistograms() {}
 };
 
 typedef std::unique_ptr<StoreRoot> StoreRootPtr;

source/common/stats/BUILD

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

source/common/stats/stats_impl.h

@@ -23,6 +23,10 @@
 
 #include "absl/strings/string_view.h"
 
+extern "C" {
+#include <circllhist.h>
+}
+
 namespace Envoy {
 namespace Stats {
 
@@ -369,6 +373,128 @@ class HistogramImpl : public Histogram, public MetricImpl {
   Store& parent_;
 };
 
+/**
+ * Structure to hold statistical data of histogram.
+ */
+struct HistogramStatistics {
+public:
+  HistogramStatistics(histogram_t* histogram_ptr) {
+    double quantile_in[] = {0, 0.25, 0.5, 0.75, 0.90, 0.95, 0.99, 0.999, 1};
+    hist_approx_quantile(histogram_ptr, quantile_in, ARRAY_SIZE(quantile_in), quantile_out_);
+  }
+
+  std::string summary() const {
+    return fmt::format("P0: {} , P25: {}, P50: {}, P75: {}, P90: {}, P95: {}, P99: {}, P100: {}",
+                       quantile_out_[0], quantile_out_[1], quantile_out_[2], quantile_out_[3],
+                       quantile_out_[4], quantile_out_[5], quantile_out_[6], quantile_out_[7],
+                       quantile_out_[8]);
+  }
+
+private:
+  double quantile_out_[9];
+};
+
+/**
+ * Log Linear Histogram implementation per thread.
+ */
+class ThreadLocalHistogramImpl : public Histogram, public MetricImpl {
+public:
+  ThreadLocalHistogramImpl(const std::string& name, Store& parent, std::string&& tag_extracted_name,
+                           std::vector<Tag>&& tags)
+      : MetricImpl(name, std::move(tag_extracted_name), std::move(tags)), parent_(parent) {
+    histograms_[0] = hist_alloc();
+    histograms_[1] = hist_alloc();
+    current_active_ = 0;
+  }
+
+  ~ThreadLocalHistogramImpl() {
+    hist_free(histograms_[0]);
+    hist_free(histograms_[1]);
+  }
+  // Stats::Histogram
+  void recordValue(uint64_t value) override {
+    hist_insert_intscale(histograms_[current_active_], value, 0, 1);
+    parent_.deliverHistogramToSinks(*this, value);
+  }
+
+  void beginMerge() {
+    if (current_active_ == 0) {
+      current_active_ = 1;
+    } else {
+      current_active_ = 0;
+    }
+  }
+
+  void merge(histogram_t* target) {
+    histogram_t* hist_array[1];
+    if (current_active_ == 0) {
+      hist_array[0] = histograms_[1];
+    } else {
+      hist_array[0] = histograms_[0];
+    }
+    hist_accumulate(target, hist_array, 1);
+    hist_clear(hist_array[0]);
+  }
+
+  Store& parent_;
+  int current_active_;
+  histogram_t* histograms_[2];
+};
+
+typedef std::shared_ptr<ThreadLocalHistogramImpl> TlsHistogramSharedPtr;
+
+/**
+ * Log Linear Histogram implementation that is stored in the main thread.
+ */
+class HistogramParentImpl : public Histogram, public MetricImpl {
+public:
+  HistogramParentImpl(const std::string& name, Store& parent, std::string&& tag_extracted_name,
+                      std::vector<Tag>&& tags)
+      : MetricImpl(name, std::move(tag_extracted_name), std::move(tags)), parent_(parent) {
+    interval_histogram_ = hist_alloc();
+    cumulative_histogram_ = hist_alloc();
+  }
+
+  ~HistogramParentImpl() {
+    hist_free(interval_histogram_);
+    hist_free(cumulative_histogram_);
+  }
+
+  // Stats::Histogram
+  void recordValue(uint64_t) override {}
+
+  void addTlsHistogram(HistogramSharedPtr hist_ptr) { tls_histograms_.emplace_back(hist_ptr); }
+
+  void merge() {
+    hist_clear(interval_histogram_);
+    for (auto tls_histogram : tls_histograms_) {
+      TlsHistogramSharedPtr tls_histogram_ptr =
+          std::dynamic_pointer_cast<ThreadLocalHistogramImpl>(tls_histogram);
+      tls_histogram_ptr->merge(interval_histogram_);
+    }
+    histogram_t* hist_array[1];
+    hist_array[0] = interval_histogram_;
+    hist_accumulate(cumulative_histogram_, hist_array, 1);
+  }
+
+  HistogramStatistics getIntervalHistogramStatistics() {
+    HistogramStatistics interval_histogram(interval_histogram_);
+    return interval_histogram;
+  }
+
+  HistogramStatistics getCumulativieHistogramStatistics() {
+    HistogramStatistics cumulative_histogram(cumulative_histogram_);
+    return cumulative_histogram_;
+  }
+
+  Store& parent_;
+  std::list<HistogramSharedPtr> tls_histograms_;
+  histogram_t* interval_histogram_;
+  histogram_t* cumulative_histogram_;
+};
+
+typedef std::shared_ptr<HistogramParentImpl> ParentHistogramSharedPtr;
+
 /**
  * Implementation of RawStatDataAllocator that just allocates a new structure in memory and returns
  * it.

source/common/stats/thread_local_store.cc

@@ -61,6 +61,22 @@ std::list<GaugeSharedPtr> ThreadLocalStoreImpl::gauges() const {
   return ret;
 }
 
+std::list<HistogramSharedPtr> ThreadLocalStoreImpl::histograms() const {
+  // Handle de-dup due to overlapping scopes.
+  std::list<HistogramSharedPtr> ret;
+  std::unordered_set<std::string> names;
+  std::unique_lock<std::mutex> lock(lock_);
+  for (ScopeImpl* scope : scopes_) {
+    for (auto histogram : scope->central_cache_.histograms_) {
+      if (names.insert(histogram.first).second) {
+        ret.push_back(histogram.second);
+      }
+    }
+  }
+
+  return ret;
+}
+
 void ThreadLocalStoreImpl::initializeThreading(Event::Dispatcher& main_thread_dispatcher,
                                                ThreadLocal::Instance& tls) {
   main_thread_dispatcher_ = &main_thread_dispatcher;
@@ -75,6 +91,36 @@ void ThreadLocalStoreImpl::shutdownThreading() {
   shutting_down_ = true;
 }
 
+void ThreadLocalStoreImpl::mergeHistograms() {
+  if (!shutting_down_) {
+    std::unique_lock<std::mutex> lock(lock_);
+    // TODO: Wait till all threads have been checked-in
+    tls_->runOnAllThreads([this]() -> void {
+      for (ScopeImpl* scope : scopes_) {
+        for (auto histogram : tls_->getTyped<TlsCache>().scope_cache_[scope].histograms_) {
+          TlsHistogramSharedPtr tls_histogram_ptr =
+              std::dynamic_pointer_cast<ThreadLocalHistogramImpl>(histogram.second);
+          tls_histogram_ptr->beginMerge();
+        }
+      }
+    });
+    if (main_thread_dispatcher_) {
+      main_thread_dispatcher_->post([this]() -> void { mergeInternal(); });
+    }
+  }
+}
+
+void ThreadLocalStoreImpl::mergeInternal() {
+  std::unique_lock<std::mutex> lock(lock_);
+  for (ScopeImpl* scope : scopes_) {
+    for (auto histogram : scope->central_cache_.histograms_) {
+      ParentHistogramSharedPtr parent_hist_ptr =
+          std::dynamic_pointer_cast<HistogramParentImpl>(histogram.second);
+      parent_hist_ptr->merge();
+    }
+  }
+}
+
 void ThreadLocalStoreImpl::releaseScopeCrossThread(ScopeImpl* scope) {
   std::unique_lock<std::mutex> lock(lock_);
   ASSERT(scopes_.count(scope) == 1);
@@ -215,18 +261,22 @@ Histogram& ThreadLocalStoreImpl::ScopeImpl::histogram(const std::string& name) {
 
   std::unique_lock<std::mutex> lock(parent_.lock_);
   HistogramSharedPtr& central_ref = central_cache_.histograms_[final_name];
+
+  std::vector<Tag> tags;
+  std::string tag_extracted_name = parent_.getTagsForName(final_name, tags);
   if (!central_ref) {
-    std::vector<Tag> tags;
-    std::string tag_extracted_name = parent_.getTagsForName(final_name, tags);
-    central_ref.reset(
-        new HistogramImpl(final_name, parent_, std::move(tag_extracted_name), std::move(tags)));
+    central_ref.reset(new HistogramParentImpl(final_name, parent_, std::move(tag_extracted_name),
+                                              std::move(tags)));
   }
+  HistogramSharedPtr hist_tls_ptr;
+  hist_tls_ptr.reset(new ThreadLocalHistogramImpl(final_name, parent_,
+                                                  std::move(tag_extracted_name), std::move(tags)));
+  dynamic_cast<HistogramParentImpl&>(*central_ref).addTlsHistogram(hist_tls_ptr);
 
   if (tls_ref) {
-    *tls_ref = central_ref;
+    *tls_ref = hist_tls_ptr;
   }
-
-  return *central_ref;
+  return *hist_tls_ptr;
 }
 
 } // namespace Stats

source/common/stats/thread_local_store.h

@@ -64,6 +64,7 @@ class ThreadLocalStoreImpl : public StoreRoot {
   // Stats::Store
   std::list<CounterSharedPtr> counters() const override;
   std::list<GaugeSharedPtr> gauges() const override;
+  std::list<HistogramSharedPtr> histograms() const override;
 
   // Stats::StoreRoot
   void addSink(Sink& sink) override { timer_sinks_.push_back(sink); }
@@ -74,6 +75,10 @@ class ThreadLocalStoreImpl : public StoreRoot {
                            ThreadLocal::Instance& tls) override;
   void shutdownThreading() override;
 
+  void mergeHistograms() override;
+
+  void mergeInternal();
+
 private:
   struct TlsCacheEntry {
     std::unordered_map<std::string, CounterSharedPtr> counters_;

source/server/http/admin.cc

@@ -36,6 +36,7 @@
 #include "common/network/listen_socket_impl.h"
 #include "common/profiler/profiler.h"
 #include "common/router/config_impl.h"
+#include "common/stats/stats_impl.h"
 #include "common/upstream/host_utility.h"
 
 #include "absl/strings/str_replace.h"
@@ -392,6 +393,7 @@ Http::Code AdminImpl::handlerStats(absl::string_view url, Http::HeaderMap& respo
   Http::Code rc = Http::Code::OK;
   const Http::Utility::QueryParams params = Http::Utility::parseQueryString(url);
   std::map<std::string, uint64_t> all_stats;
+  std::map<std::string, std::string> all_histograms;
   for (const Stats::CounterSharedPtr& counter : server_.stats().counters()) {
     all_stats.emplace(counter->name(), counter->value());
   }
@@ -400,11 +402,24 @@ Http::Code AdminImpl::handlerStats(absl::string_view url, Http::HeaderMap& respo
     all_stats.emplace(gauge->name(), gauge->value());
   }
 
+  for (const Stats::HistogramSharedPtr& histogram : server_.stats().histograms()) {
+    Stats::ParentHistogramSharedPtr parent_hist_ptr =
+        std::dynamic_pointer_cast<Stats::HistogramParentImpl>(histogram);
+    all_histograms.emplace(
+        parent_hist_ptr->name(),
+        fmt::format("\n \t Interval:   {} \n \t Cumulative: {}",
+                    parent_hist_ptr->getIntervalHistogramStatistics().summary(),
+                    parent_hist_ptr->getCumulativieHistogramStatistics().summary()));
+  }
+
   if (params.size() == 0) {
     // No Arguments so use the standard.
     for (auto stat : all_stats) {
       response.add(fmt::format("{}: {}\n", stat.first, stat.second));
     }
+    for (auto histogram : all_histograms) {
+      response.add(fmt::format("{}: {}\n", histogram.first, histogram.second));
+    }
   } else {
     const std::string format_key = params.begin()->first;
     const std::string format_value = params.begin()->second;

source/server/server.cc

@@ -139,6 +139,7 @@ void InstanceImpl::flushStats() {
   server_stats_->days_until_first_cert_expiring_.set(
       sslContextManager().daysUntilFirstCertExpires());
 
+  stats_store_.mergeHistograms();
   InstanceUtil::flushCountersAndGaugesToSinks(config_->statsSinks(), stats_store_);
   stat_flush_timer_->enableTimer(config_->statsFlushInterval());
 }