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 ) 194