vendor/go.opencensus.io/stats/measure.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 stats
  17
  18 import (
  19         "sync"
  20         "sync/atomic"
  21 )
  22
  23 // Measure represents a single numeric value to be tracked and recorded.
  24 // For example, latency, request bytes, and response bytes could be measures
  25 // to collect from a server.
  26 //
  27 // Measures by themselves have no outside effects. In order to be exported,
  28 // the measure needs to be used in a View. If no Views are defined over a
  29 // measure, there is very little cost in recording it.
  30 type Measure interface {
  31         // Name returns the name of this measure.
  32         //
  33         // Measure names are globally unique (among all libraries linked into your program).
  34         // We recommend prefixing the measure name with a domain name relevant to your
  35         // project or application.
  36         //
  37         // Measure names are never sent over the wire or exported to backends.
  38         // They are only used to create Views.
  39         Name() string
  40
  41         // Description returns the human-readable description of this measure.
  42         Description() string
  43
  44         // Unit returns the units for the values this measure takes on.
  45         //
  46         // Units are encoded according to the case-sensitive abbreviations from the
  47         // Unified Code for Units of Measure: http://unitsofmeasure.org/ucum.html
  48         Unit() string
  49 }
  50
  51 // measureDescriptor is the untyped descriptor associated with each measure.
  52 // Int64Measure and Float64Measure wrap measureDescriptor to provide typed
  53 // recording APIs.
  54 // Two Measures with the same name will have the same measureDescriptor.
  55 type measureDescriptor struct {
  56         subs int32 // access atomically
  57
  58         name        string
  59         description string
  60         unit        string
  61 }
  62
  63 func (m *measureDescriptor) subscribe() {
  64         atomic.StoreInt32(&m.subs, 1)
  65 }
  66
  67 func (m *measureDescriptor) subscribed() bool {
  68         return atomic.LoadInt32(&m.subs) == 1
  69 }
  70
  71 // Name returns the name of the measure.
  72 func (m *measureDescriptor) Name() string {
  73         return m.name
  74 }
  75
  76 // Description returns the description of the measure.
  77 func (m *measureDescriptor) Description() string {
  78         return m.description
  79 }
  80
  81 // Unit returns the unit of the measure.
  82 func (m *measureDescriptor) Unit() string {
  83         return m.unit
  84 }
  85
  86 var (
  87         mu       sync.RWMutex
  88         measures = make(map[string]*measureDescriptor)
  89 )
  90
  91 func registerMeasureHandle(name, desc, unit string) *measureDescriptor {
  92         mu.Lock()
  93         defer mu.Unlock()
  94
  95         if stored, ok := measures[name]; ok {
  96                 return stored
  97         }
  98         m := &measureDescriptor{
  99                 name:        name,
 100                 description: desc,
 101                 unit:        unit,
 102         }
 103         measures[name] = m
 104         return m
 105 }
 106
 107 // Measurement is the numeric value measured when recording stats. Each measure
 108 // provides methods to create measurements of their kind. For example, Int64Measure
 109 // provides M to convert an int64 into a measurement.
 110 type Measurement struct {
 111         v float64
 112         m *measureDescriptor
 113 }
 114
 115 // Value returns the value of the Measurement as a float64.
 116 func (m Measurement) Value() float64 {
 117         return m.v
 118 }
 119
 120 // Measure returns the Measure from which this Measurement was created.
 121 func (m Measurement) Measure() Measure {
 122         return m.m
 123 }