rolling

README

Rolling

This go package provides rolling window aggregation container that calculates basic statistical metrics for a float64 time series data.

Please note that rolling window implementation provided by this package is not thread-safe. You need to provide your own synchronization if you want to use it in concurrent environment.

The idea is to calculate metrics on the fly without O(n) aggregation every time a new data point is added to the time series.

We still have to keep all values in memory for min/max calculation with eviction, but we don't have to iterate over all of them every time we want to calculate a metric.

Please note that reported metrics are calculated at the time last value was added. If you want to force-evict old values, call Evict before accessing metric methods.

Currently supported metrics are:

• Sum - sum of all values in the window.
• Count - total number of values in the window.
• Min - minimal value.
• Max - maximal value.
• Avg - average value.
• Mid - middle value (average of first and last values).
• First - first value in the window.
• Last - last value in the window.

Example

	w := NewWindow(6, time.Second)
	w.Add(1)
	w.Add(2)
	time.Sleep(time.Second)
	w.Add(3)
	w.Add(4)
	w.Add(5)
	w.Add(6)
	w.Add(7)
	fmt.Println(w.Min(), w.Avg(), w.Max())
	// Output: 3 5 7

Documentation

Index

• type Window
  • func NewWindow(maxSize int64, duration time.Duration) *Window
  • func (w *Window) Add(value float64)
  • func (w *Window) AddAt(value float64, at time.Time)
  • func (w *Window) Avg() float64
  • func (w *Window) Count() int64
  • func (w *Window) Evict()
  • func (w *Window) First() float64
  • func (w *Window) Last() float64
  • func (w *Window) Max() float64
  • func (w *Window) Mid() float64
  • func (w *Window) Min() float64
  • func (w *Window) Sum() float64

Examples

• NewWindow

Types

type Window

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

func NewWindow

func NewWindow(maxSize int64, duration time.Duration) *Window

Example

w := NewWindow(6, time.Second)
w.Add(1)
w.Add(2)
time.Sleep(time.Second)
w.Add(3)
w.Add(4)
w.Add(5)
w.Add(6)
w.Add(7)
fmt.Println(w.Min(), w.Avg(), w.Max())

Output:

3 5 7

func (*Window) Add

func (w *Window) Add(value float64)

Add new value to the tail of the window and evict values from head if cnt > maxSize, or if value's timestamp is older than window duration.

func (*Window) AddAt

func (w *Window) AddAt(value float64, at time.Time)

AddAt adds new value to the tail of the window with a specified timestamp. Usually you need Add method. This one main purpose is to add past values on service restart. If you attempt to add value with timestamp older than the last one, it will be discarded.

func (*Window) Avg

func (w *Window) Avg() float64

Average value in the window. NaN if window is empty.

func (*Window) Count

func (w *Window) Count() int64

Count of the number of values in the window.

func (*Window) Evict

func (w *Window) Evict()

Evict clears outdated values from the window. This is useful if your updates do not come very often and you want to get some metric after some time from last Add and don't want vaules that are older than window duration to affect the result.

func (*Window) First

func (w *Window) First() float64

First returns first value of the window. NaN if window is empty.

func (*Window) Last

func (w *Window) Last() float64

Last returns last value in the window. NaN if window is empty.

func (*Window) Max

func (w *Window) Max() float64

Max value in the window. NaN if window is empty.

func (*Window) Mid

func (w *Window) Mid() float64

Mid returns average between first and last values in the window. NaN if window is empty.

func (*Window) Min

func (w *Window) Min() float64

Min value in the window. NaN if window is empty.

func (*Window) Sum

func (w *Window) Sum() float64

Sum of all values in the window. NaN if window is empty.