stats

Documentation

Overview

Package stats provides a comprehensive statistics collection system for hypercache. It implements a registry pattern for managing different types of statistics collectors and defines interfaces for collecting various metrics including counters, timers, gauges, and histograms.

The package supports pluggable statistics collectors through the CollectorRegistry, allowing for easy extension and customization of metrics collection strategies. A default histogram-based collector is provided out of the box.

Example usage:

// Create a collector using the default registry
collector, err := stats.NewCollector("default")
if err != nil {
	log.Fatal(err)
}

// Record various metrics
collector.Incr(constants.CacheHits, 1)
collector.Timing(constants.ResponseTime, 150)
collector.Gauge(constants.MemoryUsage, 1024)

// Get collected statistics
stats := collector.GetStats()

Index

• Constants
• type CollectorRegistry
  • func NewCollectorRegistry() *CollectorRegistry
  • func NewEmptyCollectorRegistry() *CollectorRegistry
  • func (r *CollectorRegistry) NewCollector(statsCollectorName string) (ICollector, error)
  • func (r *CollectorRegistry) Register(name string, createFunc func() (ICollector, error))
• type HistogramStatsCollector
  • func NewHistogramStatsCollector() *HistogramStatsCollector
  • func NewHistogramStatsCollectorWithCapacity(capacity int) *HistogramStatsCollector
  • func (c *HistogramStatsCollector) Decr(stat constants.Stat, value int64)
  • func (c *HistogramStatsCollector) Gauge(stat constants.Stat, value int64)
  • func (c *HistogramStatsCollector) GetStats() Stats
  • func (c *HistogramStatsCollector) Histogram(stat constants.Stat, value int64)
  • func (c *HistogramStatsCollector) Incr(stat constants.Stat, value int64)
  • func (c *HistogramStatsCollector) Mean(stat constants.Stat) float64
  • func (c *HistogramStatsCollector) Median(stat constants.Stat) float64
  • func (c *HistogramStatsCollector) Percentile(stat constants.Stat, percentile float64) float64
  • func (c *HistogramStatsCollector) Timing(stat constants.Stat, value int64)
• type ICollector
  • func NewCollector(statsCollectorName string) (ICollector, error)
• type Stat
• type Stats

Constants

const DefaultSampleCapacity = 4096

DefaultSampleCapacity is the per-stat ring buffer size used by NewHistogramStatsCollector. Bounded so memory does not grow without bound under sustained recording.

Types

type CollectorRegistry

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

CollectorRegistry manages stats collector constructors.

func NewCollectorRegistry

func NewCollectorRegistry() *CollectorRegistry

NewCollectorRegistry creates a new collector registry with default collectors pre-registered.

func NewEmptyCollectorRegistry

func NewEmptyCollectorRegistry() *CollectorRegistry

NewEmptyCollectorRegistry creates a new collector registry without default collectors. This is useful for testing or when you want to register only specific collectors.

func (*CollectorRegistry) NewCollector

func (r *CollectorRegistry) NewCollector(statsCollectorName string) (ICollector, error)

NewCollector creates a new stats collector.

func (*CollectorRegistry) Register

func (r *CollectorRegistry) Register(name string, createFunc func() (ICollector, error))

Register registers a new stats collector with the given name.

type HistogramStatsCollector

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

HistogramStatsCollector records statistics with per-stat atomic aggregates and a bounded per-stat sample window for percentile computation.

Hot-path Incr/Decr/Timing/Gauge/Histogram updates use atomic counters and a best-effort TryLock around a fixed-size ring buffer. There is no global lock on the recording path; the shard map uses sync.Map for read-mostly lookup. Memory usage is bounded.

Mean, Min, Max, Sum, and Count are exact lifetime aggregates. Median, Percentile, Variance, and the Values slice exposed by GetStats are computed over a recent-window snapshot whose size is configurable via NewHistogramStatsCollectorWithCapacity (default DefaultSampleCapacity).

Performance characteristics: contention is now partitioned per stat key rather than globally serialized. A worst-case microbenchmark with all goroutines hammering a single stat key sees ~150 ns/op due to cache-line ping-pong on the shard's atomics; in realistic workloads where calls spread across multiple stats (cache_hits, evictions, set_count, etc.) throughput scales with the number of distinct keys.

func NewHistogramStatsCollector

func NewHistogramStatsCollector() *HistogramStatsCollector

NewHistogramStatsCollector creates a collector with the default sample window.

func NewHistogramStatsCollectorWithCapacity

func NewHistogramStatsCollectorWithCapacity(capacity int) *HistogramStatsCollector

NewHistogramStatsCollectorWithCapacity creates a collector with a custom per-stat sample window. capacity <= 0 falls back to DefaultSampleCapacity.

func (*HistogramStatsCollector) Decr

func (c *HistogramStatsCollector) Decr(stat constants.Stat, value int64)

Decr decrements the count of a statistic by the given value.

func (*HistogramStatsCollector) Gauge

func (c *HistogramStatsCollector) Gauge(stat constants.Stat, value int64)

Gauge records the current value of a statistic.

func (*HistogramStatsCollector) GetStats

func (c *HistogramStatsCollector) GetStats() Stats

GetStats returns aggregated statistics. Mean, Min, Max, Sum, and Count are exact lifetime values; Median, Variance, and Values are over the recent sample window.

func (*HistogramStatsCollector) Histogram

func (c *HistogramStatsCollector) Histogram(stat constants.Stat, value int64)

Histogram records the statistical distribution of a set of values.

func (*HistogramStatsCollector) Incr

func (c *HistogramStatsCollector) Incr(stat constants.Stat, value int64)

Incr increments the count of a statistic by the given value.

func (*HistogramStatsCollector) Mean

func (c *HistogramStatsCollector) Mean(stat constants.Stat) float64

Mean returns the lifetime mean of all recorded values.

func (*HistogramStatsCollector) Median

func (c *HistogramStatsCollector) Median(stat constants.Stat) float64

Median returns the median of the recent sample window.

func (*HistogramStatsCollector) Percentile

func (c *HistogramStatsCollector) Percentile(stat constants.Stat, percentile float64) float64

Percentile returns the pth percentile of the recent sample window. percentile must be in [0, 1]; values outside that range are clamped.

func (*HistogramStatsCollector) Timing

func (c *HistogramStatsCollector) Timing(stat constants.Stat, value int64)

Timing records the time it took for an event to occur.

type ICollector

type ICollector interface {
	// Incr increments the count of a statistic by the given value.
	Incr(stat constants.Stat, value int64)
	// Decr decrements the count of a statistic by the given value.
	Decr(stat constants.Stat, value int64)
	// Timing records the time it took for an event to occur.
	Timing(stat constants.Stat, value int64)
	// Gauge records the current value of a statistic.
	Gauge(stat constants.Stat, value int64)
	// Histogram records the statistical distribution of a set of values.
	Histogram(stat constants.Stat, value int64)
	// GetStats returns the collected statistics.
	GetStats() Stats
}

ICollector is an interface that defines the methods that a stats collector should implement.

func NewCollector

func NewCollector(statsCollectorName string) (ICollector, error)

NewCollector creates a new stats collector using a new registry instance with default collectors. The statsCollectorName parameter is used to select the stats collector from the default collectors.

type Stat

type Stat struct {
	// Mean value of the stat.
	Mean float64
	// Median value of the stat.
	Median float64
	// Min is the minimum value of the stat.
	Min int64
	// Max maximum value of the stat.
	Max int64
	// Values slice of all the values of the stat.
	Values []int64
	// Count the number of values of the stat.
	Count int
	// Sum of all the values of the stat.
	Sum int64
	// Variance of the values of the stat.
	Variance float64
}

Stat represents statistical data for a specific stat.

type Stats

type Stats map[string]*Stat

Stats is a map that stores statistical data. The keys are the stat names and the values are the stat values.