storage

package
v0.30.5 Latest Latest
Warning

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

Go to latest
Published: Sep 29, 2026 License: MIT Imports: 12 Imported by: 0

Documentation

Overview

Package storage persists aggregated traffic into SQLite and answers the ranking / time-series queries the API exposes. It uses the pure-Go modernc.org/sqlite driver so the binary needs no system SQLite.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func PrepareDir added in v0.21.0

func PrepareDir(dir, defaultDir string) error

PrepareDir readies the directory that will hold the database.

The daemon's data directory holds a complete record of which process talked to which host and when, so it must not be reachable by other local accounts. The directory mode is what actually gates that: with 0700 no other user can open anything inside, including the SQLite sidecar files that are created lazily and so cannot be restricted up front. macOS applies the same rule to its own daemon state (/var/db/dhcpclient is 0700 root:wheel).

A directory that already exists keeps its mode, with one exception: netscope's own default location, which earlier versions created 0755 and which nothing else has a claim on. Anywhere else the operator pointed --db is theirs — a shared directory, or the working directory for a relative path — and silently dropping group access from it would be a surprise, so PrepareDir leaves it be and the database file's own 0600 does the work.

Types

type IfaceUsage added in v0.12.0

type IfaceUsage struct {
	Iface string
	Rx    uint64
	Tx    uint64
}

IfaceUsage is one interface's total rx/tx over a queried range.

type Store

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

Store is a handle to the netscope database.

func Open

func Open(path string) (*Store, error)

Open opens (creating if needed) the SQLite database at path and applies the schema and connection pragmas. If the existing database is corrupt (e.g. after power loss), it is quarantined aside and a fresh one is created — otherwise a fatal Open error would brick the daemon in a launchd KeepAlive crash loop until someone manually deletes the file.

func (*Store) AddIfaceUsage added in v0.12.0

func (s *Store) AddIfaceUsage(iface string, day int64, rx, tx uint64) error

AddIfaceUsage folds rx/tx bytes into the given interface's daily total. day is unix seconds at local midnight. A no-op when iface is empty or both are zero.

func (*Store) AppTimeSeries added in v0.5.0

func (s *Store) AppTimeSeries(ctx context.Context, app string, since, until time.Time, step time.Duration) ([]types.TimePoint, error)

AppTimeSeries returns one app's rx/tx bucketed into intervals of step over [since, until). Empty intervals are omitted.

func (*Store) Apps

func (s *Store) Apps(ctx context.Context, since, until time.Time) ([]types.AppTraffic, error)

Apps returns per-app totals over [since, until), ranked by total bytes. Whole days come from the daily rollup and only the partial edges touch the raw samples: aggregating a week of 10s buckets took ~600ms and grew with retention, while the rollup answers the same question in ~15ms.

func (*Store) Checkpoint added in v0.5.0

func (s *Store) Checkpoint()

Checkpoint flushes the WAL back into the main database and truncates it, so the WAL file can't grow without bound. Best-effort.

func (*Store) Close

func (s *Store) Close() error

Close closes the underlying database.

func (*Store) Domains

func (s *Store) Domains(ctx context.Context, since, until time.Time) ([]types.DomainStat, error)

Domains returns per-domain totals over [since, until), ranked by total bytes. Whole days come from the daily rollup (see Apps).

func (*Store) DomainsForApp added in v0.5.0

func (s *Store) DomainsForApp(ctx context.Context, app string, since, until time.Time) ([]types.DomainStat, error)

DomainsForApp returns per-domain totals for a single app over [since, until), ranked by total bytes — backs the dashboard's per-app drill-down.

func (*Store) EnforceSizeCap added in v0.5.0

func (s *Store) EnforceSizeCap(maxBytes int64) (bool, error)

EnforceSizeCap is the disk safety net: independent of time-based retention, it drops the oldest data (a day at a time) until the database fits under maxBytes. It checkpoints + vacuums between steps so on-disk size reflects each deletion. Returns whether anything was removed. A non-positive cap disables it.

func (*Store) FlushApps

func (s *Store) FlushApps(bucket int64, apps []types.AppTraffic) error

FlushApps adds the per-app counters for the given bucket. Repeated flushes to the same bucket accumulate rather than overwrite.

func (*Store) FlushDomains

func (s *Store) FlushDomains(bucket int64, domains []types.DomainStat) error

FlushDomains adds the per-domain counters for the given bucket.

func (*Store) IfaceUsageAllSince added in v0.12.0

func (s *Store) IfaceUsageAllSince(ctx context.Context, sinceDay int64) ([]IfaceUsage, error)

IfaceUsageAllSince returns per-interface totals for every interface with usage on or after sinceDay (unix seconds at local midnight), most-used first.

func (*Store) Purge

func (s *Store) Purge(before time.Time) (bool, error)

Purge deletes samples older than before, for retention management. It reports whether any rows were actually removed (so the caller can decide to VACUUM).

func (*Store) SizeOnDisk added in v0.5.0

func (s *Store) SizeOnDisk() int64

SizeOnDisk returns the total bytes the database occupies, including the WAL and shared-memory side files (which can dominate between checkpoints).

func (*Store) TimeSeries

func (s *Store) TimeSeries(ctx context.Context, since, until time.Time, step time.Duration) ([]types.TimePoint, error)

TimeSeries returns rx/tx totals bucketed into intervals of step over [since, until). Empty intervals are omitted.

func (*Store) Vacuum added in v0.5.0

func (s *Store) Vacuum() error

Vacuum rebuilds the database, reclaiming pages freed by deletes so the file actually shrinks on disk. It rewrites the whole file, so call it sparingly.

func (*Store) VacuumIfWorthwhile added in v0.18.4

func (s *Store) VacuumIfWorthwhile() error

VacuumIfWorthwhile vacuums only when enough of the file is dead space to justify rewriting it. The hourly retention purge always frees *something*, and unconditionally vacuuming after it rewrote the whole database every hour — steady IO/battery burn for a few reclaimed KB. Threshold: free pages exceed 20% of the file and at least ~8MB.

func (*Store) VerifyRollups added in v0.19.1

func (s *Store) VerifyRollups(days int) (bool, error)

VerifyRollups re-checks the last `days` local days: for each one it compares the rollup's totals against the raw samples and rebuilds any day that disagrees. The rollup is what the dashboard's ranked lists are read from, so a divergence would show wrong numbers with nothing to notice it — this makes the database self-correcting instead of trusting that every write path stays in step forever. Bounded to a few days so it stays cheap enough to run from the hourly maintenance pass. Reports whether anything was repaired.

Jump to

Keyboard shortcuts

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