Line data    Source code

       1             : #pragma once
       2             : 
       3             : #include <cstdint>
       4             : #include <memory>
       5             : #include <vector>
       6             : 
       7             : #include "envoy/common/pure.h"
       8             : #include "envoy/stats/refcount_ptr.h"
       9             : #include "envoy/stats/stats.h"
      10             : 
      11             : namespace Envoy {
      12             : namespace Stats {
      13             : 
      14             : using ConstSupportedBuckets = const std::vector<double>;
      15             : 
      16             : class HistogramSettings {
      17             : public:
      18         232 :   virtual ~HistogramSettings() = default;
      19             : 
      20             :   /**
      21             :    * For formats like Prometheus where the entire histogram is published (but not
      22             :    * like statsd where each value to include in the histogram is emitted separately),
      23             :    * get the limits for each histogram bucket.
      24             :    * @return The buckets for the histogram. Each value is an upper bound of a bucket.
      25             :    */
      26             :   virtual ConstSupportedBuckets& buckets(absl::string_view stat_name) const PURE;
      27             : };
      28             : 
      29             : using HistogramSettingsConstPtr = std::unique_ptr<const HistogramSettings>;
      30             : 
      31             : /**
      32             :  * Holds the computed statistics for a histogram.
      33             :  */
      34             : class HistogramStatistics {
      35             : public:
      36        3086 :   virtual ~HistogramStatistics() = default;
      37             : 
      38             :   /**
      39             :    * Returns quantile summary representation of the histogram.
      40             :    */
      41             :   virtual std::string quantileSummary() const PURE;
      42             : 
      43             :   /**
      44             :    * Returns bucket summary representation of the histogram.
      45             :    */
      46             :   virtual std::string bucketSummary() const PURE;
      47             : 
      48             :   /**
      49             :    * Returns supported quantiles.
      50             :    */
      51             :   virtual const std::vector<double>& supportedQuantiles() const PURE;
      52             : 
      53             :   /**
      54             :    * Returns computed quantile values during the period.
      55             :    */
      56             :   virtual const std::vector<double>& computedQuantiles() const PURE;
      57             : 
      58             :   /**
      59             :    * Returns supported buckets. Each value is the upper bound of the bucket
      60             :    * with 0 as the implicit lower bound. For timers, these bucket thresholds
      61             :    * are in milliseconds but the thresholds are applicable to all types of data.
      62             :    */
      63             :   virtual ConstSupportedBuckets& supportedBuckets() const PURE;
      64             : 
      65             :   /**
      66             :    * Returns computed bucket values during the period. The vector contains an approximation
      67             :    * of samples below each quantile bucket defined in supportedBuckets(). This vector is
      68             :    * guaranteed to be the same length as supportedBuckets().
      69             :    */
      70             :   virtual const std::vector<uint64_t>& computedBuckets() const PURE;
      71             : 
      72             :   /**
      73             :    * Returns version of computedBuckets() with disjoint buckets. This vector is
      74             :    * guaranteed to be the same length as supportedBuckets().
      75             :    */
      76             :   virtual std::vector<uint64_t> computeDisjointBuckets() const PURE;
      77             : 
      78             :   /**
      79             :    * Returns number of values during the period. This number may be an approximation
      80             :    * of the number of samples in the histogram, it is not guaranteed that this will be
      81             :    * 100% the number of samples observed.
      82             :    */
      83             :   virtual uint64_t sampleCount() const PURE;
      84             : 
      85             :   /**
      86             :    * Returns sum of all values during the period.
      87             :    */
      88             :   virtual double sampleSum() const PURE;
      89             : 
      90             :   /**
      91             :    * Returns the count of values which are out of the boundaries of the histogram bins.
      92             :    * I.e., the count of values in the (bound_of_last_bucket, +inf) bucket.
      93             :    */
      94             :   virtual uint64_t outOfBoundCount() const PURE;
      95             : };
      96             : 
      97             : /**
      98             :  * A histogram that records values one at a time.
      99             :  * Note: Histograms now incorporate what used to be timers because the only
     100             :  * difference between the two stat types was the units being represented.
     101             :  */
     102             : class Histogram : public Metric {
     103             : public:
     104             :   /**
     105             :    * Histogram values represent scalar quantity like time, length, mass,
     106             :    * distance, or in general anything which has only magnitude and no other
     107             :    * characteristics. These are often accompanied by a unit of measurement.
     108             :    * This enum defines units for commonly measured quantities. Base units
     109             :    * are preferred unless they are not granular enough to be useful as an
     110             :    * integer.
     111             :    */
     112             :   enum class Unit {
     113             :     Null,        // The histogram has been rejected, i.e. it's a null histogram and is not recording
     114             :                  // anything.
     115             :     Unspecified, // Measured quantity does not require a unit, e.g. "items".
     116             :     Bytes,
     117             :     Microseconds,
     118             :     Milliseconds,
     119             :     Percent, // A percent value stored as fixed-point, where the stored value is divided by
     120             :              // PercentScale to get the actual value, eg a value of 100% (or 1.0) is encoded as
     121             :              // PercentScale, 50% is encoded as PercentScale * 0.5. Encoding as fixed-point allows
     122             :              // enough dynamic range, without needing to support floating-point values in
     123             :              // histograms.
     124             :   };
     125             : 
     126             :   // The scaling factor for Unit::Percent.
     127             :   static constexpr uint64_t PercentScale = 1000000;
     128             : 
     129       21614 :   ~Histogram() override = default;
     130             : 
     131             :   /**
     132             :    * @return the unit of measurement for values recorded by the histogram.
     133             :    */
     134             :   virtual Unit unit() const PURE;
     135             : 
     136             :   /**
     137             :    * Records an unsigned value in the unit specified during the construction.
     138             :    */
     139             :   virtual void recordValue(uint64_t value) PURE;
     140             : };
     141             : 
     142             : using HistogramSharedPtr = RefcountPtr<Histogram>;
     143             : 
     144             : /**
     145             :  * A histogram that is stored in main thread and provides summary view of the histogram.
     146             :  */
     147             : class ParentHistogram : public Histogram {
     148             : public:
     149        1543 :   ~ParentHistogram() override = default;
     150             : 
     151             :   /**
     152             :    * This method is called during the main stats flush process for each of the histograms and used
     153             :    * to merge the histogram values.
     154             :    */
     155             :   virtual void merge() PURE;
     156             : 
     157             :   /**
     158             :    * Returns the interval histogram summary statistics for the flush interval.
     159             :    */
     160             :   virtual const HistogramStatistics& intervalStatistics() const PURE;
     161             : 
     162             :   /**
     163             :    * Returns the cumulative histogram summary statistics.
     164             :    */
     165             :   virtual const HistogramStatistics& cumulativeStatistics() const PURE;
     166             : 
     167             :   /**
     168             :    * Returns the quantile summary representation.
     169             :    */
     170             :   virtual std::string quantileSummary() const PURE;
     171             : 
     172             :   /**
     173             :    * Returns the bucket summary representation.
     174             :    */
     175             :   virtual std::string bucketSummary() const PURE;
     176             : 
     177             :   // Holds detailed value and counts for a histogram bucket.
     178             :   struct Bucket {
     179             :     double lower_bound_{0}; // Bound of bucket that's closest to zero.
     180             :     double width_{0};
     181             :     uint64_t count_{0};
     182             :   };
     183             : 
     184             :   /**
     185             :    * @return a vector of histogram buckets collected since binary start or reset.
     186             :    */
     187             :   virtual std::vector<Bucket> detailedTotalBuckets() const PURE;
     188             : 
     189             :   /**
     190             :    * @return bucket data collected since the most recent stat sink. Note that
     191             :    *         the number of interval buckets is likely to be much smaller than
     192             :    *         the number of detailed buckets.
     193             :    */
     194             :   virtual std::vector<Bucket> detailedIntervalBuckets() const PURE;
     195             : };
     196             : 
     197             : using ParentHistogramSharedPtr = RefcountPtr<ParentHistogram>;
     198             : 
     199             : } // namespace Stats
     200             : } // namespace Envoy