telemetry

Documentation

Overview

Package telemetry is the agent-side raw-telemetry tier's control plane (#424, ADR 0001). It wraps the dedicated ports.TelemetryStore with the honesty contract the columnar tier must uphold: ingest is BOUNDED and BACKPRESSURED (overflow at the store-rate stage, or a lost upstream batch seen as a sequence gap, is reported as a telemetry gap on the affected host — never a silent drop); retention is tiered with AUDITED expiry; a sampled window is never presented as complete; and the three retro-hunt patterns are served, including retro-running a detection rule over the hot window.

The columnar store is reached ONLY through the port and appears in no domain type.

Index

• type IngestReport
• type Service
  • func NewService(store ports.TelemetryStore, audit ports.AuditLogger, clock ports.Clock, ...) (*Service, error)
  • func (s *Service) Footprint(ctx context.Context) (ports.TelemetryFootprint, error)
  • func (s *Service) Hunt(ctx context.Context, q ports.HuntQuery) (ports.HuntResult, error)
  • func (s *Service) Ingest(ctx context.Context, batch ports.TelemetryBatch) (IngestReport, error)
  • func (s *Service) RetroRunRule(ctx context.Context, q ports.HuntQuery) ([]detection.Detection, ports.HuntResult, error)
  • func (s *Service) Sweep(ctx context.Context) (ports.SweepReport, error)

Types

type IngestReport

type IngestReport struct {
	Accepted int
	Dropped  int // shed because the batch exceeded the ingest budget; reported, never silent
	Gap      *ports.TelemetrySequenceGap
}

IngestReport is the honest outcome of one ingest: how many events were accepted, how many were shed at the store-rate stage, and any sequence gap (an upstream — agent/transport — loss made visible).

type Service

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

Service is the telemetry tier control plane.

func NewService

func NewService(store ports.TelemetryStore, audit ports.AuditLogger, clock ports.Clock, budget int) (*Service, error)

NewService validates dependencies. budget > 0 bounds a single ingest; <= 0 is refused (an unbounded telemetry ingest is the failure mode this tier exists to avoid).

func (*Service) Footprint

func (s *Service) Footprint(ctx context.Context) (ports.TelemetryFootprint, error)

Footprint reports the store size so spend is observable.

func (*Service) Hunt

func (s *Service) Hunt(ctx context.Context, q ports.HuntQuery) (ports.HuntResult, error)

Hunt runs a retro-hunt query and returns its result WITH the completeness metadata (sampled / gaps), so a sampled or lossy window is never presented as complete.

func (*Service) Ingest

func (s *Service) Ingest(ctx context.Context, batch ports.TelemetryBatch) (IngestReport, error)

Ingest admits one batch under the coherent ingest budget. Two stages can report a telemetry gap:

• a sequence gap vs. the last batch stored for this (host, class) — an upstream loss made visible;
• the batch exceeding the store-rate budget — the overflow is shed and reported, never dropped silently.

Either gap is audited on the affected host. The accepted prefix is persisted with its sampling rate.

func (*Service) RetroRunRule

func (s *Service) RetroRunRule(ctx context.Context, q ports.HuntQuery) ([]detection.Detection, ports.HuntResult, error)

RetroRunRule re-runs the shipped detection rules for a class over the hot window and returns the detections that WOULD have fired, alongside the hunt result (so the caller sees whether the window it hunted was complete). This is the first of the three acceptance patterns.

func (*Service) Sweep

func (s *Service) Sweep(ctx context.Context) (ports.SweepReport, error)

Sweep enforces the retention tiers and AUDITS the expiry (never a silent deletion): the warm window is down-sampled and past-warm data is expired, with the counts recorded.