Documentation

Overview

    Package stats is a wrapper for expvar. It addtionally exports new types that can be used to track performance. It also provides a callback hook that allows a program to export the variables using methods other than /debug/vars. All variables support a String function that is expected to return a JSON representation of the variable. Any function named Add will add the specified number to the variable. Any function named Counts returns a map of counts that can be used by Rates to track rates over time.

    Index

    Constants

    This section is empty.

    Variables

    This section is empty.

    Functions

    func Publish

    func Publish(name string, v expvar.Var)

      Publish is expvar.Publish+hook

      func PublishJSONFunc

      func PublishJSONFunc(name string, f func() string)

        PublishJSONFunc publishes any function that returns a JSON string as a variable. The string is sent to expvar as is.

        func Register

        func Register(nvh NewVarHook)

          Register allows you to register a callback function that will be called whenever a new stats variable gets created. This can be used to build alternate methods of exporting stats variables.

          func RegisterPushBackend

          func RegisterPushBackend(name string, backend PushBackend)

            RegisterPushBackend allows modules to register PushBackend implementations. Should be called on init().

            Types

            type CountTracker

            type CountTracker interface {
            	// Counts returns a map which maps each category to a count.
            	// Subsequent calls must return a monotonously increasing count for the same
            	// category.
            	// Optionally, an implementation may include the "All" category which has
            	// the total count across all categories (e.g. timing.go does this).
            	Counts() map[string]int64
            }

              CountTracker defines the interface that needs to be supported by a variable for being tracked by Rates.

              func CounterForDimension

              func CounterForDimension(mt MultiTracker, dimension string) CountTracker

                CounterForDimension returns a CountTracker for the provided dimension. It will panic if the dimension isn't a legal label for mt.

                type Counters

                type Counters struct {
                	// contains filtered or unexported fields
                }

                  Counters is similar to expvar.Map, except that it doesn't allow floats. In addition, it provides a Counts method which can be used for tracking rates.

                  func NewCounters

                  func NewCounters(name string, tags ...string) *Counters

                    NewCounters create a new Counters instance. If name is set, the variable gets published. The functional also accepts an optional list of tags that pre-creates them initialized to 0.

                    func (*Counters) Add

                    func (c *Counters) Add(name string, value int64)

                      Add adds a value to a named counter.

                      func (*Counters) Counts

                      func (c *Counters) Counts() map[string]int64

                        Counts returns a copy of the Counters' map.

                        func (*Counters) Reset

                        func (c *Counters) Reset()

                          Reset resets all counter values

                          func (*Counters) Set

                          func (c *Counters) Set(name string, value int64)

                            Set sets the value of a named counter.

                            func (*Counters) String

                            func (c *Counters) String() string

                              String is used by expvar.

                              type CountersFunc

                              type CountersFunc func() map[string]int64

                                CountersFunc converts a function that returns a map of int64 as an expvar.

                                func (CountersFunc) Counts

                                func (f CountersFunc) Counts() map[string]int64

                                  Counts returns a copy of the Counters' map.

                                  func (CountersFunc) String

                                  func (f CountersFunc) String() string

                                    String is used by expvar.

                                    type Duration

                                    type Duration struct {
                                    	// contains filtered or unexported fields
                                    }

                                      Duration exports a time.Duration

                                      func NewDuration

                                      func NewDuration(name string) *Duration

                                        NewDuration returns a new Duration

                                        func (*Duration) Add

                                        func (v *Duration) Add(delta time.Duration)

                                          Add adds the provided value to the Duration

                                          func (*Duration) Get

                                          func (v *Duration) Get() time.Duration

                                            Get returns the value

                                            func (*Duration) Set

                                            func (v *Duration) Set(value time.Duration)

                                              Set sets the value

                                              func (*Duration) String

                                              func (v *Duration) String() string

                                                String is the implementation of expvar.var

                                                type DurationFunc

                                                type DurationFunc func() time.Duration

                                                  DurationFunc converts a function that returns an time.Duration as an expvar.

                                                  func (DurationFunc) String

                                                  func (f DurationFunc) String() string

                                                    String is the implementation of expvar.var

                                                    type Float

                                                    type Float struct {
                                                    	// contains filtered or unexported fields
                                                    }

                                                      Float is expvar.Float+Get+hook

                                                      func NewFloat

                                                      func NewFloat(name string) *Float

                                                        NewFloat creates a new Float and exports it.

                                                        func (*Float) Add

                                                        func (v *Float) Add(delta float64)

                                                          Add adds the provided value to the Float

                                                          func (*Float) Get

                                                          func (v *Float) Get() float64

                                                            Get returns the value

                                                            func (*Float) Set

                                                            func (v *Float) Set(value float64)

                                                              Set sets the value

                                                              func (*Float) String

                                                              func (v *Float) String() string

                                                                String is the implementation of expvar.var

                                                                type FloatFunc

                                                                type FloatFunc func() float64

                                                                  FloatFunc converts a function that returns a float64 as an expvar.

                                                                  func (FloatFunc) String

                                                                  func (f FloatFunc) String() string

                                                                    String is the implementation of expvar.var

                                                                    type Histogram

                                                                    type Histogram struct {
                                                                    	// contains filtered or unexported fields
                                                                    }

                                                                      Histogram tracks counts and totals while splitting the counts under different buckets using specified cutoffs.

                                                                      func NewGenericHistogram

                                                                      func NewGenericHistogram(name string, cutoffs []int64, labels []string, countLabel, totalLabel string) *Histogram

                                                                        NewGenericHistogram creates a histogram where all the labels are supplied by the caller. The number of labels has to be one more than the number of cutoffs because the last label captures everything that exceeds the highest cutoff.

                                                                        func NewHistogram

                                                                        func NewHistogram(name string, cutoffs []int64) *Histogram

                                                                          NewHistogram creates a histogram with auto-generated labels based on the cutoffs. The buckets are categorized using the following criterion: cutoff[i-1] < value <= cutoff[i]. Anything higher than the highest cutoff is labeled as "inf".

                                                                          func (*Histogram) Add

                                                                          func (h *Histogram) Add(value int64)

                                                                            Add adds a new measurement to the Histogram.

                                                                            func (*Histogram) Buckets

                                                                            func (h *Histogram) Buckets() []int64

                                                                              Buckets returns a snapshot of the current values in all buckets.

                                                                              func (*Histogram) Count

                                                                              func (h *Histogram) Count() (count int64)

                                                                                Count returns the number of times Add has been called.

                                                                                func (*Histogram) CountLabel

                                                                                func (h *Histogram) CountLabel() string

                                                                                  CountLabel returns the count label that was set when this Histogram was created.

                                                                                  func (*Histogram) Counts

                                                                                  func (h *Histogram) Counts() map[string]int64

                                                                                    Counts returns a map from labels to the current count in the Histogram for that label.

                                                                                    func (*Histogram) Cutoffs

                                                                                    func (h *Histogram) Cutoffs() []int64

                                                                                      Cutoffs returns the cutoffs that were set when this Histogram was created.

                                                                                      func (*Histogram) Labels

                                                                                      func (h *Histogram) Labels() []string

                                                                                        Labels returns the labels that were set when this Histogram was created.

                                                                                        func (*Histogram) MarshalJSON

                                                                                        func (h *Histogram) MarshalJSON() ([]byte, error)

                                                                                          MarshalJSON returns a JSON representation of the Histogram. Note that sum of all buckets may not be equal to the total temporarily, because Add() increments bucket and total with two atomic operations.

                                                                                          func (*Histogram) String

                                                                                          func (h *Histogram) String() string

                                                                                            String returns a string representation of the Histogram. Note that sum of all buckets may not be equal to the total temporarily, because Add() increments bucket and total with two atomic operations.

                                                                                            func (*Histogram) Total

                                                                                            func (h *Histogram) Total() (total int64)

                                                                                              Total returns the sum of all values that have been added to this Histogram.

                                                                                              func (*Histogram) TotalLabel

                                                                                              func (h *Histogram) TotalLabel() string

                                                                                                TotalLabel returns the total label that was set when this Histogram was created.

                                                                                                type Int

                                                                                                type Int struct {
                                                                                                	// contains filtered or unexported fields
                                                                                                }

                                                                                                  Int is expvar.Int+Get+hook

                                                                                                  func NewInt

                                                                                                  func NewInt(name string) *Int

                                                                                                    NewInt returns a new Int

                                                                                                    func (*Int) Add

                                                                                                    func (v *Int) Add(delta int64)

                                                                                                      Add adds the provided value to the Int

                                                                                                      func (*Int) Get

                                                                                                      func (v *Int) Get() int64

                                                                                                        Get returns the value

                                                                                                        func (*Int) Set

                                                                                                        func (v *Int) Set(value int64)

                                                                                                          Set sets the value

                                                                                                          func (*Int) String

                                                                                                          func (v *Int) String() string

                                                                                                            String is the implementation of expvar.var

                                                                                                            type IntFunc

                                                                                                            type IntFunc func() int64

                                                                                                              IntFunc converts a function that returns an int64 as an expvar.

                                                                                                              func (IntFunc) String

                                                                                                              func (f IntFunc) String() string

                                                                                                                String is the implementation of expvar.var

                                                                                                                type JSONFunc

                                                                                                                type JSONFunc func() string

                                                                                                                  JSONFunc is the public type for a single function that returns json directly.

                                                                                                                  func (JSONFunc) String

                                                                                                                  func (f JSONFunc) String() string

                                                                                                                    String is the implementation of expvar.var

                                                                                                                    type MultiCounters

                                                                                                                    type MultiCounters struct {
                                                                                                                    	Counters
                                                                                                                    	// contains filtered or unexported fields
                                                                                                                    }

                                                                                                                      MultiCounters is a multidimensional Counters implementation where names of categories are compound names made with joining multiple strings with '.'.

                                                                                                                      func NewMultiCounters

                                                                                                                      func NewMultiCounters(name string, labels []string) *MultiCounters

                                                                                                                        NewMultiCounters creates a new MultiCounters instance, and publishes it if name is set.

                                                                                                                        func (*MultiCounters) Add

                                                                                                                        func (mc *MultiCounters) Add(names []string, value int64)

                                                                                                                          Add adds a value to a named counter. len(names) must be equal to len(Labels)

                                                                                                                          func (*MultiCounters) Labels

                                                                                                                          func (mc *MultiCounters) Labels() []string

                                                                                                                            Labels returns the list of labels.

                                                                                                                            func (*MultiCounters) Set

                                                                                                                            func (mc *MultiCounters) Set(names []string, value int64)

                                                                                                                              Set sets the value of a named counter. len(names) must be equal to len(Labels)

                                                                                                                              type MultiCountersFunc

                                                                                                                              type MultiCountersFunc struct {
                                                                                                                              	CountersFunc
                                                                                                                              	// contains filtered or unexported fields
                                                                                                                              }

                                                                                                                                MultiCountersFunc is a multidimensional CountersFunc implementation where names of categories are compound names made with joining multiple strings with '.'. Since the map is returned by the function, we assume it's in the right format (meaning each key is of the form 'aaa.bbb.ccc' with as many elements as there are in Labels).

                                                                                                                                func NewMultiCountersFunc

                                                                                                                                func NewMultiCountersFunc(name string, labels []string, f CountersFunc) *MultiCountersFunc

                                                                                                                                  NewMultiCountersFunc creates a new MultiCountersFunc mapping to the provided function.

                                                                                                                                  func (*MultiCountersFunc) Labels

                                                                                                                                  func (mcf *MultiCountersFunc) Labels() []string

                                                                                                                                    Labels returns the list of labels.

                                                                                                                                    type MultiTimings

                                                                                                                                    type MultiTimings struct {
                                                                                                                                    	Timings
                                                                                                                                    	// contains filtered or unexported fields
                                                                                                                                    }

                                                                                                                                      MultiTimings is meant to tracks timing data by categories as well as histograms. The names of the categories are compound names made with joining multiple strings with '.'.

                                                                                                                                      func NewMultiTimings

                                                                                                                                      func NewMultiTimings(name string, labels []string) *MultiTimings

                                                                                                                                        NewMultiTimings creates a new MultiTimings object.

                                                                                                                                        func (*MultiTimings) Add

                                                                                                                                        func (mt *MultiTimings) Add(names []string, elapsed time.Duration)

                                                                                                                                          Add will add a new value to the named histogram.

                                                                                                                                          func (*MultiTimings) Cutoffs

                                                                                                                                          func (mt *MultiTimings) Cutoffs() []int64

                                                                                                                                            Cutoffs returns the cutoffs used in the component histograms. Do not change the returned slice.

                                                                                                                                            func (*MultiTimings) Labels

                                                                                                                                            func (mt *MultiTimings) Labels() []string

                                                                                                                                              Labels returns descriptions of the parts of each compound category name.

                                                                                                                                              func (*MultiTimings) Record

                                                                                                                                              func (mt *MultiTimings) Record(names []string, startTime time.Time)

                                                                                                                                                Record is a convenience function that records completion timing data based on the provided start time of an event.

                                                                                                                                                type MultiTracker

                                                                                                                                                type MultiTracker interface {
                                                                                                                                                	CountTracker
                                                                                                                                                	Labels() []string
                                                                                                                                                }

                                                                                                                                                  MultiTracker is a CountTracker that tracks counts grouping them by more than one dimension.

                                                                                                                                                  type NewVarHook

                                                                                                                                                  type NewVarHook func(name string, v expvar.Var)

                                                                                                                                                    NewVarHook is the type of a hook to export variables in a different way

                                                                                                                                                    type PushBackend

                                                                                                                                                    type PushBackend interface {
                                                                                                                                                    	// PushAll pushes all stats from expvar to the backend
                                                                                                                                                    	PushAll() error
                                                                                                                                                    }

                                                                                                                                                      PushBackend is an interface for any stats/metrics backend that requires data to be pushed to it. It's used to support push-based metrics backends, as expvar by default only supports pull-based ones.

                                                                                                                                                      type Rates

                                                                                                                                                      type Rates struct {
                                                                                                                                                      	// contains filtered or unexported fields
                                                                                                                                                      }

                                                                                                                                                        Rates is capable of reporting the rate (typically QPS) for any variable that satisfies the CountTracker interface.

                                                                                                                                                        func NewRates

                                                                                                                                                        func NewRates(name string, countTracker CountTracker, samples int, interval time.Duration) *Rates

                                                                                                                                                          NewRates reports rolling rate information for countTracker. samples specifies the number of samples to report, and interval specifies the time interval between samples. The minimum interval is 1 second. If passing the special value of -1s as interval, we don't snapshot. (use this for tests).

                                                                                                                                                          func (*Rates) Get

                                                                                                                                                          func (rt *Rates) Get() (rateMap map[string][]float64)

                                                                                                                                                            Get returns for each category (string) its latest rates (up to X values where X is the configured number of samples of the Rates struct). Rates are ordered from least recent (index 0) to most recent (end of slice).

                                                                                                                                                            func (*Rates) String

                                                                                                                                                            func (rt *Rates) String() string

                                                                                                                                                            func (*Rates) TotalRate

                                                                                                                                                            func (rt *Rates) TotalRate() float64

                                                                                                                                                              TotalRate returns the current total rate (counted across categories).

                                                                                                                                                              type RingInt64

                                                                                                                                                              type RingInt64 struct {
                                                                                                                                                              	// contains filtered or unexported fields
                                                                                                                                                              }

                                                                                                                                                                Ring of int64 values Not thread safe

                                                                                                                                                                func NewRingInt64

                                                                                                                                                                func NewRingInt64(capacity int) *RingInt64

                                                                                                                                                                func (*RingInt64) Add

                                                                                                                                                                func (ri *RingInt64) Add(val int64)

                                                                                                                                                                func (*RingInt64) Values

                                                                                                                                                                func (ri *RingInt64) Values() (values []int64)

                                                                                                                                                                type String

                                                                                                                                                                type String struct {
                                                                                                                                                                	// contains filtered or unexported fields
                                                                                                                                                                }

                                                                                                                                                                  String is expvar.String+Get+hook

                                                                                                                                                                  func NewString

                                                                                                                                                                  func NewString(name string) *String

                                                                                                                                                                    NewString returns a new String

                                                                                                                                                                    func (*String) Get

                                                                                                                                                                    func (v *String) Get() string

                                                                                                                                                                      Get returns the value

                                                                                                                                                                      func (*String) Set

                                                                                                                                                                      func (v *String) Set(value string)

                                                                                                                                                                        Set sets the value

                                                                                                                                                                        func (*String) String

                                                                                                                                                                        func (v *String) String() string

                                                                                                                                                                          String is the implementation of expvar.var

                                                                                                                                                                          type StringFunc

                                                                                                                                                                          type StringFunc func() string

                                                                                                                                                                            StringFunc converts a function that returns an string as an expvar.

                                                                                                                                                                            func (StringFunc) String

                                                                                                                                                                            func (f StringFunc) String() string

                                                                                                                                                                              String is the implementation of expvar.var

                                                                                                                                                                              type StringMap

                                                                                                                                                                              type StringMap struct {
                                                                                                                                                                              	// contains filtered or unexported fields
                                                                                                                                                                              }

                                                                                                                                                                                StringMap is a map of string -> string

                                                                                                                                                                                func NewStringMap

                                                                                                                                                                                func NewStringMap(name string) *StringMap

                                                                                                                                                                                  NewStringMap returns a new StringMap

                                                                                                                                                                                  func (*StringMap) Get

                                                                                                                                                                                  func (v *StringMap) Get(name string) string

                                                                                                                                                                                    Get will return the value, or "" f not set.

                                                                                                                                                                                    func (*StringMap) Set

                                                                                                                                                                                    func (v *StringMap) Set(name, value string)

                                                                                                                                                                                      Set will set a value (existing or not)

                                                                                                                                                                                      func (*StringMap) String

                                                                                                                                                                                      func (v *StringMap) String() string

                                                                                                                                                                                        String is the implementation of expvar.Var

                                                                                                                                                                                        type StringMapFunc

                                                                                                                                                                                        type StringMapFunc func() map[string]string

                                                                                                                                                                                          StringMapFunc is the function equivalent of StringMap

                                                                                                                                                                                          func (StringMapFunc) String

                                                                                                                                                                                          func (f StringMapFunc) String() string

                                                                                                                                                                                            String is used by expvar.

                                                                                                                                                                                            type Timings

                                                                                                                                                                                            type Timings struct {
                                                                                                                                                                                            	// contains filtered or unexported fields
                                                                                                                                                                                            }

                                                                                                                                                                                              Timings is meant to tracks timing data by named categories as well as histograms.

                                                                                                                                                                                              func NewTimings

                                                                                                                                                                                              func NewTimings(name string, categories ...string) *Timings

                                                                                                                                                                                                NewTimings creates a new Timings object, and publishes it if name is set. categories is an optional list of categories to initialize to 0. Categories that aren't initialized will be missing from the map until the first time they are updated.

                                                                                                                                                                                                func (*Timings) Add

                                                                                                                                                                                                func (t *Timings) Add(name string, elapsed time.Duration)

                                                                                                                                                                                                  Add will add a new value to the named histogram.

                                                                                                                                                                                                  func (*Timings) Count

                                                                                                                                                                                                  func (t *Timings) Count() int64

                                                                                                                                                                                                    Count returns the total count for all values.

                                                                                                                                                                                                    func (*Timings) Counts

                                                                                                                                                                                                    func (t *Timings) Counts() map[string]int64

                                                                                                                                                                                                      Counts returns the total count for each value.

                                                                                                                                                                                                      func (*Timings) Cutoffs

                                                                                                                                                                                                      func (t *Timings) Cutoffs() []int64

                                                                                                                                                                                                        Cutoffs returns the cutoffs used in the component histograms. Do not change the returned slice.

                                                                                                                                                                                                        func (*Timings) Histograms

                                                                                                                                                                                                        func (t *Timings) Histograms() (h map[string]*Histogram)

                                                                                                                                                                                                          Histograms returns a map pointing at the histograms.

                                                                                                                                                                                                          func (*Timings) Record

                                                                                                                                                                                                          func (t *Timings) Record(name string, startTime time.Time)

                                                                                                                                                                                                            Record is a convenience function that records completion timing data based on the provided start time of an event.

                                                                                                                                                                                                            func (*Timings) String

                                                                                                                                                                                                            func (t *Timings) String() string

                                                                                                                                                                                                              String is for expvar.

                                                                                                                                                                                                              func (*Timings) Time

                                                                                                                                                                                                              func (t *Timings) Time() int64

                                                                                                                                                                                                                Time returns the total time elapsed for all values.

                                                                                                                                                                                                                Directories

                                                                                                                                                                                                                Path Synopsis
                                                                                                                                                                                                                Package influxdbbackend is useful for publishing metrics to an InfluxDB backend (tested on v0.88).
                                                                                                                                                                                                                Package influxdbbackend is useful for publishing metrics to an InfluxDB backend (tested on v0.88).
                                                                                                                                                                                                                Package promstats contains adapters to publish stats variables to prometheus (http://prometheus.io)
                                                                                                                                                                                                                Package promstats contains adapters to publish stats variables to prometheus (http://prometheus.io)