engine

package
v0.16.0 Latest Latest
Warning

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

Go to latest
Published: Aug 4, 2026 License: MIT Imports: 11 Imported by: 0

Documentation

Overview

Package engine is the heart of netscope: it consumes attributed flows, resolves each to an owning app and a domain, and maintains two sets of counters:

  • window accumulators: reset every Bucket and flushed to storage. These back the historical (today/week) queries.
  • session accumulators: cumulative since the daemon started, never reset on flush. These back the LIVE dashboard tables, so the view grows steadily instead of emptying every flush interval.

Instantaneous rates are derived from monotonic lifetime totals.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Config

type Config struct {
	// Bucket is the storage flush granularity; window counters accumulate for
	// one bucket then get written and reset.
	Bucket time.Duration
	// SnapshotInterval is how often the live snapshot is recomputed.
	SnapshotInterval time.Duration
	// Retention bounds how long stored samples are kept; zero disables purging.
	Retention time.Duration
	// MaxDBBytes is a hard disk safety net: when the database (incl. WAL) exceeds
	// it, the oldest data is dropped until it fits, regardless of Retention. Zero
	// disables the cap.
	MaxDBBytes int64
	// Interface is the capture source name, surfaced in snapshots.
	Interface string
	// LiveTopN caps how many apps/domains the live snapshot carries.
	LiveTopN int
	// ActiveWindow defines "active now": apps/domains with traffic newer than
	// this are counted as active.
	ActiveWindow time.Duration
	// SessionHorizon prunes session entries idle longer than this to bound
	// memory on long-running daemons. Zero keeps everything for the session.
	SessionHorizon time.Duration
	// SelfPID, when non-zero, is the daemon's own PID; its traffic (e.g. update
	// checks) is excluded from accounting.
	SelfPID int
	// Hinter receives remote IPs with no known hostname for reverse-DNS
	// resolution. Optional.
	Hinter HostHinter
}

Config tunes the engine timings.

type Engine

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

Engine owns the accumulators and coordinates flushing/snapshots.

func New

func New(cfg Config, res Resolver, dns *dnscache.Cache, store *storage.Store) *Engine

New constructs an Engine. res may be nil (everything attributes to "unknown"); store may be nil to run without persistence.

func (*Engine) Connections added in v0.11.0

func (e *Engine) Connections(activeWithin time.Duration) []types.Connection

Connections returns connections seen within activeWithin, most-active first. activeWithin <= 0 returns all tracked (un-pruned) connections.

func (*Engine) RateHistory added in v0.8.0

func (e *Engine) RateHistory() []types.RatePoint

RateHistory returns a copy of the recent per-second rate samples.

func (*Engine) ResetSession added in v0.13.0

func (e *Engine) ResetSession()

ResetSession zeroes the live session counters (apps/domains/connections and the session totals) and restarts the session clock — a "measure from now" reset. Stored history (today/week/month) and per-interface usage are left intact. Safe to call from any goroutine; the work runs in the Run loop.

func (*Engine) Run

func (e *Engine) Run(ctx context.Context, flows <-chan types.Flow) error

Run consumes flows until the context is cancelled, driving periodic flushes and snapshots. It returns ctx.Err() on shutdown after a final flush.

func (*Engine) SetInterface added in v0.6.0

func (e *Engine) SetInterface(name string)

SetInterface updates the capture-interface name surfaced in snapshots (the supervisor calls this when it (re)opens on a different interface).

func (*Engine) SetPaused added in v0.10.0

func (e *Engine) SetPaused(p bool)

SetPaused records whether capture is suspended, for snapshot reporting.

func (*Engine) Snapshot

func (e *Engine) Snapshot() types.Snapshot

Snapshot returns the most recent live snapshot.

type HostHinter

type HostHinter interface {
	Enqueue(ip string)
}

HostHinter is notified of remote IPs that have no known hostname, so it can resolve them out-of-band (reverse DNS). Implemented by internal/revdns.

type Resolver

type Resolver interface {
	Lookup(types.ConnKey) (types.Process, bool)
}

Resolver maps a connection to its owning process. Implemented by internal/resolver (live, libproc) and internal/demo (synthetic).

Jump to

Keyboard shortcuts

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