agent

Documentation

Overview

Package agent is the composition root: it wires state, scraper, metrics, runtime and logging onto an HTTP server — the glue between the BPF data plane and the Prometheus endpoint.

One Agent struct with method files by functionality: construction here, HTTP in http.go, the Run/shutdown lifecycle in run.go, the worker table in worker.go, the WAL slice in walflush.go.

The Agent depends only on the scraper.MapReader seam, so unit tests run on macOS; the real BPF reader and boot sequence are the _linux.go files.

Index

• type Agent
  • func Bootstrap(ctx context.Context, args []string) (*Agent, io.Closer, error)
  • func New(opts Options) (*Agent, error)
  • func (a *Agent) Addr() string
  • func (a *Agent) Run(ctx context.Context) error
  • func (a *Agent) SeedServerSettled(records []state.ServerSettledRecord)
  • func (a *Agent) SeedState(records []state.Record)
  • func (a *Agent) SeedTenantSettled(records []state.TenantSettledRecord)
  • func (a *Agent) SeedTotalSettled(records []state.TotalSettledRecord)
  • func (a *Agent) WALMetrics() *wal.Metrics
• type BPFMapReader
  • func NewBPFMapReader(m *ebpf.Map) (*BPFMapReader, error)
  • func (r *BPFMapReader) BatchLookup(dst map[bpf.FlowKey]bpf.FlowMetrics) error
• type Options

Types

type Agent

type Agent struct {
	// contains filtered or unexported fields
}

Agent owns the in-process composition of the telemetry data plane: state.GlobalState, the scraper.Scraper goroutine, the metrics Collector, the runtime manager, and the HTTP server. Construct one with New (or Bootstrap for the full Linux startup sequence), then call Agent.Run; Run blocks until ctx is cancelled.

func Bootstrap

func Bootstrap(ctx context.Context, args []string) (*Agent, io.Closer, error)

Bootstrap runs the agent's startup sequence and returns a ready Agent plus an io.Closer releasing the BPF collection. The body is a flat ordered list of named steps, each advancing the boot.Sequencer to the phase it establishes — read it for the order.

The order is load-bearing: Neutron is fetched BEFORE TC attach, so the first packet sees a populated trie. A flow classified against an empty trie is miskeyed permanently, because dst_zone is part of FlowKey.

docs/architecture/boot-and-recovery.md#boot-sequence

func New

func New(opts Options) (*Agent, error)

New constructs the agent, reading top-to-bottom as the composition order. The HTTP listener opens immediately so Agent.Addr is usable before Agent.Run — tests bind ":0" and read the resolved port.

func (*Agent) Addr

func (a *Agent) Addr() string

Addr returns the address the HTTP server is bound to. Stable as soon as New returns; remains valid after Run starts and after it returns.

func (*Agent) Run

func (a *Agent) Run(ctx context.Context) error

Run starts the [Agent.workers] goroutines and the HTTP server, blocking until ctx is cancelled or the server fails. The workers list is the single source of truth — a new long-lived goroutine means a new row there and nothing else.

Shutdown stops accepting requests, then cancels and awaits each worker in list order, so the scraper's final tick lands before the WAL's final flush snapshots it and a clean shutdown loses no billing data. The same drain runs when the server itself fails.

TC programs are deliberately NOT detached — the qdisc and filter outlive the process, and the next start replaces them idempotently.

func (*Agent) SeedServerSettled

func (a *Agent) SeedServerSettled(records []state.ServerSettledRecord)

SeedServerSettled seeds the agent's server-settled accumulator from the WAL's server_settled section (v4+). Lifecycle is re-derived on the next reconcile's Nova-list prune after restore.

func (*Agent) SeedState

func (a *Agent) SeedState(records []state.Record)

SeedState seeds the agent's state.GlobalState from records, intended to run between New and [Run] (for example, after a WAL restore on boot). Takes the state's write lock; safe to call before any other goroutine touches the agent.

func (*Agent) SeedTenantSettled

func (a *Agent) SeedTenantSettled(records []state.TenantSettledRecord)

SeedTenantSettled seeds the agent's settled-bytes accumulator, the companion of Agent.SeedState for the WAL's settled section.

func (*Agent) SeedTotalSettled

func (a *Agent) SeedTotalSettled(records []state.TotalSettledRecord)

SeedTotalSettled seeds the agent's total-settled accumulator from the WAL's total_settled section (v5+) — the dead projects' history that keeps the total tier monotone across restarts.

func (*Agent) WALMetrics

func (a *Agent) WALMetrics() *wal.Metrics

WALMetrics returns the WAL instrument bundle the agent registered with its prometheus.Registry. The boot path reads a.mx.wal directly; this accessor exists for the package's external tests, which record load-fallback observations on the same Metrics that the periodic flush contributes timings to.

type BPFMapReader

type BPFMapReader struct {
	// contains filtered or unexported fields
}

BPFMapReader implements scraper.MapReader over a kernel PERCPU_HASH map (telemetry_map). The buffers are allocated once at construction and reused across ticks; BatchLookup itself is allocation-free in steady state.

func NewBPFMapReader

func NewBPFMapReader(m *ebpf.Map) (*BPFMapReader, error)

NewBPFMapReader wraps an *ebpf.Map (telemetry_map). The map must be a PERCPU_HASH with key type bpf.FlowKey and value type bpf.FlowMetrics; constructor errors otherwise.

func (*BPFMapReader) BatchLookup

func (r *BPFMapReader) BatchLookup(dst map[bpf.FlowKey]bpf.FlowMetrics) error

BatchLookup drains the kernel map in chunks of up to [batchSize] keys per syscall, aggregating per-CPU values into a single bpf.FlowMetrics per key and writing the result into dst.

Caller is responsible for clearing dst before invocation; the scraper does this.

type Options

type Options struct {
	Config     config.Config
	ConfigPath string
	Reader     scraper.MapReader
	Log        *logging.Handle
	// Resolver maps FlowKey → tenant_id label. nil means a
	// [metadata.NewResolver] wrapping the Agent's own
	// [metadata.ShardedMetadataMap], which starts empty and is
	// populated by Bootstrap (Linux) from Neutron. Tests can
	// inject a mock resolver to pin label outputs without
	// pre-populating the metadata map.
	Resolver metrics.TenantResolver
	// Stats reads the kernel telemetry_stats counters once per
	// scrape drain (see [telemetryFillReader]). nil disables the
	// drain — the lachesis_bpf_update_failures_total series stay
	// zero-seeded — which is the case on darwin and in unit tests;
	// the Linux Bootstrap always wires it.
	Stats *bpf.StatsReader
	// Sequencer is the boot phase sequencer the agent's phase-gated
	// workers await. Bootstrap passes the one it advances so the agent
	// and the boot steps share a single sequencer; nil means New
	// constructs a fresh one (unit-test agents, which never advance it).
	Sequencer *boot.Sequencer
}

Options bundles the inputs to New. ConfigPath is the YAML file the runtime.Manager will re-read on SIGHUP; empty disables SIGHUP reload while keeping /debug functional.