gnomon

README

gnomon

A tiny, standardized BI layer for Go services — the metrics sibling to flagpole. Register business metrics, then capture and serve them. No scheduler, no auth, no UI — those belong to the host.

Concepts

• ReadThrough metric: queried live on request.
• Snapshot metric: captured once per day into gnomon_snapshots for trends.

Usage

g := gnomon.New(sourcepg.New(pool), sourcepg.New(pool))
g.Register(
    gnomon.Metric{Name: "mrr", Title: "MRR", Kind: gnomon.ReadThrough,
        SQL: "SELECT * FROM analytics_mrr", Unit: gnomon.Cents, Chart: gnomon.Stat},
    gnomon.Metric{Name: "mrr_daily", Title: "MRR over time", Kind: gnomon.Snapshot,
        SQL: "SELECT mrr_usd::float8 AS value FROM analytics_mrr", Unit: gnomon.Cents, Chart: gnomon.Line},
)

// In a daily job:
_ = g.Capture(ctx, time.Now().UTC())

// Mount the JSON API behind your own auth:
mux.Handle("/admin/insights/", http.StripPrefix("/admin/insights", adminhttp.NewHandler(g)))

Run sourcepg/schema.sql via your own migration tooling.

Documentation

Overview

Package gnomon is a tiny, standardized BI layer: register business metrics (live ReadThrough or daily Snapshot), then capture and serve them. It owns no scheduling and no auth -- the host wires Capture into its own job runner and wraps adminhttp with its own auth middleware.

Index

• Variables
• type Chart
• type DataSource
• type Gnomon
  • func New(data DataSource, store Store) *Gnomon
  • func (g *Gnomon) Capture(ctx context.Context, on time.Time) error
  • func (g *Gnomon) Metrics() []Metric
  • func (g *Gnomon) Query(ctx context.Context, name string) ([]Row, error)
  • func (g *Gnomon) Register(ms ...Metric) error
  • func (g *Gnomon) Series(ctx context.Context, name string, from, to time.Time) ([]Point, error)
• type Kind
• type Measure
• type Metric
• type Point
• type Row
• type Sample
• type Store
• type Unit

Variables

var ErrUnknownMetric = errors.New("gnomon: unknown metric")

ErrUnknownMetric is returned by Query and Series when the requested metric name has not been registered.

var ErrWrongKind = errors.New("gnomon: wrong metric kind")

ErrWrongKind is returned by Query when called on a Snapshot metric, or by Series when called on a ReadThrough metric.

Types

type Chart

type Chart int

const (
	Stat Chart = iota
	Line
	Bar
	Funnel
)

type DataSource

type DataSource interface {
	Query(ctx context.Context, sql string) ([]Row, error)
}

DataSource runs metric SQL against the host's data database.

type Gnomon

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

Gnomon is the engine: a metric registry over a DataSource + Store.

func New

func New(data DataSource, store Store) *Gnomon

func (*Gnomon) Capture

func (g *Gnomon) Capture(ctx context.Context, on time.Time) error

Capture runs every registered Snapshot metric's SQL, parses the rows into samples, and upserts them stamped with on. ReadThrough metrics are skipped. One metric's failure does not abort the rest; all errors are joined.

A snapshot metric is all-or-nothing per capture: if any row fails to parse, that metric's entire sample set for the day is skipped and the error is joined (other metrics still capture).

func (*Gnomon) Metrics

func (g *Gnomon) Metrics() []Metric

Metrics returns registered metrics in registration order.

func (*Gnomon) Query

func (g *Gnomon) Query(ctx context.Context, name string) ([]Row, error)

Query runs a ReadThrough metric and returns its rows. It errors if the metric is unknown or is not a ReadThrough metric.

func (*Gnomon) Register

func (g *Gnomon) Register(ms ...Metric) error

Register validates and adds metrics in a single atomic operation. Names must be unique (against existing registrations AND within the batch itself) and non-empty; SQL must be non-empty. If any metric in the batch fails validation, no metrics from the batch are registered.

func (*Gnomon) Series

func (g *Gnomon) Series(ctx context.Context, name string, from, to time.Time) ([]Point, error)

Series reads stored snapshot history for a Snapshot metric in [from, to].

type Kind

type Kind int

const (
	// ReadThrough metrics are queried live on request; nothing is stored.
	ReadThrough Kind = iota
	// Snapshot metrics are captured once per day into the snapshot store for trends.
	Snapshot
)

type Measure

type Measure struct {
	Name  string
	Label string
	Unit  Unit
}

Measure is one plotted/displayed series within a metric: which row column to read, an optional display label, and the unit to format it with.

type Metric

type Metric struct {
	Name      string
	Title     string
	Kind      Kind
	SQL       string
	Unit      Unit
	Chart     Chart
	Dimension string
	Measures  []Measure
}

Metric is a single registered metric. For Snapshot kind, SQL must return a value column and may return a dimension column. For ReadThrough kind, SQL may return arbitrary columns; Dimension names the x-axis column and Measures names the columns to plot/show (in order).

type Point

type Point struct {
	CapturedOn time.Time `json:"captured_on"`
	Dimension  string    `json:"dimension"`
	Value      float64   `json:"value"`
}

Point is one stored snapshot data point read back from the store.

type Row

type Row map[string]any

Row is one result row from a ReadThrough query (column name -> value).

type Sample

type Sample struct {
	Dimension string
	Value     float64
}

Sample is one captured snapshot value for a metric on a given day.

type Store

type Store interface {
	UpsertSnapshots(ctx context.Context, on time.Time, metric string, samples []Sample) error
	ReadSeries(ctx context.Context, metric string, from, to time.Time) ([]Point, error)
}

Store persists and reads snapshot history.

type Unit

type Unit int

const (
	Count Unit = iota
	Percent
	Cents
)