README
¶
go-peak
Overview
go-peak is a Go package providing a generic data type that tracks the maximum and minimum peak values within a specific period of time.
Background
go-peak was originally designed for Prometheus monitoring to catch the peaks between scraping. For example, suppose the scraping interval is configured to one minute, and a Gauge metric spikes immediately after a scraping. If this Gauge value had dropped by the next scraping, that spike value would not be detected. If there are secondary metrics that report the maximum and/or minimum values for the last 1 minute, these peaks will be able to be detected.
Usage
import (
"fmt"
"time"
"github.com/tunabay/go-peak"
)
func main() {
// uint32 Value that tracks the maximum/minimum in last 1 sec, with the
// initial value 1000.
v := peak.New[uint32](time.Second, 1000)
// Add, Sub, and Set change the value.
time.Sleep(time.Second / 4) // [0.25s]
v.Add(500) // [0.25s] 1500
time.Sleep(time.Second / 4) // [0.50s]
v.Sub(700) // [0.50s] 800
time.Sleep(time.Second / 4) // [0.75s]
v.Set(300) // [0.75s] 300
time.Sleep(time.Second / 4) // [1.00s]
// Get the current value and maximum/minimum values in last 1 sec.
cur, min, max := v.Get()
fmt.Printf("cur: %3v\n", cur)
fmt.Printf("min: %3v\n", min)
fmt.Printf("max: %3v\n", max)
}
Limitation
- It uses the new Go generics syntaxes and requires Go v1.18 or higher.
- The detection period is not accurate. For example, a report for the last one second may contain a maximum value at 1.001 seconds ago. This is because not all individual changes are recorded, but at a resolution of about 1/128 to 1/256 of the reporting period.
Documentation
¶
Overview ¶
Package peak provides a generic data type that tracks the maximum and minimum peak values within the specific period of time.
Example (Usage) ¶
// Value that tracks the maximum/minimum in last 1 sec, with the initial
// value 1000.
v := peak.New[uint32](time.Second, 1000)
// Add, Sub, and Set change the value.
time.Sleep(time.Millisecond * 250) // [0.25s]
v.Add(300) // [0.25s] 1300
time.Sleep(time.Millisecond * 250) // [0.50s]
v.Sub(1100) // [0.50s] 200
time.Sleep(time.Millisecond * 250) // [0.75s]
v.Set(900) // [0.75s] 900
time.Sleep(time.Millisecond * 740) // [1.49s]
// Get the current value and maximum/minimum values in last 1 sec.
cur, min, max := v.Get()
fmt.Printf("cur: %3v\n", cur)
fmt.Printf("min: %3v\n", min)
fmt.Printf("max: %3v\n", max)
Output: cur: 900 min: 200 max: 900
Index ¶
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Number ¶
type Number interface {
constraints.Integer | constraints.Float
}
Number is a constraint that permits any integer and floating point types.
type Value ¶
type Value[T Number] struct { // contains filtered or unexported fields }
Value represents a value that tracks the maximum and minimum values over the last period of time. Safe for concurrent use from multiple goroutines. Do not copy the value. The zero value does not work, so always need to be created by New().
Example ¶
v := peak.New[uint16](time.Millisecond*500, 100)
v.Sub(50) // 0.0s: 100 -> 50
time.Sleep(time.Millisecond * 200) // 0.0s -> 0.2s
v.Add(30) // 0.2s: 50 -> 80
time.Sleep(time.Millisecond * 200) // 0.2s -> 0.4s
v.Set(250) // 0.4s: 80 -> 250
v.Sub(50) // 0.4s: 250 -> 200
time.Sleep(time.Millisecond * 200) // 0.4s -> 0.6s
cur, min, max := v.Get() // min/max within 0.1s .. 0.5s
fmt.Printf("cur: %3v\n", cur)
fmt.Printf("min: %3v\n", min)
fmt.Printf("max: %3v\n", max)
Output: cur: 200 min: 80 max: 250
func New ¶
New creates and returns a Value with the specified tracking period and the initial value. It panics if the period is 0 or negative. Also, if the period is less than 2^20 ns (about 1.05ms), it is rounded up to that value. Perhaps, it does not make sense to use such a very short period.
func (*Value[T]) Add ¶
func (v *Value[T]) Add(delta T) T
Add adds delta to the Value v and returns the new value. It is legal to pass a negative delta for signed integers and floating point types. This has the same result as Sub. It is also possible to subtract an unsigned integer by adding ^(delta-1) in the same manner as for atomic.AddUint32/64.
func (*Value[T]) Get ¶
func (v *Value[T]) Get() (cur, min, max T)
Get returns the current value and the maximum / minimum values within the period.
Source Files