stats

README

Contextualized Stats Tracker for Go

This library provides context-driven stats tracker.

Features

• Loosely coupled with underlying implementation.
• Context-driven labels control.
• Zero allocation implementation for Prometheus client.
• A simple interface with variadic number of key-value pairs for labels.
• Easily mockable interface free from 3rd party dependencies.

Example

// Bring your own Prometheus registry.
registry := prometheus.NewRegistry()
tr := prom.Tracker{
    Registry: registry,
}

// Add custom Prometheus configuration where necessary.
tr.DeclareHistogram("my_latency_seconds", prometheus.HistogramOpts{
    Buckets: []float64{1e-4, 1e-3, 1e-2, 1e-1, 1, 10, 100},
})

ctx := context.Background()

// Add labels to context.
ctx = stats.AddKeysAndValues(ctx, "ctx-label", "ctx-value0")

// Override label values.
ctx = stats.AddKeysAndValues(ctx, "ctx-label", "ctx-value1")

// Collect stats with last mile labels.
tr.Add(ctx, "my_count", 1,
    "some-label", "some-value",
)

tr.Add(ctx, "my_latency_seconds", 1.23)

tr.Set(ctx, "temperature", 33.3)

Versioning

This project adheres to Semantic Versioning.

Before version 1.0.0, breaking changes are tagged with MINOR bump, features and fixes are tagged with PATCH bump. After version 1.0.0, breaking changes are tagged with MAJOR bump.

Documentation

Overview

Package stats defines statistics tracker.

Index

• func AddKeysAndValues(ctx context.Context, keysAndValues ...string) context.Context
• func KeysAndValues(ctx context.Context) []string
• type Adder
• type AdderFunc
  • func (f AdderFunc) Add(ctx context.Context, name string, increment float64, labelsAndValues ...string)
• type NoOp
  • func (NoOp) Add(ctx context.Context, name string, increment float64, labelsAndValues ...string)
  • func (NoOp) Set(ctx context.Context, name string, absolute float64, labelsAndValues ...string)
  • func (NoOp) StatsTracker() Tracker
• type Setter
• type SetterFunc
  • func (f SetterFunc) Set(ctx context.Context, name string, absolute float64, labelsAndValues ...string)
• type Tracker
• type TrackerMock
  • func (t *TrackerMock) Add(_ context.Context, name string, increment float64, labels ...string)
  • func (t *TrackerMock) Int(name string, labels ...string) int
  • func (t *TrackerMock) LabeledValues() map[string]float64
  • func (t *TrackerMock) Metrics() string
  • func (t *TrackerMock) Set(_ context.Context, name string, absolute float64, labels ...string)
  • func (t *TrackerMock) StatsTracker() Tracker
  • func (t *TrackerMock) Value(name string, labels ...string) float64
  • func (t *TrackerMock) Values() map[string]float64
• type TrackerProvider

Functions

func AddKeysAndValues

func AddKeysAndValues(ctx context.Context, keysAndValues ...string) context.Context

AddKeysAndValues returns context with added key-value pairs. If key-value pairs exist in parent context already, new pairs are appended.

func KeysAndValues

func KeysAndValues(ctx context.Context) []string

KeysAndValues returns key-pairs found in context or nil.

Types

type Adder

type Adder interface {
	// Add collects additional or observable value.
	Add(ctx context.Context, name string, increment float64, labelsAndValues ...string)
}

Adder defines incremental metric collector.

type AdderFunc

type AdderFunc func(ctx context.Context, name string, increment float64, labelsAndValues ...string)

AdderFunc implements Adder.

func (AdderFunc) Add

func (f AdderFunc) Add(ctx context.Context, name string, increment float64, labelsAndValues ...string)

Add collects additional or observable value.

type NoOp

type NoOp struct{}

NoOp is a stats tracker stub.

func (NoOp) Add

func (NoOp) Add(ctx context.Context, name string, increment float64, labelsAndValues ...string)

Add discards value increment, can be negative.

func (NoOp) Set

func (NoOp) Set(ctx context.Context, name string, absolute float64, labelsAndValues ...string)

Set discards absolute value.

func (NoOp) StatsTracker

func (NoOp) StatsTracker() Tracker

StatsTracker is a provider.

type Setter

type Setter interface {
	// Set collects absolute value, e.g. number of goroutines.
	Set(ctx context.Context, name string, absolute float64, labelsAndValues ...string)
}

Setter defines absolute value collector.

type SetterFunc

type SetterFunc func(ctx context.Context, name string, absolute float64, labelsAndValues ...string)

SetterFunc implements Setter.

func (SetterFunc) Set

func (f SetterFunc) Set(ctx context.Context, name string, absolute float64, labelsAndValues ...string)

Set collects absolute value.

type Tracker

type Tracker interface {
	Adder
	Setter
}

Tracker defines stats collector.

type TrackerMock

type TrackerMock struct {
	// contains filtered or unexported fields
}

TrackerMock can collect stats for tests with labels ignored.

func (*TrackerMock) Add

func (t *TrackerMock) Add(_ context.Context, name string, increment float64, labels ...string)

Add collects metric increment.

func (*TrackerMock) Int

func (t *TrackerMock) Int(name string, labels ...string) int

Int returns collected value as integer by name.

func (*TrackerMock) LabeledValues

func (t *TrackerMock) LabeledValues() map[string]float64

LabeledValues returns collected labeled values as a map.

func (*TrackerMock) Metrics

func (t *TrackerMock) Metrics() string

Metrics returns collected values in Prometheus format.

func (*TrackerMock) Set

func (t *TrackerMock) Set(_ context.Context, name string, absolute float64, labels ...string)

Set collects absolute value.

func (*TrackerMock) StatsTracker

func (t *TrackerMock) StatsTracker() Tracker

StatsTracker is a provider.

func (*TrackerMock) Value

func (t *TrackerMock) Value(name string, labels ...string) float64

Value returns collected value by name.

func (*TrackerMock) Values

func (t *TrackerMock) Values() map[string]float64

Values returns collected summarized values as a map.

type TrackerProvider

type TrackerProvider interface {
	StatsTracker() Tracker
}

TrackerProvider defines service locator interface.