README
¶
Trend: Small Time-Series Store for Go
Trend stores float64 samples, unsigned counters, and sketches behind a small byte-store interface. It is meant for embedded or service-local time-series data where simple writes, mergeable state, iterator reads, and compact storage are enough.
It keeps recent raw points, can compact older points into buckets, and serializes state with a compact binary format compressed with S2.
- Samples: Last-write-wins float64 values.
- Counters: Grow-only unsigned counter deltas.
- Sketches: Exact recent observations with compact approximate quantiles.
- Reads:
ValuesandRangereturn Go iterators. - Storage: Pluggable stores registered by URI scheme.
Use When
- You need simple local time-series storage inside a Go service.
- You want separate APIs for samples, counters, and sketches.
- You want compact serialized state without running a metrics database.
Not For
- High-cardinality metrics ingestion at Prometheus/TSDB scale.
- Distributed query engines, retention policies, or alerting.
- Interoperable on-disk formats.
Quick Start
package main
import (
"context"
"fmt"
"time"
"github.com/kelindar/trend"
_ "github.com/kelindar/trend/storage/buntdb"
)
func main() {
ctx := context.Background()
db, err := trend.Open("buntdb:///:memory:")
if err != nil {
panic(err)
}
defer db.Close()
now := time.Now()
_ = db.Samples("cpu").Set(ctx, now, 0.42)
_ = db.Counters("requests").Add(ctx, now, 1)
_ = db.Sketches("latency").Add(ctx, now, 12.5)
values, _ := db.Samples("cpu").Values(ctx, now.Add(-time.Minute), now)
for at, value := range values {
fmt.Println(at, value)
}
}
API Highlights
Open(uri string, opts ...Option): Open a registered storage adapter.New(store Store, opts ...Option): Use an existing store implementation.Samples(key).Set(ctx, at, value): Store a float64 sample.Samples(key).Values(ctx, from, to): Iterate raw sample values.Samples(key).Range(ctx, from, to, span, agg): Iterate bucketed sample aggregates.Counters(key).Add(ctx, at, delta): Store an unsigned counter delta.Counters(key).Values(ctx, from, to): Iterate counter values.Counters(key).Range(ctx, from, to, span, agg): Iterate bucketed counter aggregates.Sketches(key).Add(ctx, at, value): Store one finite float64 observation.Sketches(key).Values(ctx, from, to): Iterate sketches at retained resolution.Sketches(key).Range(ctx, from, to, span): Iterate merged sketch buckets.Compact(ctx): Compact old points using the configured window.
Storage
Stores implement a byte-oriented update interface:
type Store interface {
Load(context.Context, string) ([]byte, error)
Update(context.Context, string, func([]byte) ([]byte, error)) error
Delete(context.Context, string) error
Close() error
}
Adapters register by URI scheme. Import the adapter package for registration:
import (
_ "github.com/kelindar/trend/storage/buntdb"
_ "github.com/kelindar/trend/storage/redis"
_ "github.com/kelindar/trend/storage/sqlite"
)
Benchmarks
name time/op ops/s allocs/op
samples/append 327.9 us 3.0K 10
samples/range 177.9 us 5.6K 4
samples/values 95.0 us 10.5K 4
counters/append 286.4 us 3.5K 9
counters/range 100.7 us 9.9K 4
counters/values 78.6 us 12.7K 4
Numbers are from local 10K element DB-backed benchmarks on an Intel i7-13700K.
About
Trend is MIT licensed and maintained by @kelindar.
PRs and issues welcome.
Documentation
¶
Index ¶
- func Register(scheme string, open func(*url.URL) (Store, error))
- type Agg
- type Counters
- func (c Counters) Add(ctx context.Context, at time.Time, delta uint64) error
- func (c Counters) Compact(ctx context.Context) error
- func (c Counters) Range(ctx context.Context, from, to time.Time, span time.Duration, agg Agg) (iter.Seq2[time.Time, float64], error)
- func (c Counters) Values(ctx context.Context, from, to time.Time) (iter.Seq2[time.Time, float64], error)
- type DB
- type Option
- type Samples
- func (s Samples) Compact(ctx context.Context) error
- func (s Samples) Range(ctx context.Context, from, to time.Time, span time.Duration, agg Agg) (iter.Seq2[time.Time, float64], error)
- func (s Samples) Set(ctx context.Context, at time.Time, value float64) error
- func (s Samples) Values(ctx context.Context, from, to time.Time) (iter.Seq2[time.Time, float64], error)
- type Sketch
- type Sketches
- func (h Sketches) Add(ctx context.Context, at time.Time, value float64) error
- func (h Sketches) Compact(ctx context.Context) error
- func (h Sketches) Range(ctx context.Context, from, to time.Time, span time.Duration) (iter.Seq2[time.Time, Sketch], error)
- func (h Sketches) Values(ctx context.Context, from, to time.Time) (iter.Seq2[time.Time, Sketch], error)
- type Store
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
Types ¶
type Counters ¶
type Counters struct {
// contains filtered or unexported fields
}
Counters writes and reads grow-only counters.
type DB ¶
type DB struct {
// contains filtered or unexported fields
}
DB stores time-series samples, counters, and sketches.
type Option ¶
Option configures a DB.
func WithCompaction ¶
WithCompaction enables lossy compaction of raw values older than after.
func WithCompactor ¶
WithCompactor starts a jittered background compactor for keys seen locally.
func WithFlushEvery ¶
WithFlushEvery buffers writes in memory and flushes them periodically.
type Samples ¶
type Samples struct {
// contains filtered or unexported fields
}
Samples writes and reads float64 samples.
func (Samples) Range ¶
func (s Samples) Range(ctx context.Context, from, to time.Time, span time.Duration, agg Agg) (iter.Seq2[time.Time, float64], error)
Range returns bucketed aggregate values.
type Sketch ¶ added in v0.2.0
type Sketch struct {
// contains filtered or unexported fields
}
Sketch is an immutable encoded distribution.
type Sketches ¶ added in v0.2.0
type Sketches struct {
// contains filtered or unexported fields
}
Sketches writes and reads distributions of float64 observations.
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
Package machine identifies the current process for replica tags.
|
Package machine identifies the current process for replica tags. |
|
storage
|
|
|
cached
Package cached adds a read-through cache to a store.
|
Package cached adds a read-through cache to a store. |
|
memory
module
|
|
|
sqlite
module
|