telemetry

package
v0.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jul 4, 2026 License: MIT Imports: 9 Imported by: 0

Documentation

Overview

Package telemetry collects per-request events from the proxy handlers for the admin console and persists them to SQLite, the single source of truth. Every Record is durable at write time; reads query SQLite directly. There is no in-memory mode.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Broadcaster

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

Broadcaster fans out events to live subscribers (SSE handlers). Publish never blocks.

func NewBroadcaster

func NewBroadcaster() *Broadcaster

NewBroadcaster creates an empty Broadcaster.

func (*Broadcaster) Publish

func (b *Broadcaster) Publish(ev gate.Event)

Publish delivers ev to every subscriber with buffer room; slow subscribers lose the event so the proxy data path never stalls.

func (*Broadcaster) Subscribe

func (b *Broadcaster) Subscribe() (<-chan gate.Event, func())

Subscribe registers a subscriber. The returned cancel func releases it and closes the channel; calling cancel more than once is safe.

type Cursor

type Cursor struct {
	TS time.Time
	ID int64
}

Cursor is a keyset position in the event log — the (ts, id) of a row under the canonical ORDER BY ts DESC, id DESC. The zero Cursor means "start from the newest event". id is the SQLite rowid (>= 1), so ID == 0 is the sentinel.

func (Cursor) Zero

func (c Cursor) Zero() bool

Zero reports whether c is the start-from-newest sentinel.

type DailyMetric

type DailyMetric struct {
	Day            string                `json:"day"` // UTC YYYY-MM-DD
	Requests       uint64                `json:"requests"`
	CacheHits      uint64                `json:"cache_hits"`
	Blocked        uint64                `json:"blocked"`
	Errors         uint64                `json:"errors"`
	SupplyBlocked  uint64                `json:"supply_blocked"`
	CVEBlocked     uint64                `json:"cve_blocked"`
	MalwareBlocked uint64                `json:"malware_blocked"`
	Denylisted     uint64                `json:"denylisted"`
	Gates          map[string]GateCounts `json:"gates"`
}

DailyMetric is one UTC calendar day's tallies.

type GateCounts

type GateCounts struct {
	Pass  uint64 `json:"pass"`
	Block uint64 `json:"block"`
}

GateCounts is the pass/block tally for one gate.

type Hub

type Hub struct {
	Store       *Store
	Broadcaster *Broadcaster
}

Hub implements gate.Recorder by recording to Store and publishing to Broadcaster. Both fields must be non-nil.

func (*Hub) Record

func (h *Hub) Record(ev gate.Event)

Record implements gate.Recorder.

type Repo

type Repo interface {
	// RecordEvent durably persists one event and applies its tallies to the
	// cumulative counters and the event's UTC-day metrics row, atomically.
	RecordEvent(ev gate.Event) error
	// Snapshot returns the cumulative counters, stamped with started as StartedAt.
	Snapshot(started time.Time) (Snapshot, error)
	// Recent returns up to limit events, newest first. limit <= 0 means all.
	Recent(limit int) ([]gate.Event, error)
	// Page returns up to limit events with the given verdict (empty = any),
	// newest-first, strictly older than cursor. A zero cursor starts at the
	// newest matching event. The second return is the cursor of the last row
	// returned; it is the zero Cursor when there are no more pages.
	// When limit <= 0 all matching rows are returned in one call; the second
	// return is then the cursor of the last row (non-zero if any rows exist),
	// but no further rows exist beyond it.
	Page(verdict string, cursor Cursor, limit int) ([]gate.Event, Cursor, error)
	// Quarantine returns active supply-chain holds (newest BLOCK@supply per
	// eco/pkg@ver whose block_until is after now), newest first.
	Quarantine(now time.Time) ([]gate.Event, error)
	// DailyMetrics returns per-UTC-day rows, newest first (days <= 0 → all).
	DailyMetrics(days int) ([]DailyMetric, error)
	// Prune deletes events and daily rows older than the configured retention.
	Prune() error
}

Repo persists and retrieves telemetry. SQLite is the single source of truth; there is no in-memory implementation. Implementations are safe for concurrent use (calls serialize on a single SQLite connection).

func NewSQLiteRepo

func NewSQLiteRepo(db *storage.DB, eventRetentionDays, dailyRetentionDays int) (Repo, error)

NewSQLiteRepo applies the telemetry schema to db and returns a Repo. eventRetentionDays/dailyRetentionDays ≤ 0 fall back to defaults (30/365).

type Snapshot

type Snapshot struct {
	StartedAt      time.Time
	Requests       uint64
	CacheHits      uint64
	Blocked        uint64
	Errors         uint64
	SupplyBlocked  uint64
	CVEBlocked     uint64
	MalwareBlocked uint64
	Denylisted     uint64
	Gates          map[string]GateCounts // keys: cache, supply, cve, malware
}

Snapshot is a point-in-time copy of all counters since process start.

type Store

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

Store is a thin façade over a Repo. All telemetry state lives in the Repo (SQLite). Store adds the process start time (for uptime) and a periodic prune.

func New

func New(repo Repo, logger zerolog.Logger) *Store

New returns a Store backed by repo and starts its background prune loop.

func Open

func Open(db *storage.DB, eventRetentionDays, dailyRetentionDays int, logger zerolog.Logger) (*Store, error)

Open builds a SQLite-backed Store on db, applying the telemetry schema. Retention values ≤ 0 fall back to defaults (30/365 days).

func (*Store) Close

func (s *Store) Close() error

Close stops the prune loop. Safe to call multiple times.

func (*Store) DailyMetrics

func (s *Store) DailyMetrics(days int) ([]DailyMetric, error)

DailyMetrics returns per-UTC-day tallies, newest first (days ≤ 0 → all).

func (*Store) Page

func (s *Store) Page(verdict string, cursor Cursor, limit int) ([]gate.Event, Cursor)

Page returns up to limit events matching verdict (empty = any), newest-first, older than cursor (zero cursor = newest), plus the cursor for the next call (zero when there are no more pages). A read error logs and yields nil with a zero cursor, so the console degrades to an empty page rather than failing.

func (*Store) Quarantine

func (s *Store) Quarantine(now time.Time) []gate.Event

Quarantine returns the active supply-chain holds. A read error logs and yields nil.

func (*Store) Recent

func (s *Store) Recent(limit int) []gate.Event

Recent returns up to limit events, newest first (limit ≤ 0 → all). A read error logs and yields nil.

func (*Store) Record

func (s *Store) Record(ev gate.Event)

Record durably persists ev (insert + counter/daily increments) synchronously. Telemetry must never fail a proxy request: on error it logs and returns, losing at most this one event (not a flush window).

func (*Store) Snapshot

func (s *Store) Snapshot() Snapshot

Snapshot returns the cumulative counters. A read error logs and yields a zero snapshot (the overview must not 500 on a transient read failure).

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL