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 ¶
- type Broadcaster
- type Cursor
- type DailyMetric
- type GateCounts
- type Hub
- type Repo
- type Snapshot
- type Store
- func (s *Store) Close() error
- func (s *Store) DailyMetrics(days int) ([]DailyMetric, error)
- func (s *Store) Page(verdict, text string, cursor Cursor, limit int) ([]gate.Event, Cursor)
- func (s *Store) Quarantine(now time.Time) []gate.Event
- func (s *Store) Recent(limit int) []gate.Event
- func (s *Store) Record(ev gate.Event)
- func (s *Store) Snapshot() Snapshot
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 ¶
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.
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 ¶
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.
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)
// 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(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(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).
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 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) DailyMetrics ¶
func (s *Store) DailyMetrics(days int) ([]DailyMetric, error)
DailyMetrics returns per-UTC-day tallies, newest first (days ≤ 0 → all).
func (*Store) Page ¶
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 ¶
Quarantine returns the active supply-chain holds. A read error logs and yields nil.
func (*Store) Recent ¶
Recent returns up to limit events, newest first (limit ≤ 0 → all). A read error logs and yields nil.