hphp/util/service-data.h

   1 /*
   2    +----------------------------------------------------------------------+
   3    | HipHop for PHP                                                       |
   4    +----------------------------------------------------------------------+
   5    | Copyright (c) 2010-present Facebook, Inc. (http://www.facebook.com)  |
   6    +----------------------------------------------------------------------+
   7    | This source file is subject to version 3.01 of the PHP license,      |
   8    | that is bundled with this package in the file LICENSE, and is        |
   9    | available through the world-wide-web at the following url:           |
  10    | http://www.php.net/license/3_01.txt                                  |
  11    | If you did not receive a copy of the PHP license and are unable to   |
  12    | obtain it through the world-wide-web, please send a note to          |
  13    | license@php.net so we can mail you a copy immediately.               |
  14    +----------------------------------------------------------------------+
  15 */
  16
  17 #pragma once
  18
  19 #include <atomic>
  20 #include <chrono>
  21 #include <map>
  22 #include <string>
  23 #include <vector>
  24
  25 #include <folly/Synchronized.h>
  26 #include <folly/stats/Histogram.h>
  27 #include <folly/stats/MultiLevelTimeSeries.h>
  28
  29 #include "hphp/util/assertions.h"
  30 #include "hphp/util/optional.h"
  31
  32 namespace HPHP {
  33
  34 ///////////////////////////////////////////////////////////////////////////////
  35
  36 /*
  37  * A globally accessible statistics tracking facility. This can be used to keep
  38  * track of internal runtime statistics in the form of flat counters, timeseries
  39  * counters or histograms.
  40  *
  41  * ServiceData provides a globally accessible entry point to all the internal
  42  * statistics. A 'statistic counter' of different types could be created by
  43  * calling createCouter() createTimeSeries() or createHistogram(). The caller
  44  * can then add values at different time points to the statistic counters. The
  45  * statistic can then be retrieved and reported via the exportAll() call on
  46  * ServiceData.
  47  *
  48  * Thread safety:
  49  * ==============
  50  * All functions in ServiceData namespace are thread safe. It is safe
  51  * (and recommended) to cache the object returned by create...() methods and
  52  * repeatedly add data points to it. It is safe to call create...() with the
  53  * same name from multiple threads. In this case, only one object will be
  54  * created and passed back to different threads.
  55  *
  56  * All objects returned by returned by the various create...() calls are thread
  57  * safe. It is okay to add data points to it from multiple threads concurrently.
  58  * These objects are internally synchronized with spin locks.
  59  *
  60  * Example Usage:
  61  * ==============
  62  * // create a flat counter named foo.
  63  * auto counter = ServiceData::createCounter("foo");
  64  * counter->increment();
  65  *
  66  * // create timeseries data named bar with default setting (avg value for the
  67  * // last 1 minute, 10 minute, hour and all time).
  68  * auto timeseries = ServiceData::createTimeSeries("bar");
  69  * timeseries->addValue(3);
  70  *
  71  * // create a histogram with 10 buckets, min of 1, max of 100 and export the
  72  * // 50th and 90th percentile value for reporting.
  73  * auto histogram = ServiceData::createHistogram("blah", 10, 1, 100,
  74  *                                               {0.5, 0.9});
  75  * histogram->addValue(10);
  76  *
  77  * // You can report the data like so.
  78  * std::map<std::string, int64_t> statsMap;
  79  * ServiceData::exportAll(statsMap);
  80  *
  81  * and statsMap will contain these keys:
  82  *
  83  * "foo"
  84  * "bar.avg.60", "bar.avg.600", "bar.avg.3600", "bar.avg"
  85  * "blah.hist.p50", "blah.hist.p90"
  86  *
  87  * Anti pattern:
  88  * =============
  89  * ServiceData::createCounter("foo")->increment();  // don't do this.
  90  * Don't do this in performance critical code. You will incur the cost of a
  91  * std::map look up whenever createCounter() is called. Rather, you should call
  92  * ServiceData::createCounter("foo") just once, cache the returned pointer and
  93  * repeatedly adding data points to it.
  94  */
  95 namespace ServiceData {
  96
  97 struct ExportedCounter;
  98 struct ExportedHistogram;
  99 struct ExportedTimeSeries;
 100
 101 namespace detail {
 102 template <class ClassWithPrivateDestructor>
 103 struct FriendDeleter;
 104 };
 105
 106 enum class StatsType { AVG, SUM, RATE, COUNT, PCT };
 107
 108 /*
 109  * Create a flat counter named 'name'. Return an existing counter if it has
 110  * already been created.
 111  */
 112 ExportedCounter* createCounter(const std::string& name);
 113
 114 /*
 115  * Callback-based counters
 116  *
 117  * Some counters have values that are updated much more frequently than data is
 118  * requested from ServiceData, or there may not be a good location in the code
 119  * to periodically update the value. For these cases, a callback-based counter
 120  * may be used instead.
 121  *
 122  * registerCounterCallback() returns a unique handle that may be passed to
 123  * deregisterCounterCallback() if the callback should be deregistered.
 124  *
 125  * The CounterCallback struct is provided as a convenience wrapper to manage
 126  * the handle. The callback may be provided to its constructor, or to the
 127  * init() function, if the callback isn't safe to call at CounterCallback's
 128  * construction. Similarly, deinit() may be be called if the callback should be
 129  * deregistered before CounterCallback's destruction.
 130  *
 131  * Once registered, callbacks must be safe to call at any time, from any
 132  * thread, and may even be called before registerCounterCallback()
 133  * returns. Callbacks are passed a reference to the std::map<std::string,
 134  * int64_t> being populated, so one callback can add many counters (callbacks
 135  * can also remove or modify existing counters, but this is discouraged).
 136  */
 137 using CounterFunc = std::function<void(std::map<std::string, int64_t>&)>;
 138 using CounterHandle = uint32_t;
 139
 140 CounterHandle registerCounterCallback(CounterFunc func);
 141 void deregisterCounterCallback(CounterHandle key);
 142
 143 struct CounterCallback {
 144   CounterCallback() = default;
 145
 146   explicit CounterCallback(CounterFunc func) {
 147     init(std::move(func));
 148   }
 149
 150   ~CounterCallback() {
 151     deinit();
 152   }
 153
 154   void init(CounterFunc func) {
 155     assertx(!m_key);
 156     m_key = registerCounterCallback(std::move(func));
 157   }
 158
 159   void deinit() {
 160     if (m_key) {
 161       deregisterCounterCallback(*m_key);
 162       m_key = std::nullopt;
 163     }
 164   }
 165
 166 private:
 167   Optional<CounterHandle> m_key;
 168 };
 169
 170 /*
 171  * Create a timeseries counter named 'name'. Return an existing one if it
 172  * has already been created.
 173  *
 174  * Timeseries data is implemented as a number of buckets (buckted by time).
 175  * As data point is added and time rolls forward, new bucket is created and
 176  * the earliest bucket expires.
 177  *
 178  * We keep multiple of timeseries data at different granularity and update
 179  * them simultaneously. This allows us to commute statistics at different
 180  * levels. For example, we can simultaneously compute the avg of some counter
 181  * value over the last 5 minutes, 10 minutes and hour. This is a similar
 182  * concept to the load counters from the unix 'uptime' command.
 183  *
 184  * 'exportTypes' specifies what kind of statistics to export for each level.
 185  * More export types can be added after the timeseries is created.
 186  *
 187  * 'levels' specifies at which granularity should the stats be tracked. The
 188  * time duration must be strictly increasing. Special value '0' means all
 189  * time and should always come last.
 190  *
 191  * 'numBuckets' specifies how many buckets to keep at each level. More buckets
 192  * will produce more precise data at the expense of memory.
 193  */
 194 ExportedTimeSeries* createTimeSeries(
 195   const std::string& name,
 196   const std::vector<StatsType>& exportTypes =
 197   std::vector<StatsType>{ StatsType::AVG },
 198   const std::vector<std::chrono::seconds>& levels =
 199   std::vector<std::chrono::seconds>{
 200     std::chrono::seconds(60),
 201     std::chrono::seconds(600),
 202     std::chrono::seconds(3600),
 203     std::chrono::seconds(0) /* all time */ },
 204   int numBuckets = 60);
 205
 206 /*
 207  * Create a histogram counter named 'name'. Return an existing one if it has
 208  * already been created.
 209  *
 210  * 'bucketSize' specifies how many buckets to track for the histogram.
 211  * 'min' is the minimal value in the histogram.
 212  * 'max' is the maximal value in the histogram.
 213  * 'exportPercentile' specifies at what percentile values we should report the
 214  * stat. A set of doubles between 0 and 1.0. For example, 0.5 means p50 and
 215  * 0.99 means p99.
 216  */
 217 ExportedHistogram* createHistogram(
 218   const std::string& name,
 219   int64_t bucketSize,
 220   int64_t min,
 221   int64_t max,
 222   const std::vector<double>& exportPercentile);
 223
 224 /*
 225  * Export all the statistics as simple key, value pairs.
 226  */
 227 void exportAll(std::map<std::string, int64_t>& statsMap);
 228
 229 /*
 230  * Export a specific counter by key name.
 231  */
 232 Optional<int64_t> exportCounterByKey(const std::string& key);
 233
 234 // Interface for a flat counter. All methods are thread safe.
 235 struct ExportedCounter {
 236   ExportedCounter() : m_value(0) {}
 237   void increment() { m_value.fetch_add(1, std::memory_order_relaxed); }
 238   void decrement() { m_value.fetch_sub(1, std::memory_order_relaxed); }
 239   void addValue(int64_t value) {
 240     m_value.fetch_add(value, std::memory_order_relaxed);
 241   }
 242   void setValue(int64_t value) {
 243     m_value.store(value, std::memory_order_relaxed);
 244   }
 245   int64_t getValue() const { return m_value.load(std::memory_order_relaxed); }
 246
 247  private:
 248   friend struct detail::FriendDeleter<ExportedCounter>;
 249   ~ExportedCounter() {}
 250
 251   std::atomic_int_fast64_t m_value;
 252 };
 253
 254 // Interface for timeseries data. All methods are thread safe.
 255 struct ExportedTimeSeries {
 256   ExportedTimeSeries(int numBuckets,
 257                      const std::vector<std::chrono::seconds>& durations,
 258                      const std::vector<StatsType>& exportTypes);
 259
 260   void addValue(int64_t value);
 261   void addValue(int64_t value, int64_t times);
 262   void addValueAggregated(int64_t sum, int64_t nsamples);
 263
 264   int64_t getSum();
 265   int64_t getRateByDuration(std::chrono::seconds duration);
 266
 267   Optional<int64_t> getCounter(StatsType type, int seconds);
 268
 269   void exportAll(const std::string& prefix,
 270                  std::map<std::string, int64_t>& statsMap);
 271
 272  private:
 273   friend struct detail::FriendDeleter<ExportedTimeSeries>;
 274   ~ExportedTimeSeries() {}
 275
 276   folly::Synchronized<folly::MultiLevelTimeSeries<int64_t>> m_timeseries;
 277   const std::vector<ServiceData::StatsType> m_exportTypes;
 278 };
 279
 280 // Interface for histogram data. All methods are thread safe.
 281 struct ExportedHistogram {
 282   ExportedHistogram(int64_t bucketSize, int64_t min, int64_t max,
 283                     const std::vector<double>& exportPercentiles);
 284   void addValue(int64_t value);
 285   void removeValue(int64_t value);
 286   void exportAll(const std::string& prefix,
 287                  std::map<std::string, int64_t>& statsMap);
 288
 289  private:
 290   friend struct detail::FriendDeleter<ExportedHistogram>;
 291   ~ExportedHistogram() {}
 292
 293   folly::Synchronized<folly::Histogram<int64_t>> m_histogram;
 294   const std::vector<double> m_exportPercentiles;
 295 };
 296
 297 };  // namespace ServiceData
 298
 299 ///////////////////////////////////////////////////////////////////////////////
 300 }
 301
 302 #include "hphp/util/service-data-inl.h"