Documentation

Overview

    Package stats defines a lightweight interface for collecting statistics. It doesn't provide an implementation, just the shared interface.

    Index

    Constants

    This section is empty.

    Variables

    View Source
    var (
    	// HistogramPercentiles is used to determine which percentiles to return for
    	// SimpleCounter.Aggregate
    	HistogramPercentiles = map[string]float64{
    		"p50": 0.5,
    		"p95": 0.95,
    		"p99": 0.99,
    	}
    
    	// MinSamplesForPercentiles is used by SimpleCounter.Aggregate to determine
    	// what the minimum number of samples is required for percentile analysis
    	MinSamplesForPercentiles = 10
    )
    View Source
    var NoOpEnd = noOpEnd{}

      NoOpEnd provides a dummy value for use in tests as valid return value for BumpTime().

      Functions

      func Average

      func Average(values []float64) float64

        Average returns the average value

        func BumpAvg

        func BumpAvg(c Client, key string, val float64)

          BumpAvg calls BumpAvg on the Client if it isn't nil. This is useful when a component has an optional stats.Client.

          func BumpHistogram

          func BumpHistogram(c Client, key string, val float64)

            BumpHistogram calls BumpHistogram on the Client if it isn't nil. This is useful when a component has an optional stats.Client.

            func BumpSum

            func BumpSum(c Client, key string, val float64)

              BumpSum calls BumpSum on the Client if it isn't nil. This is useful when a component has an optional stats.Client.

              func BumpTime

              func BumpTime(c Client, key string) interface {
              	End()
              }

                BumpTime calls BumpTime on the Client if it isn't nil. If the Client is nil it still returns a valid return value which will be a no-op. This is useful when a component has an optional stats.Client.

                func Percentiles

                func Percentiles(values []float64, percentiles map[string]float64) map[string]float64

                  Percentiles returns a map containing the asked for percentiles

                  func Sum

                  func Sum(values []float64) float64

                    Sum returns the sum of all the given values

                    Types

                    type Aggregates

                    type Aggregates map[string]Counter

                      Aggregates can be used to merge counters together. This is not goroutine safe

                      func (Aggregates) Add

                      func (a Aggregates) Add(c Counter) error

                        Add adds the counter for aggregation. This is not goroutine safe

                        type Client

                        type Client interface {
                        	// BumpAvg bumps the average for the given key.
                        	BumpAvg(key string, val float64)
                        
                        	// BumpSum bumps the sum for the given key.
                        	BumpSum(key string, val float64)
                        
                        	// BumpHistogram bumps the histogram for the given key.
                        	BumpHistogram(key string, val float64)
                        
                        	// BumpTime is a special version of BumpHistogram which is specialized for
                        	// timers. Calling it starts the timer, and it returns a value on which End()
                        	// can be called to indicate finishing the timer. A convenient way of
                        	// recording the duration of a function is calling it like such at the top of
                        	// the function:
                        	//
                        	//     defer s.BumpTime("my.function").End()
                        	BumpTime(key string) interface {
                        		End()
                        	}
                        }

                          Client provides methods to collection statistics.

                          func PrefixClient

                          func PrefixClient(prefixes []string, client Client) Client

                            PrefixClient adds multiple keys for the same value, with each prefix added to the key and calls the underlying client.

                            type Counter

                            type Counter interface {
                            	// FullKey is used to uniquely identify the counter
                            	FullKey() string
                            
                            	// AddValues adds values for aggregation
                            	AddValues(...float64)
                            
                            	// GetValues returns the values for aggregation
                            	GetValues() []float64
                            
                            	// GetType returns the type of aggregation to apply
                            	GetType() Type
                            }

                              Counter is the interface used by Aggregates to merge counters together

                              type HookClient

                              type HookClient struct {
                              	BumpAvgHook       func(key string, val float64)
                              	BumpSumHook       func(key string, val float64)
                              	BumpHistogramHook func(key string, val float64)
                              	BumpTimeHook      func(key string) interface {
                              		End()
                              	}
                              }

                                HookClient is useful for testing. It provides optional hooks for each expected method in the interface, which if provided will be called. If a hook is not provided, it will be ignored.

                                func (*HookClient) BumpAvg

                                func (c *HookClient) BumpAvg(key string, val float64)

                                  BumpAvg will call BumpAvgHook if defined.

                                  func (*HookClient) BumpHistogram

                                  func (c *HookClient) BumpHistogram(key string, val float64)

                                    BumpHistogram will call BumpHistogramHook if defined.

                                    func (*HookClient) BumpSum

                                    func (c *HookClient) BumpSum(key string, val float64)

                                      BumpSum will call BumpSumHook if defined.

                                      func (*HookClient) BumpTime

                                      func (c *HookClient) BumpTime(key string) interface {
                                      	End()
                                      }

                                        BumpTime will call BumpTimeHook if defined.

                                        type SimpleCounter

                                        type SimpleCounter struct {
                                        	Key    string
                                        	Values []float64
                                        	Type   Type
                                        }

                                          SimpleCounter is a basic implementation of the Counter interface

                                          func (*SimpleCounter) AddValues

                                          func (s *SimpleCounter) AddValues(vs ...float64)

                                            AddValues is part of the Counter interface

                                            func (*SimpleCounter) Aggregate

                                            func (s *SimpleCounter) Aggregate() map[string]float64

                                              Aggregate aggregates the provided values appropriately, returning a map from key to value. If AggregateHistogram is specified, the map will contain the relevant percentiles as specified by HistogramPercentiles

                                              func (*SimpleCounter) FullKey

                                              func (s *SimpleCounter) FullKey() string

                                                FullKey is part of the Counter interace

                                                func (*SimpleCounter) GetType

                                                func (s *SimpleCounter) GetType() Type

                                                  GetType is part of the Counter interface

                                                  func (*SimpleCounter) GetValues

                                                  func (s *SimpleCounter) GetValues() []float64

                                                    GetValues is part of the Counter interface

                                                    type Stopper

                                                    type Stopper struct {
                                                    	Key    string
                                                    	Start  time.Time
                                                    	Client Client
                                                    }

                                                      Stopper calls Client.BumpSum and Client.BumpHistogram when End'ed

                                                      func (*Stopper) End

                                                      func (s *Stopper) End()

                                                        End the Stopper

                                                        type Type

                                                        type Type int

                                                          Type is the type of aggregation of apply

                                                          const (
                                                          	AggregateAvg Type = iota
                                                          	AggregateSum
                                                          	AggregateHistogram
                                                          )