cmd/bpa-operator/vendor/go.opencensus.io/metric/metricdata/point.go

   1 // Copyright 2018, OpenCensus Authors
   2 //
   3 // Licensed under the Apache License, Version 2.0 (the "License");
   4 // you may not use this file except in compliance with the License.
   5 // You may obtain a copy of the License at
   6 //
   7 //     http://www.apache.org/licenses/LICENSE-2.0
   8 //
   9 // Unless required by applicable law or agreed to in writing, software
  10 // distributed under the License is distributed on an "AS IS" BASIS,
  11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  12 // See the License for the specific language governing permissions and
  13 // limitations under the License.
  14
  15 package metricdata
  16
  17 import (
  18         "time"
  19 )
  20
  21 // Point is a single data point of a time series.
  22 type Point struct {
  23         // Time is the point in time that this point represents in a time series.
  24         Time time.Time
  25         // Value is the value of this point. Prefer using ReadValue to switching on
  26         // the value type, since new value types might be added.
  27         Value interface{}
  28 }
  29
  30 //go:generate stringer -type ValueType
  31
  32 // NewFloat64Point creates a new Point holding a float64 value.
  33 func NewFloat64Point(t time.Time, val float64) Point {
  34         return Point{
  35                 Value: val,
  36                 Time:  t,
  37         }
  38 }
  39
  40 // NewInt64Point creates a new Point holding an int64 value.
  41 func NewInt64Point(t time.Time, val int64) Point {
  42         return Point{
  43                 Value: val,
  44                 Time:  t,
  45         }
  46 }
  47
  48 // NewDistributionPoint creates a new Point holding a Distribution value.
  49 func NewDistributionPoint(t time.Time, val *Distribution) Point {
  50         return Point{
  51                 Value: val,
  52                 Time:  t,
  53         }
  54 }
  55
  56 // NewSummaryPoint creates a new Point holding a Summary value.
  57 func NewSummaryPoint(t time.Time, val *Summary) Point {
  58         return Point{
  59                 Value: val,
  60                 Time:  t,
  61         }
  62 }
  63
  64 // ValueVisitor allows reading the value of a point.
  65 type ValueVisitor interface {
  66         VisitFloat64Value(float64)
  67         VisitInt64Value(int64)
  68         VisitDistributionValue(*Distribution)
  69         VisitSummaryValue(*Summary)
  70 }
  71
  72 // ReadValue accepts a ValueVisitor and calls the appropriate method with the
  73 // value of this point.
  74 // Consumers of Point should use this in preference to switching on the type
  75 // of the value directly, since new value types may be added.
  76 func (p Point) ReadValue(vv ValueVisitor) {
  77         switch v := p.Value.(type) {
  78         case int64:
  79                 vv.VisitInt64Value(v)
  80         case float64:
  81                 vv.VisitFloat64Value(v)
  82         case *Distribution:
  83                 vv.VisitDistributionValue(v)
  84         case *Summary:
  85                 vv.VisitSummaryValue(v)
  86         default:
  87                 panic("unexpected value type")
  88         }
  89 }
  90
  91 // Distribution contains summary statistics for a population of values. It
  92 // optionally contains a histogram representing the distribution of those
  93 // values across a set of buckets.
  94 type Distribution struct {
  95         // Count is the number of values in the population. Must be non-negative. This value
  96         // must equal the sum of the values in bucket_counts if a histogram is
  97         // provided.
  98         Count int64
  99         // Sum is the sum of the values in the population. If count is zero then this field
 100         // must be zero.
 101         Sum float64
 102         // SumOfSquaredDeviation is the sum of squared deviations from the mean of the values in the
 103         // population. For values x_i this is:
 104         //
 105         //     Sum[i=1..n]((x_i - mean)^2)
 106         //
 107         // Knuth, "The Art of Computer Programming", Vol. 2, page 323, 3rd edition
 108         // describes Welford's method for accumulating this sum in one pass.
 109         //
 110         // If count is zero then this field must be zero.
 111         SumOfSquaredDeviation float64
 112         // BucketOptions describes the bounds of the histogram buckets in this
 113         // distribution.
 114         //
 115         // A Distribution may optionally contain a histogram of the values in the
 116         // population.
 117         //
 118         // If nil, there is no associated histogram.
 119         BucketOptions *BucketOptions
 120         // Bucket If the distribution does not have a histogram, then omit this field.
 121         // If there is a histogram, then the sum of the values in the Bucket counts
 122         // must equal the value in the count field of the distribution.
 123         Buckets []Bucket
 124 }
 125
 126 // BucketOptions describes the bounds of the histogram buckets in this
 127 // distribution.
 128 type BucketOptions struct {
 129         // Bounds specifies a set of bucket upper bounds.
 130         // This defines len(bounds) + 1 (= N) buckets. The boundaries for bucket
 131         // index i are:
 132         //
 133         // [0, Bounds[i]) for i == 0
 134         // [Bounds[i-1], Bounds[i]) for 0 < i < N-1
 135         // [Bounds[i-1], +infinity) for i == N-1
 136         Bounds []float64
 137 }
 138
 139 // Bucket represents a single bucket (value range) in a distribution.
 140 type Bucket struct {
 141         // Count is the number of values in each bucket of the histogram, as described in
 142         // bucket_bounds.
 143         Count int64
 144         // Exemplar associated with this bucket (if any).
 145         Exemplar *Exemplar
 146 }
 147
 148 // Summary is a representation of percentiles.
 149 type Summary struct {
 150         // Count is the cumulative count (if available).
 151         Count int64
 152         // Sum is the cumulative sum of values  (if available).
 153         Sum float64
 154         // HasCountAndSum is true if Count and Sum are available.
 155         HasCountAndSum bool
 156         // Snapshot represents percentiles calculated over an arbitrary time window.
 157         // The values in this struct can be reset at arbitrary unknown times, with
 158         // the requirement that all of them are reset at the same time.
 159         Snapshot Snapshot
 160 }
 161
 162 // Snapshot represents percentiles over an arbitrary time.
 163 // The values in this struct can be reset at arbitrary unknown times, with
 164 // the requirement that all of them are reset at the same time.
 165 type Snapshot struct {
 166         // Count is the number of values in the snapshot. Optional since some systems don't
 167         // expose this. Set to 0 if not available.
 168         Count int64
 169         // Sum is the sum of values in the snapshot. Optional since some systems don't
 170         // expose this. If count is 0 then this field must be zero.
 171         Sum float64
 172         // Percentiles is a map from percentile (range (0-100.0]) to the value of
 173         // the percentile.
 174         Percentiles map[float64]float64
 175 }
 176
 177 //go:generate stringer -type Type
 178
 179 // Type is the overall type of metric, including its value type and whether it
 180 // represents a cumulative total (since the start time) or if it represents a
 181 // gauge value.
 182 type Type int
 183
 184 // Metric types.
 185 const (
 186         TypeGaugeInt64 Type = iota
 187         TypeGaugeFloat64
 188         TypeGaugeDistribution
 189         TypeCumulativeInt64
 190         TypeCumulativeFloat64
 191         TypeCumulativeDistribution
 192         TypeSummary
 193 )