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
- func New() engine.Plugin
- type EvalCandidate
- type IdentityRedactor
- type Plugin
- func (p *Plugin) Capabilities() []engine.Capability
- func (p *Plugin) ConfigSchema() []byte
- func (p *Plugin) Dependencies() []string
- func (p *Plugin) Emissions() []string
- func (p *Plugin) ID() string
- func (p *Plugin) Init(ctx engine.PluginContext) error
- func (p *Plugin) Name() string
- func (p *Plugin) Ready() error
- func (p *Plugin) Requires() []engine.Requirement
- func (p *Plugin) SetRandSource(rng *rand.Rand)
- func (p *Plugin) SetRedactor(r Redactor)
- func (p *Plugin) Shutdown(_ context.Context) error
- func (p *Plugin) Subscriptions() []engine.EventSubscription
- func (p *Plugin) Version() string
- type Redactor
Constants ¶
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 ¶
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.
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 ¶
ConfigSchema implements engine.ConfigSchemaProvider.
func (*Plugin) Dependencies ¶
func (*Plugin) Emissions ¶
Emissions documents the single event type this plugin may emit on capture.
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) Requires ¶
func (p *Plugin) Requires() []engine.Requirement
func (*Plugin) SetRandSource ¶
SetRandSource injects a deterministic *rand.Rand for rate sampling. Tests pin the seed so a `rate: 0.5` case is reproducible.
func (*Plugin) SetRedactor ¶
SetRedactor swaps the redactor used for journal snapshots. Tests inject drop-style redactors here; production runs leave the IdentityRedactor in place.
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.
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.