timeseries

README

go-time-series

Time series implementation in Go.

It is used in go-trending as a backend for a trending algorithm. The time series supports storing counts at different granularities, e.g. seconds, minutes, hours, ....
In case of go-trending the time series is configured to have recent data available at small granularity, i.e. the recent 60 seconds, and historical data available at large granularity, i.e. the last few hours, days of data.

A redis backend is planned.

• Simple interface
• Store time series data at different granularities
• Use your own clock implementation, e.g. for testing or similar

Examples

Creating a time series with default settings

The default settings use time.Now() as clock and time.Second * 60, time.Minute * 60 and time.Hour * 24 as granularities.

import "github.com/codesuki/go-time-series"

...

ts, err := timeseries.NewTimeSeries()
if err != nil {
    // handle error
}

Creating a customized time series

You can specify the clock and/or granularities to use. A clock must implement the timeseries.Clock interface.

import "github.com/codesuki/go-time-series"

...
type clock struct {}
func (c *clock) Now() {
    return time.Time{} // always returns the zero time
}
var myClock clock
...

ts, err := timeseries.NewTimeSeries(
    timeseries.WithGranularities(
        []timeseries.Granularity{
            {Granularity: time.Second, Count: 60},
            {Granularity: time.Minute, Count: 60},
            {Granularity: time.Hour, Count: 24},
            {Granularity: time.Hour * 24, Count: 7},
        }),
    timeseries.WithClock(&myClock),
)
if err != nil {
    // handle error
}

Filling the time series

To fill the time series with counts, e.g. events, you can use two different functions.

import "github.com/codesuki/go-time-series"

...

ts, err := timeseries.NewTimeSeries()
if err != nil {
    // handle error
}

ts.Increase(2) // adds 2 to the counter at the current time
ts.IncreaseAtTime(3, time.Now().Add(-2 * time.Minute)) // adds 3 to the counter 2 minutes ago

Querying the time series

The Range() function takes 2 arguments, i.e. the start and end of a time span. Recent() is a small helper function that just uses clock.Now() as end in Range. Please refer to the documentation for how Range() works exactly. There are some details depending on what range you query and what range is available.

import "github.com/codesuki/go-time-series"

...

ts, err := timeseries.NewTimeSeries()
if err != nil {
    // handle error
}

ts.Increase(2) // adds 2 to the counter at the current time
// 1s passes
ts.Increase(3)
// 1s passes

ts.Recent(5 * time.Second) // returns 5

ts.Range(time.Now().Add(-5 * time.Second), time.Now()) // returns 5

Documentation

GoDoc is located here

License

go-time-series is MIT licensed.

Documentation

Index

• Variables
• type Clock
• type Granularity
• type Option
  • func WithClock(c Clock) Option
  • func WithGranularities(g []Granularity) Option
• type TimeSeries
  • func NewTimeSeries(os ...Option) (*TimeSeries, error)
  • func (t *TimeSeries) Increase(amount int)
  • func (t *TimeSeries) IncreaseAtTime(amount int, time time.Time)
  • func (t *TimeSeries) Range(start, end time.Time) (float64, error)
  • func (t *TimeSeries) Recent(duration time.Duration) (float64, error)

Variables

var (
	// ErrBadRange indicates that the given range is invalid. Start should always be <= End
	ErrBadRange = errors.New("timeseries: range is invalid")
	// ErrBadGranularities indicates that the provided granularities are not strictly increasing
	ErrBadGranularities = errors.New("timeseries: granularities must be strictly increasing and non empty")
	// ErrRangeNotCovered indicates that the provided range lies outside the time series
	ErrRangeNotCovered = errors.New("timeseries: range is not convered")
)

Types

type Clock

type Clock interface {
	Now() time.Time
}

Clock specifies the needed time related functions used by the time series. To use a custom clock implement the interface and pass it to the time series constructor. The default clock uses time.Now()

type Granularity

type Granularity struct {
	Granularity time.Duration
	Count       int
}

Granularity describes the granularity for one level of the time series. Count cannot be 0.

type Option

type Option func(*options)

Option configures the time series.

func WithClock

func WithClock(c Clock) Option

WithClock returns a Option that sets the clock used by the time series.

func WithGranularities

func WithGranularities(g []Granularity) Option

WithGranularities returns a Option that sets the granularites used by the time series.

type TimeSeries

type TimeSeries struct {
	sync.RWMutex
	// contains filtered or unexported fields
}

func NewTimeSeries

func NewTimeSeries(os ...Option) (*TimeSeries, error)

NewTimeSeries creates a new time series with the provided options. If no options are provided default values are used.

func (*TimeSeries) Increase

func (t *TimeSeries) Increase(amount int)

Increase adds amount at current time.

func (*TimeSeries) IncreaseAtTime

func (t *TimeSeries) IncreaseAtTime(amount int, time time.Time)

IncreaseAtTime adds amount at a specific time.

func (*TimeSeries) Range

func (t *TimeSeries) Range(start, end time.Time) (float64, error)

Range returns the sum over the given range [start, end). ErrBadRange is returned if start is after end. ErrRangeNotCovered is returned if the range lies outside the time series.

func (*TimeSeries) Recent

func (t *TimeSeries) Recent(duration time.Duration) (float64, error)

Recent returns the sum over [now-duration, now).