sampler

package
v0.33.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 20, 2026 License: MIT Imports: 15 Imported by: 0

Documentation

Overview

Package sampler is the opt-in online sampler plugin. When enabled, it snapshots a fraction of live session journals (plus every failed session when failure_capture is on) to a local directory so the eval pipeline can later score them.

The plugin is off by default. Activation requires either an explicit `nexus.observe.sampler` entry in `plugins.active` or a `sampler:` config block with `enabled: true` — the engine itself never references sampler state. Configuration lives under the top-level `sampler:` key documented in docs/src/configuration/reference.md.

Index

Constants

View Source
const EvalCandidateEventType = "eval.candidate"

EvalCandidateEventType is the dotted bus event type emitted whenever the sampler captures a session. Downstream tooling (`nexus eval list-candidates`, future ingestion backends) subscribes to this type to learn about new captures.

Variables

This section is empty.

Functions

func New

func New() engine.Plugin

New creates a new online sampler plugin. Defaults to the IdentityRedactor and the package-level random source. Call SetRedactor / SetRandSource on the returned *Plugin from a test harness when needed.

Types

type EvalCandidate

type EvalCandidate struct {
	// SessionID is the source session whose journal was sampled.
	SessionID string `json:"session_id"`
	// CaseDir is the absolute on-disk path the sample was written to,
	// typically `<out_dir>/<session-id>`. The directory contains a `journal/`
	// subtree plus a `metadata.json`.
	CaseDir string `json:"case_dir"`
	// Reason is the short tag explaining why the sample was captured.
	// Currently one of:
	//   "sampled"          — rate-based capture
	//   "failure_capture"  — failed session captured regardless of rate
	Reason string `json:"reason"`
	// Warnings carries non-fatal advisories surfaced during snapshotting
	// (e.g. partial copy, redactor errors). Empty on the happy path.
	Warnings []string `json:"warnings,omitempty"`
}

EvalCandidate is the payload of an eval.candidate emission. The struct is intentionally small and stable — external harnesses pin against it, so any addition here is a deliberate, documented event.

type IdentityRedactor

type IdentityRedactor struct{}

IdentityRedactor returns the payload bytes unchanged. This is the default the sampler uses when no other Redactor is supplied.

func (IdentityRedactor) Redact

func (IdentityRedactor) Redact(_ string, payload []byte) ([]byte, error)

Redact implements Redactor.

type Plugin

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

Plugin is the engine.Plugin implementation. Constructed via New() — both cmd/nexus and embedders register it through pkg/engine/allplugins.

func (*Plugin) Capabilities

func (p *Plugin) Capabilities() []engine.Capability

func (*Plugin) ConfigSchema

func (p *Plugin) ConfigSchema() []byte

ConfigSchema implements engine.ConfigSchemaProvider.

func (*Plugin) Dependencies

func (p *Plugin) Dependencies() []string

func (*Plugin) Emissions

func (p *Plugin) Emissions() []string

Emissions documents the single event type this plugin may emit on capture.

func (*Plugin) ID

func (p *Plugin) ID() string

func (*Plugin) Init

func (p *Plugin) Init(ctx engine.PluginContext) error

Init parses config, validates rate, and prepares the output directory. When the config is absent (raw == nil) or `enabled: false`, Init succeeds as a no-op — Subscriptions returns nil for that case so the plugin draws zero traffic.

func (*Plugin) Name

func (p *Plugin) Name() string

func (*Plugin) Ready

func (p *Plugin) Ready() error

func (*Plugin) Requires

func (p *Plugin) Requires() []engine.Requirement

func (*Plugin) SetRandSource

func (p *Plugin) SetRandSource(rng *rand.Rand)

SetRandSource injects a deterministic *rand.Rand for rate sampling. Tests pin the seed so a `rate: 0.5` case is reproducible.

func (*Plugin) SetRedactor

func (p *Plugin) SetRedactor(r Redactor)

SetRedactor swaps the redactor used for journal snapshots. Tests inject drop-style redactors here; production runs leave the IdentityRedactor in place.

func (*Plugin) Shutdown

func (p *Plugin) Shutdown(_ context.Context) error

func (*Plugin) Subscriptions

func (p *Plugin) Subscriptions() []engine.EventSubscription

Subscriptions returns nothing when the plugin is disabled — the engine inventory tooling then surfaces a clean "no traffic" entry. The actual bus subscription happens in Init via ctx.Bus.Subscribe; this declaration is documentation for plugin manifests. There is no separate "session.failed" event in v1; failure capture is decided post-hoc by reading the session's metadata/session.json status field at sample time.

func (*Plugin) Version

func (p *Plugin) Version() string

type Redactor

type Redactor interface {
	// Redact rewrites or drops the payload bytes of a single envelope. The
	// returned slice replaces the original payload at copy time. Returning
	// nil signals "drop this payload entirely"; the envelope's metadata
	// (seq, type, ts) is preserved.
	Redact(eventType string, payload []byte) ([]byte, error)
}

Redactor is the pluggable hook for transforming or dropping bytes from individual journal envelopes before they are copied into the sample.

The contract is intentionally minimal: implementations receive an event type and the JSON-encoded payload bytes, and return the (possibly rewritten) payload bytes for the snapshot. v1 ships only an identity implementation — concrete PII / secret patterns are deferred to the caller. Keeping the interface in place from day one preserves the option without bloating the v1 surface.

Implementations must be safe to call concurrently; the sampler may snapshot multiple sessions in parallel.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL