/proc/self/cwd/envoy/stats/histogram.h

Source
#pragma once

#include <cstdint>
#include <memory>
#include <vector>

#include "envoy/common/pure.h"
#include "envoy/stats/refcount_ptr.h"
#include "envoy/stats/stats.h"

namespace Envoy {
namespace Stats {

using ConstSupportedBuckets = const std::vector<double>;

class HistogramSettings {
public:
  virtual ~HistogramSettings() = default;

  /**
   * For formats like Prometheus where the entire histogram is published (but not
   * like statsd where each value to include in the histogram is emitted separately),
   * get the limits for each histogram bucket.
   * @return The buckets for the histogram. Each value is an upper bound of a bucket.
   */
  virtual ConstSupportedBuckets& buckets(absl::string_view stat_name) const PURE;
};

using HistogramSettingsConstPtr = std::unique_ptr<const HistogramSettings>;

/**
 * Holds the computed statistics for a histogram.
 */
class HistogramStatistics {
public:
  virtual ~HistogramStatistics() = default;

  /**
   * Returns quantile summary representation of the histogram.
   */
  virtual std::string quantileSummary() const PURE;

  /**
   * Returns bucket summary representation of the histogram.
   */
  virtual std::string bucketSummary() 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;

  /**
   * Returns supported buckets. Each value is the upper bound of the bucket
   * with 0 as the implicit lower bound. For timers, these bucket thresholds
   * are in milliseconds but the thresholds are applicable to all types of data.
   */
  virtual ConstSupportedBuckets& supportedBuckets() const PURE;

  /**
   * Returns computed bucket values during the period. The vector contains an approximation
   * of samples below each quantile bucket defined in supportedBuckets(). This vector is
   * guaranteed to be the same length as supportedBuckets().
   */
  virtual const std::vector<uint64_t>& computedBuckets() const PURE;

  /**
   * Returns version of computedBuckets() with disjoint buckets. This vector is
   * guaranteed to be the same length as supportedBuckets().
   */
  virtual std::vector<uint64_t> computeDisjointBuckets() const PURE;

  /**
   * Returns number of values during the period. This number may be an approximation
   * of the number of samples in the histogram, it is not guaranteed that this will be
   * 100% the number of samples observed.
   */
  virtual uint64_t sampleCount() const PURE;

  /**
   * Returns sum of all values during the period.
   */
  virtual double sampleSum() 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 two stat types was the units being represented.
 */
class Histogram : public Metric {
public:
  /**
   * Histogram values represent scalar quantity like time, length, mass,
   * distance, or in general anything which has only magnitude and no other
   * characteristics. These are often accompanied by a unit of measurement.
   * This enum defines units for commonly measured quantities. Base units
   * are preferred unless they are not granular enough to be useful as an
   * integer.
   */
  enum class Unit {
    Null,        // The histogram has been rejected, i.e. it's a null histogram and is not recording
                 // anything.
    Unspecified, // Measured quantity does not require a unit, e.g. "items".
    Bytes,
    Microseconds,
    Milliseconds,
    Percent, // A percent value stored as fixed-point, where the stored value is divided by
             // PercentScale to get the actual value, eg a value of 100% (or 1.0) is encoded as
             // PercentScale, 50% is encoded as PercentScale * 0.5. Encoding as fixed-point allows
             // enough dynamic range, without needing to support floating-point values in
             // histograms.
  };

  // The scaling factor for Unit::Percent.
  static constexpr uint64_t PercentScale = 1000000;

  ~Histogram() override = default;

  /**
   * @return the unit of measurement for values recorded by the histogram.
   */
  virtual Unit unit() const PURE;

  /**
   * Records an unsigned value in the unit specified during the construction.
   */
  virtual void recordValue(uint64_t value) PURE;
};

using HistogramSharedPtr = RefcountPtr<Histogram>;

/**
 * A histogram that is stored in main thread and provides summary view of the histogram.
 */
class ParentHistogram : public Histogram {
public:
  ~ParentHistogram() override = default;

  /**
   * This method is called during the main stats flush process for each of the histograms and used
   * to merge the histogram values.
   */
  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;

  /**
   * Returns the quantile summary representation.
   */
  virtual std::string quantileSummary() const PURE;

  /**
   * Returns the bucket summary representation.
   */
  virtual std::string bucketSummary() const PURE;

  // Holds detailed value and counts for a histogram bucket.
  struct Bucket {
    double lower_bound_{0}; // Bound of bucket that's closest to zero.
    double width_{0};
    uint64_t count_{0};
  };

  /**
   * @return a vector of histogram buckets collected since binary start or reset.
   */
  virtual std::vector<Bucket> detailedTotalBuckets() const PURE;

  /**
   * @return bucket data collected since the most recent stat sink. Note that
   *         the number of interval buckets is likely to be much smaller than
   *         the number of detailed buckets.
   */
  virtual std::vector<Bucket> detailedIntervalBuckets() const PURE;
};

using ParentHistogramSharedPtr = RefcountPtr<ParentHistogram>;

} // namespace Stats
} // namespace Envoy

Line	Count	Source
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	8.05k	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	75.0k	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		/**
92		* A histogram that records values one at a time.
93		* Note: Histograms now incorporate what used to be timers because the only
94		* difference between the two stat types was the units being represented.
95		*/
96		class Histogram : public Metric {
97		public:
98		/**
99		* Histogram values represent scalar quantity like time, length, mass,
100		* distance, or in general anything which has only magnitude and no other
101		* characteristics. These are often accompanied by a unit of measurement.
102		* This enum defines units for commonly measured quantities. Base units
103		* are preferred unless they are not granular enough to be useful as an
104		* integer.
105		*/
106		enum class Unit {
107		Null, // The histogram has been rejected, i.e. it's a null histogram and is not recording
108		// anything.
109		Unspecified, // Measured quantity does not require a unit, e.g. "items".
110		Bytes,
111		Microseconds,
112		Milliseconds,
113		Percent, // A percent value stored as fixed-point, where the stored value is divided by
114		// PercentScale to get the actual value, eg a value of 100% (or 1.0) is encoded as
115		// PercentScale, 50% is encoded as PercentScale * 0.5. Encoding as fixed-point allows
116		// enough dynamic range, without needing to support floating-point values in
117		// histograms.
118		};
119
120		// The scaling factor for Unit::Percent.
121		static constexpr uint64_t PercentScale = 1000000;
122
123		~Histogram() override = default;
124
125		/**
126		* @return the unit of measurement for values recorded by the histogram.
127		*/
128		virtual Unit unit() const PURE;
129
130		/**
131		* Records an unsigned value in the unit specified during the construction.
132		*/
133		virtual void recordValue(uint64_t value) PURE;
134		};
135
136		using HistogramSharedPtr = RefcountPtr<Histogram>;
137
138		/**
139		* A histogram that is stored in main thread and provides summary view of the histogram.
140		*/
141		class ParentHistogram : public Histogram {
142		public:
143		~ParentHistogram() override = default;
144
145		/**
146		* This method is called during the main stats flush process for each of the histograms and used
147		* to merge the histogram values.
148		*/
149		virtual void merge() PURE;
150
151		/**
152		* Returns the interval histogram summary statistics for the flush interval.
153		*/
154		virtual const HistogramStatistics& intervalStatistics() const PURE;
155
156		/**
157		* Returns the cumulative histogram summary statistics.
158		*/
159		virtual const HistogramStatistics& cumulativeStatistics() const PURE;
160
161		/**
162		* Returns the quantile summary representation.
163		*/
164		virtual std::string quantileSummary() const PURE;
165
166		/**
167		* Returns the bucket summary representation.
168		*/
169		virtual std::string bucketSummary() const PURE;
170
171		// Holds detailed value and counts for a histogram bucket.
172		struct Bucket {
173		double lower_bound_{0}; // Bound of bucket that's closest to zero.
174		double width_{0};
175		uint64_t count_{0};
176		};
177
178		/**
179		* @return a vector of histogram buckets collected since binary start or reset.
180		*/
181		virtual std::vector<Bucket> detailedTotalBuckets() const PURE;
182
183		/**
184		* @return bucket data collected since the most recent stat sink. Note that
185		* the number of interval buckets is likely to be much smaller than
186		* the number of detailed buckets.
187		*/
188		virtual std::vector<Bucket> detailedIntervalBuckets() const PURE;
189		};
190
191		using ParentHistogramSharedPtr = RefcountPtr<ParentHistogram>;
192
193		} // namespace Stats
194		} // namespace Envoy

Coverage Report

Created: 2023-11-12 09:30