bps

Documentation

Overview

Package bps provides gauges for calculating the Bytes Per Second transfer rate of data streams.

Index

• func Watch(ctx context.Context, g Gauge, f SampleFunc, interval time.Duration)
• type Gauge
  • func NewSMA(maxSamples int) Gauge
• type SampleFunc

Functions

func Watch

func Watch(ctx context.Context, g Gauge, f SampleFunc, interval time.Duration)

Watch will periodically call the given SampleFunc to sample the progress of a monitored stream and update the given gauge. SampleFunc should return the total number of bytes transferred by the stream since it started.

Watch is a blocking call and should typically be called in a new goroutine. To prevent the goroutine from leaking, make sure to cancel the given context once the stream is completed or canceled.

Types

type Gauge

type Gauge interface {
	// Sample adds a new sample of the progress of the monitored stream.
	Sample(t time.Time, n int64)

	// BPS returns the calculated Bytes Per Second rate of the monitored stream.
	BPS() float64
}

Gauge is the common interface for all BPS gauges in this package. Given a set of samples over time, each gauge type can be used to measure the Bytes Per Second transfer rate of a data stream.

All samples must monotonically increase in timestamp and value. Each sample should represent the total number of bytes sent in a stream, rather than accounting for the number sent since the last sample.

To ensure a gauge can report progress as quickly as possible, take an initial sample when your stream first starts.

All gauge implementations are safe for concurrent use.

func NewSMA

func NewSMA(maxSamples int) Gauge

NewSMA returns a gauge that uses a Simple Moving Average with the given number of samples to measure the bytes per second of a byte stream.

BPS is computed using the timestamp of the most recent and oldest sample in the sample buffer. When a new sample is added, the oldest sample is dropped if the sample count exceeds maxSamples.

The gauge does not account for any latency in arrival time of new samples or the desired window size. Any variance in the arrival of samples will result in a BPS measurement that is correct for the submitted samples, but over a varying time window.

maxSamples should be equal to 1 + (window size / sampling interval) where window size is the number of seconds over which the moving average is smoothed and sampling interval is the number of seconds between each sample.

For example, if you want a five second window, sampling once per second, maxSamples should be 1 + 5/1 = 6.

type SampleFunc

type SampleFunc func() (n int64)

SampleFunc is used by Watch to take periodic samples of a monitored stream.