telemetry

package
v1.1.0 Latest Latest
Warning

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

Go to latest
Published: Nov 8, 2026 License: MIT Imports: 13 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 admitted event is persisted in a background batch; reads query committed SQLite state directly. Full or closed queues drop and count incoming events.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type BatchEvent added in v1.1.0

type BatchEvent struct {
	Event gate.Event
	Day   string
}

BatchEvent freezes the accounting day at admission, including for zero Time.

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) Close added in v1.0.0

func (b *Broadcaster) Close()

Close ends every subscription, which ends the SSE streams reading them, and makes later subscriptions start closed. It is a server shutdown hook: an open console tab would otherwise hold the drain until its deadline. Safe to call more than once.

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 {
	// contains filtered or unexported fields
}

Hub records to Store; its writer publishes only confirmed commits.

func NewHub added in v1.1.0

func NewHub(store *Store, b *Broadcaster) *Hub

NewHub binds post-commit publication before traffic is admitted.

func (*Hub) Record

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

Record implements gate.Recorder.

type Repo

type Repo interface {
	// RecordBatch atomically applies a batch and its retry receipt. Only the
	// latest unresolved token may be replayed; tokens must be unique per batch.
	RecordBatch(ctx context.Context, token string, events []BatchEvent) error
	// 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(ctx context.Context, started time.Time) (Snapshot, error)
	// Recent returns up to limit events, newest first. limit <= 0 means all.
	Recent(ctx context.Context, limit int) ([]gate.Event, error)
	// Page returns up to limit events with the given verdict (empty = any)
	// whose "package@version" or request_id contains text (case-insensitive,
	// literal substring; 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(ctx context.Context, verdict, text 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(ctx context.Context, now time.Time) ([]gate.Event, error)
	// DailyMetrics returns per-UTC-day rows, newest first (days <= 0 → all).
	DailyMetrics(ctx context.Context, days int) ([]DailyMetric, error)
	// Prune deletes events and daily rows older than the configured retention.
	Prune(ctx context.Context) 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 admits owned observations to a bounded writer. Committed state lives in the Repo (SQLite); reads never flush pending work. Store also owns uptime and periodic retention pruning.

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 uses a bounded drain when application shutdown has not run already.

func (*Store) DailyMetrics

func (s *Store) DailyMetrics(ctx context.Context, days int) ([]DailyMetric, error)

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

func (*Store) Flush added in v1.1.0

func (s *Store) Flush(ctx context.Context) error

Flush waits for all events accepted before this call, including publication. Cancelling the waiter does not cancel admitted work.

func (*Store) Page

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

Page returns up to limit events matching verdict (empty = any) and text (a case-insensitive substring of "package@version" or request_id; 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(ctx context.Context, 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(ctx context.Context, 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 admits an owned event without waiting for storage. Full or closed queues reject the incoming event and increment in-memory loss counters.

func (*Store) RequestFlush added in v1.1.0

func (s *Store) RequestFlush()

RequestFlush wakes the writer without waiting for it.

func (*Store) Shutdown added in v1.1.0

func (s *Store) Shutdown(ctx context.Context) error

Shutdown stops admissions, drains within ctx, and joins both workers. On expiry the error reports admitted events whose commit was not confirmed.

func (*Store) Snapshot

func (s *Store) Snapshot(ctx context.Context) 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).

func (*Store) WriterStats added in v1.1.0

func (s *Store) WriterStats() storage.WriterStats

WriterStats reads only in-memory counters, even when SQLite is unavailable.

Jump to

Keyboard shortcuts

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