Documentation
¶
Overview ¶
Package scraper drives BPF telemetry-map collection: one goroutine drains the kernel map on a tick and folds each reading into state.GlobalState. The MapReader seam lets tests substitute a synthetic reader without eBPF.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Evictor ¶
type Evictor interface {
Relieve(drained map[bpf.FlowKey]bpf.FlowMetrics)
}
Evictor relieves kernel telemetry_map pressure once per tick, AFTER the drain is applied to GlobalState — so every byte is accounted before its kernel entry can be removed. It receives the just-drained buffer read-only. nil disables relief.
docs/architecture/data-structures.md#kernel-side-bpf-maps
type FlowSink ¶
type FlowSink interface {
Absorb(key bpf.FlowKey, raw bpf.FlowMetrics)
Sweep(force bool)
}
FlowSink classifies each drained reading: known VM-MAC flows go to GlobalState, unknown ones to the UnresolvedBuffer. Sweep ages out buffered entries each tick; force=true on the shutdown tick folds the whole buffer so no unknown bytes are lost to the final WAL flush.
docs/architecture/data-structures.md#userspace-structures
type MapReader ¶
type MapReader interface {
BatchLookup(dst map[bpf.FlowKey]bpf.FlowMetrics) error
}
MapReader is the kernel-side data source drained each tick. dst is caller-owned and reused, so implementations must clear it first or stale entries leak. PERCPU values must already be aggregated across CPUs — the scraper expects one bpf.FlowMetrics per key.
type Metrics ¶
type Metrics struct {
// contains filtered or unexported fields
}
Metrics holds the scraper-subsystem Prometheus instruments. Construct with NewMetrics, register the slice from Metrics.Collectors with your prometheus.Registry, then hand the *Metrics to Scraper.SetMetrics. nil is acceptable — the Observe* helpers handle it, so a Scraper without metrics simply records nothing.
The bundle mirrors the metric catalogue:
- lachesis_scrape_duration_seconds one successful drain+integrate tick
func NewMetrics ¶
func NewMetrics() *Metrics
NewMetrics constructs the scraper instrument bundle. The bucket span matches the WAL flush and Collect histograms (1 ms..1 s) so the three per-tick costs are directly comparable on a dashboard; the upper decade matters here because the drain grows with entries × N_CPU and is expected to reach tens of milliseconds on high-core hosts.
Cost model: docs/architecture/performance.md
func (*Metrics) Collectors ¶
func (m *Metrics) Collectors() []prometheus.Collector
Collectors returns every instrument in the bundle, suitable for passing to prometheus.Registerer.MustRegister.
func (*Metrics) ObserveScrape ¶
ObserveScrape records one completed tick's wall time. Only successful ticks are observed — a tick whose drain failed did a fraction of the work, and mixing those in would pull the quantiles down precisely when drains are failing; lachesis_scraper_errors_total carries that signal. nil-safe.
type Scraper ¶
type Scraper struct {
// contains filtered or unexported fields
}
Scraper periodically drains a MapReader and updates a state.GlobalState. Construct one with New, then call Scraper.Run on a long-lived goroutine.
func New ¶
New constructs a Scraper. tun supplies the live scrape cadence (validated ≥1s by [config.ScrapeConfig.Validate]; hot-reload applies at the next tick — the delta math is interval-agnostic, so retiming is safe mid-run).
func (*Scraper) ErrorCount ¶
ErrorCount returns the cumulative count of failed ticks since process start. Exposed via Prometheus by the metrics package.
func (*Scraper) LastSuccessUnix ¶
LastSuccessUnix returns the unix-second timestamp of the most recent successful tick, or 0 if none has succeeded.
func (*Scraper) Run ¶
Run drives the scrape loop until ctx is cancelled, ticking immediately so /metrics has data within one interval of startup.
On cancellation it performs one FINAL tick. Without it a graceful shutdown loses up to a scrape interval of billing data, because the maps die with the TC filters on the next boot. Callers must keep the BPF collection open until Run returns.
func (*Scraper) SetEvictor ¶
SetEvictor wires the pressure-relief evictor. Call once before [Run] starts the scrape goroutine — Bootstrap does so after it has the kernel telemetry_map handle. Passing nil leaves pressure relief disabled.
func (*Scraper) SetMetrics ¶
SetMetrics wires the instrument bundle timing each tick. Call once before [Run] starts the scrape goroutine; nil records nothing.
func (*Scraper) SetSink ¶
SetSink wires the unknown-MAC classifier. Call once before [Run] starts the scrape goroutine. Passing nil keeps the legacy direct-to-GlobalState path (every flow integrated regardless of whether its MAC is known).
func (*Scraper) Tick ¶
Tick performs a single drain+integrate pass. Exposed for tests and for the loadtest harness; the production path is Scraper.Run.
Source Files