improve docs

add tests

Author: platinummonkey

docs/assets/moving_percentile_reference.pdf

@@ -152,3 +152,6 @@ dialOption := grpc.WithUnaryInterceptor(
     ),
 )
 ```
+
+---
+[References used can be found here](_references.md)

docs/content/_index.md

@@ -0,0 +1,3 @@
+# References Used
+1. Original Java implementation - Netflix - https://github.com/netflix/concurrency-limits/
+1. Windowless Moving Percentile - Martin Jambon - https://mjambon.com/2016-07-23-moving-percentile/

docs/content/_references.md

@@ -6,6 +6,9 @@ import (
 	"sync"
 )
 
+// SimpleExponentialMovingAverage implements a simple exponential moving average
+// this implementation only uses a single alpha value to determine warm-up time and provides a mean
+// approximation
 type SimpleExponentialMovingAverage struct {
 	alpha        float64
 	initialAlpha float64
@@ -17,6 +20,7 @@ type SimpleExponentialMovingAverage struct {
 	mu sync.RWMutex
 }
 
+// NewSimpleExponentialMovingAverage creates a new simple moving average
 func NewSimpleExponentialMovingAverage(
 	alpha float64,
 ) (*SimpleExponentialMovingAverage, error) {
@@ -31,6 +35,8 @@ func NewSimpleExponentialMovingAverage(
 	}, nil
 }
 
+// Add a single sample and update the internal state.
+// returns true if the internal state was updated, also return the current value.
 func (m *SimpleExponentialMovingAverage) Add(value float64) (float64, bool) {
 	m.mu.Lock()
 	defer m.mu.Unlock()
@@ -56,12 +62,14 @@ func (m *SimpleExponentialMovingAverage) add(value float64) (float64, bool) {
 	return m.value, changed
 }
 
+// Get the current value.
 func (m *SimpleExponentialMovingAverage) Get() float64 {
 	m.mu.RLock()
 	defer m.mu.RUnlock()
 	return m.value
 }
 
+// Reset the internal state as if no samples were ever added.
 func (m *SimpleExponentialMovingAverage) Reset() {
 	m.mu.Lock()
 	m.seenSamples = 0
@@ -70,6 +78,7 @@ func (m *SimpleExponentialMovingAverage) Reset() {
 	m.mu.Unlock()
 }
 
+// Update will update the value given an operation function
 func (m *SimpleExponentialMovingAverage) Update(operation func(value float64) float64) {
 	m.mu.Lock()
 	defer m.mu.Unlock()

measurements/moving_average.go

@@ -0,0 +1,24 @@
+package measurements
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+)
+
+func TestSimpleExponentialMovingAverage(t *testing.T) {
+	t.Parallel()
+	asrt := assert.New(t)
+	m, err := NewSimpleExponentialMovingAverage(0.05)
+	asrt.NoError(err)
+	asrt.NotNil(m)
+
+	asrt.Equal(float64(0), m.Get())
+	m.Add(10)
+	asrt.Equal(float64(10), m.Get())
+	m.Add(11)
+	asrt.Equal(float64(10.5), m.Get())
+	m.Add(11)
+	m.Add(11)
+	asrt.Equal(float64(10.75), m.Get())
+}

measurements/moving_average_test.go

@@ -5,16 +5,18 @@ import (
 	"sync"
 )
 
+// SimpleMovingVariance implements a simple moving variance calculation based on the simple moving average.
 type SimpleMovingVariance struct {
 	average  *SimpleExponentialMovingAverage
 	variance *SimpleExponentialMovingAverage
 
 	stdev      float64 // square root of the estimated variance
-	normalized float64 // (signal - mean) / stdev
+	normalized float64 // (input - mean) / stdev
 
 	mu sync.RWMutex
 }
 
+// NewSimpleMovingVariance will create a new exponential moving variance approximation based on the SimpleMovingAverage
 func NewSimpleMovingVariance(
 	alphaAverage float64,
 	alphaVariance float64,
@@ -33,6 +35,8 @@ func NewSimpleMovingVariance(
 	}, nil
 }
 
+// Add a single sample and update the internal state.
+// returns true if the internal state was updated, also return the current value.
 func (m *SimpleMovingVariance) Add(value float64) (float64, bool) {
 	m.mu.Lock()
 	defer m.mu.Unlock()
@@ -50,7 +54,7 @@ func (m *SimpleMovingVariance) Add(value float64) (float64, bool) {
 		// edge case
 		normalized = (value - mean) / stdev
 	}
-	//fmt.Printf("\tMV add: value=%0.5f mean=%0.5f variance=%0.5f stdev=%0.5f normalized=%0.5f\n", value, mean, variance, stdev, normalized)
+
 	if stdev != m.stdev || normalized != m.normalized {
 		changed = true
 	}
@@ -59,12 +63,14 @@ func (m *SimpleMovingVariance) Add(value float64) (float64, bool) {
 	return stdev, changed
 }
 
+// Get the current value.
 func (m *SimpleMovingVariance) Get() float64 {
 	m.mu.RLock()
 	defer m.mu.RUnlock()
 	return m.variance.Get()
 }
 
+// Reset the internal state as if no samples were ever added.
 func (m *SimpleMovingVariance) Reset() {
 	m.mu.Lock()
 	m.average.Reset()
@@ -74,6 +80,7 @@ func (m *SimpleMovingVariance) Reset() {
 	m.mu.Unlock()
 }
 
+// Update will update the value given an operation function
 func (m *SimpleMovingVariance) Update(operation func(value float64) float64) {
 	m.mu.Lock()
 	defer m.mu.Unlock()

measurements/moving_variance.go

@@ -0,0 +1,31 @@
+package measurements
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+)
+
+func TestSimpleMovingVariance(t *testing.T) {
+	t.Parallel()
+	asrt := assert.New(t)
+	m, err := NewSimpleMovingVariance(0.05, 0.05)
+	asrt.NoError(err)
+	asrt.NotNil(m)
+
+	// initial condition
+	asrt.Equal(float64(0), m.Get())
+	// warmup first sample
+	m.Add(10)
+	asrt.Equal(float64(0), m.Get())
+	// first variance reading is expected to be 1 here
+	m.Add(11)
+	asrt.Equal(float64(1), m.Get())
+	m.Add(10)
+	m.Add(11)
+	asrt.InDelta(float64(0.5648), m.Get(), 0.00005)
+	m.Add(20)
+	m.Add(100)
+	m.Add(30)
+	asrt.InDelta(float64(1295.7841), m.Get(), 0.00005)
+}

measurements/moving_variance_test.go

@@ -5,8 +5,12 @@ import (
 	"sync"
 )
 
-// Much credit goes to here: https://mjambon.com/2016-07-23-moving-percentile/
-
+// WindowlessMovingPercentile implements a moving percentile.
+// This implementation uses a windowless calculation that while not strictly always accurate,
+// provides a very close estimation in O(1) time and space.
+// Much credit goes to Martin Jambon here: https://mjambon.com/2016-07-23-moving-percentile/
+// a copy can be found in github.com/platinummonkey/go-concurrency-limits/docs/assets/moving_percentile_reference.pdf
+// and this is a port of the OCaml implementation provided in that reference.
 type WindowlessMovingPercentile struct {
 	p            float64
 	deltaInitial float64
@@ -21,9 +25,16 @@ type WindowlessMovingPercentile struct {
 	mu sync.RWMutex
 }
 
+// NewWindowlessMovingPercentile creates a new Windowless Moving Percentile
+// p - percentile requested, accepts (0,1)
+// deltaInitial - the initial delta value, here 0 is acceptable if you expect it to be rather stable at start, otherwise
+//                choose a larger value. This would be estimated: `delta := stdev * r` where `r` is a user chosen
+//                constant. Good values are generally from 0.001 to 0.01
+// movingAvgAlphaAvg - this is the alpha value for the simple moving average. A good start is 0.05. Accepts [0,1]
+// movingVarianceAlphaAvg - this is the alpha value for the simple moving variance. A good start is 0.05. Accepts [0,1]
 func NewWindowlessMovingPercentile(
-	p float64,
-	delta float64,
+	p float64, // percentile requested
+	deltaInitial float64,
 	movingAvgAlphaAvg float64,
 	movingVarianceAlphaVar float64,
 ) (*WindowlessMovingPercentile, error) {
@@ -42,8 +53,8 @@ func NewWindowlessMovingPercentile(
 	return &WindowlessMovingPercentile{
 		p:            p,
 		q:            q,
-		deltaInitial: delta,
-		delta:        delta,
+		deltaInitial: deltaInitial,
+		delta:        deltaInitial,
 		deltaState:   variance,
 	}, nil
 }