tally

Documentation

Overview

Package tally keeps additive sufficient statistics for observations so that two sheets recorded on different machines can be merged by addition, in any order, and give the same answer as one sheet that saw everything. It is standard library only and touches no network, no disk and no clock. The only strings a sheet holds are the metric, role, model and dim labels an observation carries.

Index

• type Cell
  • func (c Cell) Mean() float64
  • func (c Cell) Var() float64
• type Sheet
  • func New() *Sheet
  • func (s *Sheet) Cell(metric, role, model string, dims map[string]string) (Cell, bool)
  • func (s *Sheet) Each(metric string, fn func(role, model string, dims map[string]string, c Cell))
  • func (s *Sheet) MarshalJSON() ([]byte, error)
  • func (s *Sheet) Merge(other *Sheet)
  • func (s *Sheet) Observe(metric, role, model string, dims map[string]string, x float64)
  • func (s *Sheet) UnmarshalJSON(data []byte) error
  • func (s *Sheet) Win(role, winner, loser string)
  • func (s *Sheet) Wins(role, a, b string) (aOverB, bOverA int64)

Types

type Cell

type Cell struct {
	N     int64
	Sum   float64
	SumSq float64
}

Cell is the sufficient statistic recorded for one address: how many observations were seen, their sum, and the sum of their squares. Two cells for the same address add field by field.

func (Cell) Mean

func (c Cell) Mean() float64

Mean returns the mean of the observations, or 0 when the cell is empty.

func (Cell) Var

func (c Cell) Var() float64

Var returns the sample variance of the observations. It is 0 when the cell holds fewer than two observations, and it is never negative: rounding in the sum-of-squares formula is clamped to zero.

type Sheet

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

Sheet keeps additive sufficient statistics: one cell per address of metric, role, model and dims, and paired-comparison tallies per role. A Sheet is safe for concurrent use by multiple goroutines, and the zero value is an empty sheet ready to use.

func New

func New() *Sheet

New returns an empty sheet.

func (*Sheet) Cell

func (s *Sheet) Cell(metric, role, model string, dims map[string]string) (Cell, bool)

Cell returns the cell recorded for the address, and whether any observation was recorded for it. Nil dims and an empty map are the same address, and the order the labels were inserted in never matters.

func (*Sheet) Each

func (s *Sheet) Each(metric string, fn func(role, model string, dims map[string]string, c Cell))

Each hands every cell recorded under metric to fn, one call per cell, in a deterministic order: role, then model, then the dim labels. Cells recorded under other metrics are not handed over, and the sheet is only read — fn sees the dim labels as the sheet stores them, nil when the observations carried none, and it does not run while the sheet is locked, so it may read the sheet again.

func (*Sheet) MarshalJSON

func (s *Sheet) MarshalJSON() ([]byte, error)

MarshalJSON encodes the sheet deterministically: sheets holding the same statistics give byte-identical documents, whatever order anything was inserted in. Cells are sorted by metric, role, model and dim labels, wins by role, winner and loser, dim labels by key. The document carries a top-level "schema": 1.

func (*Sheet) Merge

func (s *Sheet) Merge(other *Sheet)

Merge adds other into s: afterwards s holds what it held plus what other holds, and other is left unmodified. Merging a sheet into itself doubles it. A nil sheet on either side is a no-op.

func (*Sheet) Observe

func (s *Sheet) Observe(metric, role, model string, dims map[string]string, x float64)

Observe records one observation x of metric for role and model, under the optional dim labels (for example quant=fp8). Nil dims and an empty map are the same address, and the order the labels were inserted in never matters. An observation that is NaN or infinite is ignored, and so is the whole call when any label is longer than 128 bytes or contains a newline or a path separator other than the single "/" a model id carries between vendor and name.

func (*Sheet) UnmarshalJSON

func (s *Sheet) UnmarshalJSON(data []byte) error

UnmarshalJSON replaces the sheet's contents with the document. Fields unknown to this package, at the top level and inside an entry, are ignored. A document whose schema is greater than 1 is refused with an error.

func (*Sheet) Win

func (s *Sheet) Win(role, winner, loser string)

Win records one paired comparison in which winner beat loser for role. The call is ignored when a name is empty, when winner and loser are equal, or when a name is longer than 128 bytes or contains a newline or a path separator other than the single "/" a model id carries between vendor and name.

func (*Sheet) Wins

func (s *Sheet) Wins(role, a, b string) (aOverB, bOverA int64)

Wins returns the paired comparisons recorded for role in both directions between a and b.