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

• 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 Metric
• type Point
• type Row
• type Sample
• type Store
• type Unit

Types

type Chart

type Chart int

const (
	Stat Chart = iota
	Line
	Bar
)

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.

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. Names must be unique and non-empty; SQL must be non-empty.

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 Metric

type Metric struct {
	Name  string
	Title string
	Kind  Kind
	SQL   string
	Unit  Unit
	Chart Chart
}

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.

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
)