scrape

README

Scrape

Package scrape is the TTL refresh orchestrator for unixctl-backed data sources. ovsdb is monitor-cached by libovsdb (push updates from the server keep the local cache fresh) so it doesn't need a scraper; the unixctl protocol has no monitor concept, so collectors that consume appctl output read from an atomic.Pointer snapshot refreshed here.

A Scraper is generic over the snapshot type T so domain-specific structs (e.g. an OVSSnapshot composed of coverage / memory / upcall fields) can live in their own packages next to their parsers.

Documentation

Index

• type Config
• type Outcome
• type RefreshFunc
• type Scraper
  • func New[T any](cfg Config[T]) (*Scraper[T], error)
  • func (s *Scraper[T]) Outcome() Outcome
  • func (s *Scraper[T]) Refresh(ctx context.Context) error
  • func (s *Scraper[T]) Run(ctx context.Context)
  • func (s *Scraper[T]) Snapshot() *T
  • func (s *Scraper[T]) Stale(maxAge time.Duration) error

Types

type Config

type Config[T any] struct {
	// Name identifies this scraper in logs and span attributes
	// (e.g. "ovs", "northd"). Required.
	Name string
	// Interval is the TTL between refreshes. Defaults to 15s.
	Interval time.Duration
	// Refresh produces the next snapshot. Required.
	Refresh RefreshFunc[T]
	// Logger receives one debug line per successful tick and one warn line
	// per failure. Required.
	Logger *slog.Logger
	// Tracer wraps each refresh in an `ovsx.scrape.unixctl` span.
	// Optional; when nil, no spans are emitted.
	Tracer trace.Tracer
}

Config configures a Scraper.

type Outcome

type Outcome struct {
	Time     time.Time
	Duration time.Duration
	Success  bool
	Err      error
}

Outcome is the result of a single TTL refresh. It is replaced atomically on every tick

type RefreshFunc

type RefreshFunc[T any] func(ctx context.Context) (*T, error)

RefreshFunc produces a fresh snapshot on every tick. It is invoked with the Scraper's context (cancellation propagates) and should respect any deadline. On error the previous snapshot is preserved.

type Scraper

type Scraper[T any] struct {
	// contains filtered or unexported fields
}

Scraper runs Refresh on a ticker and stores the most recent successful result in an atomic pointer for lock-free reads.

func New

func New[T any](cfg Config[T]) (*Scraper[T], error)

New validates cfg and returns an idle Scraper. Call Run to start the ticker, or Refresh to drive one tick manually.

func (*Scraper[T]) Outcome

func (s *Scraper[T]) Outcome() Outcome

Outcome returns the result of the most recent tick (success or failure). Returns zero value before the first tick.

func (*Scraper[T]) Refresh

func (s *Scraper[T]) Refresh(ctx context.Context) error

Refresh runs a single refresh synchronously. Exposed so tests and readyz probes can drive a tick without waiting for the ticker.

func (*Scraper[T]) Run

func (s *Scraper[T]) Run(ctx context.Context)

Run drives Refresh on Config.Interval until ctx is cancelled. The first refresh runs immediately so collectors don't see a nil snapshot for a full interval after startup.

func (*Scraper[T]) Snapshot

func (s *Scraper[T]) Snapshot() *T

Snapshot returns the most recent successful refresh. Returns nil before the first successful tick — callers must handle that case.

func (*Scraper[T]) Stale

func (s *Scraper[T]) Stale(maxAge time.Duration) error

Stale returns nil when the last scrape succeeded and is no older than maxAge, otherwise a descriptive error. Plugs into the probes.Checker interface via a CheckerFunc wrapper so the probes package stays free of an import on internal/scrape. The caller owns the policy (what age counts as stale).