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 ¶
- func PrepareDir(dir, defaultDir string) error
- type IfaceUsage
- type Store
- func (s *Store) AddIfaceUsage(iface string, day int64, rx, tx uint64) error
- func (s *Store) AppTimeSeries(app string, since, until time.Time, step time.Duration) ([]types.TimePoint, error)
- func (s *Store) Apps(since, until time.Time) ([]types.AppTraffic, error)
- func (s *Store) Checkpoint()
- func (s *Store) Close() error
- func (s *Store) Domains(since, until time.Time) ([]types.DomainStat, error)
- func (s *Store) DomainsForApp(app string, since, until time.Time) ([]types.DomainStat, error)
- func (s *Store) EnforceSizeCap(maxBytes int64) (bool, error)
- func (s *Store) FlushApps(bucket int64, apps []types.AppTraffic) error
- func (s *Store) FlushDomains(bucket int64, domains []types.DomainStat) error
- func (s *Store) IfaceUsageAllSince(sinceDay int64) ([]IfaceUsage, error)
- func (s *Store) Purge(before time.Time) (bool, error)
- func (s *Store) SizeOnDisk() int64
- func (s *Store) TimeSeries(since, until time.Time, step time.Duration) ([]types.TimePoint, error)
- func (s *Store) Vacuum() error
- func (s *Store) VacuumIfWorthwhile() error
- func (s *Store) VerifyRollups(days int) (bool, error)
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func PrepareDir ¶ added in v0.21.0
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
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 ¶
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
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(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 ¶
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) Domains ¶
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
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
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(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 ¶
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
SizeOnDisk returns the total bytes the database occupies, including the WAL and shared-memory side files (which can dominate between checkpoints).
func (*Store) TimeSeries ¶
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
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
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
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.