github.com/netdata/go.d.plugin@v0.58.1/pkg/metrics/summary.go (about)

     1  // SPDX-License-Identifier: GPL-3.0-or-later
     2  
     3  package metrics
     4  
     5  import (
     6  	"math"
     7  
     8  	"github.com/netdata/go.d.plugin/pkg/stm"
     9  )
    10  
    11  type (
    12  	// A Summary captures individual observations from an event or sample stream and
    13  	// summarizes them in a manner similar to traditional summary statistics:
    14  	//   sum of observations
    15  	//   observation count
    16  	//   observation average.
    17  	//
    18  	// To create summary instances, use NewSummary.
    19  	Summary interface {
    20  		Observer
    21  		Reset()
    22  	}
    23  
    24  	// SummaryVec is a Collector that bundles a set of Summary which have different values for their names.
    25  	// This is used if you want to count the same thing partitioned by various dimensions
    26  	// (e.g. number of HTTP response time, partitioned by response code and method).
    27  	//
    28  	// Create instances with NewSummaryVec.
    29  	SummaryVec map[string]Summary
    30  
    31  	summary struct {
    32  		min   float64
    33  		max   float64
    34  		sum   float64
    35  		count int64
    36  	}
    37  )
    38  
    39  var (
    40  	_ stm.Value = summary{}
    41  	_ stm.Value = SummaryVec{}
    42  )
    43  
    44  // NewSummary creates a new Summary.
    45  func NewSummary() Summary {
    46  	return &summary{
    47  		min: math.MaxFloat64,
    48  		max: -math.MaxFloat64,
    49  	}
    50  }
    51  
    52  // WriteTo writes its values into given map.
    53  // It adds those key-value pairs:
    54  //
    55  //	${key}_sum        gauge, for sum of it's observed values from last Reset calls
    56  //	${key}_count      counter, for count of it's observed values from last Reset calls
    57  //	${key}_min        gauge, for min of it's observed values from last Reset calls (only exists if count > 0)
    58  //	${key}_max        gauge, for max of it's observed values from last Reset calls (only exists if count > 0)
    59  //	${key}_avg        gauge, for avg of it's observed values from last Reset calls (only exists if count > 0)
    60  func (s summary) WriteTo(rv map[string]int64, key string, mul, div int) {
    61  	if s.count > 0 {
    62  		rv[key+"_min"] = int64(s.min * float64(mul) / float64(div))
    63  		rv[key+"_max"] = int64(s.max * float64(mul) / float64(div))
    64  		rv[key+"_sum"] = int64(s.sum * float64(mul) / float64(div))
    65  		rv[key+"_count"] = s.count
    66  		rv[key+"_avg"] = int64(s.sum / float64(s.count) * float64(mul) / float64(div))
    67  	} else {
    68  		rv[key+"_count"] = 0
    69  		rv[key+"_sum"] = 0
    70  		delete(rv, key+"_min")
    71  		delete(rv, key+"_max")
    72  		delete(rv, key+"_avg")
    73  	}
    74  }
    75  
    76  // Reset resets all of its counters.
    77  // Call it before every scrape loop.
    78  func (s *summary) Reset() {
    79  	s.min = math.MaxFloat64
    80  	s.max = -math.MaxFloat64
    81  	s.sum = 0
    82  	s.count = 0
    83  }
    84  
    85  // Observe observes a value
    86  func (s *summary) Observe(v float64) {
    87  	if v > s.max {
    88  		s.max = v
    89  	}
    90  	if v < s.min {
    91  		s.min = v
    92  	}
    93  	s.sum += v
    94  	s.count++
    95  }
    96  
    97  // NewSummaryVec creates a new SummaryVec instance.
    98  func NewSummaryVec() SummaryVec {
    99  	return SummaryVec{}
   100  }
   101  
   102  // WriteTo writes its value into given map.
   103  func (c SummaryVec) WriteTo(rv map[string]int64, key string, mul, div int) {
   104  	for name, value := range c {
   105  		value.WriteTo(rv, key+"_"+name, mul, div)
   106  	}
   107  }
   108  
   109  // Get gets counter instance by name.
   110  func (c SummaryVec) Get(name string) Summary {
   111  	item, ok := c[name]
   112  	if ok {
   113  		return item
   114  	}
   115  	item = NewSummary()
   116  	c[name] = item
   117  	return item
   118  }
   119  
   120  // Reset resets its all summaries.
   121  func (c SummaryVec) Reset() {
   122  	for _, value := range c {
   123  		value.Reset()
   124  	}
   125  }