vendor/go.opencensus.io/stats/view/aggregation.go

   1 // Copyright 2017, 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
  16 package view
  17
  18 // AggType represents the type of aggregation function used on a View.
  19 type AggType int
  20
  21 // All available aggregation types.
  22 const (
  23         AggTypeNone         AggType = iota // no aggregation; reserved for future use.
  24         AggTypeCount                       // the count aggregation, see Count.
  25         AggTypeSum                         // the sum aggregation, see Sum.
  26         AggTypeDistribution                // the distribution aggregation, see Distribution.
  27         AggTypeLastValue                   // the last value aggregation, see LastValue.
  28 )
  29
  30 func (t AggType) String() string {
  31         return aggTypeName[t]
  32 }
  33
  34 var aggTypeName = map[AggType]string{
  35         AggTypeNone:         "None",
  36         AggTypeCount:        "Count",
  37         AggTypeSum:          "Sum",
  38         AggTypeDistribution: "Distribution",
  39         AggTypeLastValue:    "LastValue",
  40 }
  41
  42 // Aggregation represents a data aggregation method. Use one of the functions:
  43 // Count, Sum, or Distribution to construct an Aggregation.
  44 type Aggregation struct {
  45         Type    AggType   // Type is the AggType of this Aggregation.
  46         Buckets []float64 // Buckets are the bucket endpoints if this Aggregation represents a distribution, see Distribution.
  47
  48         newData func() AggregationData
  49 }
  50
  51 var (
  52         aggCount = &Aggregation{
  53                 Type: AggTypeCount,
  54                 newData: func() AggregationData {
  55                         return &CountData{}
  56                 },
  57         }
  58         aggSum = &Aggregation{
  59                 Type: AggTypeSum,
  60                 newData: func() AggregationData {
  61                         return &SumData{}
  62                 },
  63         }
  64 )
  65
  66 // Count indicates that data collected and aggregated
  67 // with this method will be turned into a count value.
  68 // For example, total number of accepted requests can be
  69 // aggregated by using Count.
  70 func Count() *Aggregation {
  71         return aggCount
  72 }
  73
  74 // Sum indicates that data collected and aggregated
  75 // with this method will be summed up.
  76 // For example, accumulated request bytes can be aggregated by using
  77 // Sum.
  78 func Sum() *Aggregation {
  79         return aggSum
  80 }
  81
  82 // Distribution indicates that the desired aggregation is
  83 // a histogram distribution.
  84 //
  85 // An distribution aggregation may contain a histogram of the values in the
  86 // population. The bucket boundaries for that histogram are described
  87 // by the bounds. This defines len(bounds)+1 buckets.
  88 //
  89 // If len(bounds) >= 2 then the boundaries for bucket index i are:
  90 //
  91 //     [-infinity, bounds[i]) for i = 0
  92 //     [bounds[i-1], bounds[i]) for 0 < i < length
  93 //     [bounds[i-1], +infinity) for i = length
  94 //
  95 // If len(bounds) is 0 then there is no histogram associated with the
  96 // distribution. There will be a single bucket with boundaries
  97 // (-infinity, +infinity).
  98 //
  99 // If len(bounds) is 1 then there is no finite buckets, and that single
 100 // element is the common boundary of the overflow and underflow buckets.
 101 func Distribution(bounds ...float64) *Aggregation {
 102         return &Aggregation{
 103                 Type:    AggTypeDistribution,
 104                 Buckets: bounds,
 105                 newData: func() AggregationData {
 106                         return newDistributionData(bounds)
 107                 },
 108         }
 109 }
 110
 111 // LastValue only reports the last value recorded using this
 112 // aggregation. All other measurements will be dropped.
 113 func LastValue() *Aggregation {
 114         return &Aggregation{
 115                 Type: AggTypeLastValue,
 116                 newData: func() AggregationData {
 117                         return &LastValueData{}
 118                 },
 119         }
 120 }