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 ¶
- type BatchEvent
- 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(ctx context.Context, days int) ([]DailyMetric, error)
- func (s *Store) Flush(ctx context.Context) error
- func (s *Store) Page(ctx context.Context, verdict, text string, cursor Cursor, limit int) ([]gate.Event, Cursor)
- func (s *Store) Quarantine(ctx context.Context, now time.Time) []gate.Event
- func (s *Store) Recent(ctx context.Context, limit int) []gate.Event
- func (s *Store) Record(ev gate.Event)
- func (s *Store) RequestFlush()
- func (s *Store) Shutdown(ctx context.Context) error
- func (s *Store) Snapshot(ctx context.Context) Snapshot
- func (s *Store) WriterStats() storage.WriterStats
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type BatchEvent ¶ added in v1.1.0
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 ¶
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 {
// 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.
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).
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 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 ¶
DailyMetrics returns per-UTC-day tallies, newest first (days ≤ 0 → all).
func (*Store) Flush ¶ added in v1.1.0
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 ¶
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.
func (*Store) Record ¶
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
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 ¶
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.