histogram.go

Documentation: github.com/rcrowley/go-metrics

     1  package metrics
     2  
     3  // Histograms calculate distribution statistics from a series of int64 values.
     4  type Histogram interface {
     5  	Clear()
     6  	Count() int64
     7  	Max() int64
     8  	Mean() float64
     9  	Min() int64
    10  	Percentile(float64) float64
    11  	Percentiles([]float64) []float64
    12  	Sample() Sample
    13  	Snapshot() Histogram
    14  	StdDev() float64
    15  	Sum() int64
    16  	Update(int64)
    17  	Variance() float64
    18  }
    19  
    20  // GetOrRegisterHistogram returns an existing Histogram or constructs and
    21  // registers a new StandardHistogram.
    22  func GetOrRegisterHistogram(name string, r Registry, s Sample) Histogram {
    23  	if nil == r {
    24  		r = DefaultRegistry
    25  	}
    26  	return r.GetOrRegister(name, func() Histogram { return NewHistogram(s) }).(Histogram)
    27  }
    28  
    29  // NewHistogram constructs a new StandardHistogram from a Sample.
    30  func NewHistogram(s Sample) Histogram {
    31  	if UseNilMetrics {
    32  		return NilHistogram{}
    33  	}
    34  	return &StandardHistogram{sample: s}
    35  }
    36  
    37  // NewRegisteredHistogram constructs and registers a new StandardHistogram from
    38  // a Sample.
    39  func NewRegisteredHistogram(name string, r Registry, s Sample) Histogram {
    40  	c := NewHistogram(s)
    41  	if nil == r {
    42  		r = DefaultRegistry
    43  	}
    44  	r.Register(name, c)
    45  	return c
    46  }
    47  
    48  // HistogramSnapshot is a read-only copy of another Histogram.
    49  type HistogramSnapshot struct {
    50  	sample *SampleSnapshot
    51  }
    52  
    53  // Clear panics.
    54  func (*HistogramSnapshot) Clear() {
    55  	panic("Clear called on a HistogramSnapshot")
    56  }
    57  
    58  // Count returns the number of samples recorded at the time the snapshot was
    59  // taken.
    60  func (h *HistogramSnapshot) Count() int64 { return h.sample.Count() }
    61  
    62  // Max returns the maximum value in the sample at the time the snapshot was
    63  // taken.
    64  func (h *HistogramSnapshot) Max() int64 { return h.sample.Max() }
    65  
    66  // Mean returns the mean of the values in the sample at the time the snapshot
    67  // was taken.
    68  func (h *HistogramSnapshot) Mean() float64 { return h.sample.Mean() }
    69  
    70  // Min returns the minimum value in the sample at the time the snapshot was
    71  // taken.
    72  func (h *HistogramSnapshot) Min() int64 { return h.sample.Min() }
    73  
    74  // Percentile returns an arbitrary percentile of values in the sample at the
    75  // time the snapshot was taken.
    76  func (h *HistogramSnapshot) Percentile(p float64) float64 {
    77  	return h.sample.Percentile(p)
    78  }
    79  
    80  // Percentiles returns a slice of arbitrary percentiles of values in the sample
    81  // at the time the snapshot was taken.
    82  func (h *HistogramSnapshot) Percentiles(ps []float64) []float64 {
    83  	return h.sample.Percentiles(ps)
    84  }
    85  
    86  // Sample returns the Sample underlying the histogram.
    87  func (h *HistogramSnapshot) Sample() Sample { return h.sample }
    88  
    89  // Snapshot returns the snapshot.
    90  func (h *HistogramSnapshot) Snapshot() Histogram { return h }
    91  
    92  // StdDev returns the standard deviation of the values in the sample at the
    93  // time the snapshot was taken.
    94  func (h *HistogramSnapshot) StdDev() float64 { return h.sample.StdDev() }
    95  
    96  // Sum returns the sum in the sample at the time the snapshot was taken.
    97  func (h *HistogramSnapshot) Sum() int64 { return h.sample.Sum() }
    98  
    99  // Update panics.
   100  func (*HistogramSnapshot) Update(int64) {
   101  	panic("Update called on a HistogramSnapshot")
   102  }
   103  
   104  // Variance returns the variance of inputs at the time the snapshot was taken.
   105  func (h *HistogramSnapshot) Variance() float64 { return h.sample.Variance() }
   106  
   107  // NilHistogram is a no-op Histogram.
   108  type NilHistogram struct{}
   109  
   110  // Clear is a no-op.
   111  func (NilHistogram) Clear() {}
   112  
   113  // Count is a no-op.
   114  func (NilHistogram) Count() int64 { return 0 }
   115  
   116  // Max is a no-op.
   117  func (NilHistogram) Max() int64 { return 0 }
   118  
   119  // Mean is a no-op.
   120  func (NilHistogram) Mean() float64 { return 0.0 }
   121  
   122  // Min is a no-op.
   123  func (NilHistogram) Min() int64 { return 0 }
   124  
   125  // Percentile is a no-op.
   126  func (NilHistogram) Percentile(p float64) float64 { return 0.0 }
   127  
   128  // Percentiles is a no-op.
   129  func (NilHistogram) Percentiles(ps []float64) []float64 {
   130  	return make([]float64, len(ps))
   131  }
   132  
   133  // Sample is a no-op.
   134  func (NilHistogram) Sample() Sample { return NilSample{} }
   135  
   136  // Snapshot is a no-op.
   137  func (NilHistogram) Snapshot() Histogram { return NilHistogram{} }
   138  
   139  // StdDev is a no-op.
   140  func (NilHistogram) StdDev() float64 { return 0.0 }
   141  
   142  // Sum is a no-op.
   143  func (NilHistogram) Sum() int64 { return 0 }
   144  
   145  // Update is a no-op.
   146  func (NilHistogram) Update(v int64) {}
   147  
   148  // Variance is a no-op.
   149  func (NilHistogram) Variance() float64 { return 0.0 }
   150  
   151  // StandardHistogram is the standard implementation of a Histogram and uses a
   152  // Sample to bound its memory use.
   153  type StandardHistogram struct {
   154  	sample Sample
   155  }
   156  
   157  // Clear clears the histogram and its sample.
   158  func (h *StandardHistogram) Clear() { h.sample.Clear() }
   159  
   160  // Count returns the number of samples recorded since the histogram was last
   161  // cleared.
   162  func (h *StandardHistogram) Count() int64 { return h.sample.Count() }
   163  
   164  // Max returns the maximum value in the sample.
   165  func (h *StandardHistogram) Max() int64 { return h.sample.Max() }
   166  
   167  // Mean returns the mean of the values in the sample.
   168  func (h *StandardHistogram) Mean() float64 { return h.sample.Mean() }
   169  
   170  // Min returns the minimum value in the sample.
   171  func (h *StandardHistogram) Min() int64 { return h.sample.Min() }
   172  
   173  // Percentile returns an arbitrary percentile of the values in the sample.
   174  func (h *StandardHistogram) Percentile(p float64) float64 {
   175  	return h.sample.Percentile(p)
   176  }
   177  
   178  // Percentiles returns a slice of arbitrary percentiles of the values in the
   179  // sample.
   180  func (h *StandardHistogram) Percentiles(ps []float64) []float64 {
   181  	return h.sample.Percentiles(ps)
   182  }
   183  
   184  // Sample returns the Sample underlying the histogram.
   185  func (h *StandardHistogram) Sample() Sample { return h.sample }
   186  
   187  // Snapshot returns a read-only copy of the histogram.
   188  func (h *StandardHistogram) Snapshot() Histogram {
   189  	return &HistogramSnapshot{sample: h.sample.Snapshot().(*SampleSnapshot)}
   190  }
   191  
   192  // StdDev returns the standard deviation of the values in the sample.
   193  func (h *StandardHistogram) StdDev() float64 { return h.sample.StdDev() }
   194  
   195  // Sum returns the sum in the sample.
   196  func (h *StandardHistogram) Sum() int64 { return h.sample.Sum() }
   197  
   198  // Update samples a new value.
   199  func (h *StandardHistogram) Update(v int64) { h.sample.Update(v) }
   200  
   201  // Variance returns the variance of the values in the sample.
   202  func (h *StandardHistogram) Variance() float64 { return h.sample.Variance() }
   203
View as plain text