stats

package
v1.36.0 Latest Latest
Warning

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

Go to latest
Published: Mar 23, 2026 License: MPL-2.0 Imports: 13 Imported by: 0

Documentation

Index

Constants

View Source
const (
	MinRetentionWeeks     = 1
	DefaultRetentionWeeks = 2
	MaxRetentionWeeks     = 4 // Hard maximum, not overridable
)

Retention constants - hard limits per design agreement

View Source
const (
	ScaleNormal    = "NORMAL"         // 0 – 9,999
	ScaleLarge     = "LARGE"          // 10,000 – 49,999
	ScaleVeryLarge = "VERY_LARGE"     // 50,000 – 99,999
	ScaleHuge      = "HUGE"           // 100,000 – 249,999
	ScaleExtreme   = "EXTREME"        // 250,000 – 499,999
	ScaleCritical  = "CRITICAL_SCALE" // 500,000+
)

Scale levels for set size classification

View Source
const (
	ScaleNumNormal    = 0
	ScaleNumLarge     = 1
	ScaleNumVeryLarge = 2
	ScaleNumHuge      = 3
	ScaleNumExtreme   = 4
	ScaleNumCritical  = 5
)

Scale level numeric values for Prometheus export

View Source
const (
	ThresholdLarge     = 10_000
	ThresholdVeryLarge = 50_000
	ThresholdHuge      = 100_000
	ThresholdExtreme   = 250_000
	ThresholdCritical  = 500_000
)

Thresholds for scale levels

View Source
const SchemaVersion = 2

SchemaVersion is the current JSON schema version Increment when making breaking changes to the JSON structure

Variables

This section is empty.

Functions

func CanCreateProfile

func CanCreateProfile(profileDir string, maxCount int) bool

CanCreateProfile checks if we can create a new profile without exceeding limits

func CleanupHistory

func CleanupHistory(historyDir string, retentionDays int, maxCount int) error

CleanupHistory removes history files older than retention days. Also enforces a maximum file count to prevent unbounded growth.

func CleanupProfiles

func CleanupProfiles(profileDir string, retentionDays int, maxCount int) error

CleanupProfiles removes profile files older than retention days. Also enforces maximum profile count as a HARD LIMIT.

func CleanupReports

func CleanupReports(reportsDir string, retentionDays int) error

CleanupReports removes report files older than retention days. Handles both daily/ subdirectory and root report files.

func FileExists

func FileExists(path string) bool

FileExists checks if a file exists

func FileModTime

func FileModTime(path string) (int64, error)

FileModTime returns the modification time of a file Returns zero time if file doesn't exist

func GetProfileCount

func GetProfileCount(profileDir string) int

GetProfileCount returns the number of profile files in the directory

func ReadJSON

func ReadJSON(path string, data interface{}) error

ReadJSON reads a JSON file, tolerating missing/partial files. Returns nil, nil if file doesn't exist (not an error). Returns data, nil on success. Returns nil, error on parse failure.

func WriteJSONAtomic

func WriteJSONAtomic(path string, data interface{}) error

WriteJSONAtomic writes data to a file atomically. Pattern: write to temp file -> fsync -> rename This ensures the file is never partially written.

Types

type Alert

type Alert struct {
	Level     string    `json:"level"` // "warning" or "critical"
	Type      string    `json:"type"`  // "memory", "goroutines", etc.
	Message   string    `json:"message"`
	Timestamp time.Time `json:"timestamp"`
	Value     float64   `json:"value"`
	Threshold float64   `json:"threshold"`
}

Alert represents an active alert

type Collector

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

Collector gathers and persists runtime statistics

func NewCollector

func NewCollector(config *Config) *Collector

NewCollector creates a new stats collector

func (*Collector) Collect

func (c *Collector) Collect() *Snapshot

Collect gathers current runtime statistics

func (*Collector) GetConfig

func (c *Collector) GetConfig() *Config

GetConfig returns the collector configuration

func (*Collector) RecordBan

func (c *Collector) RecordBan()

RecordBan increments the ban counter

func (*Collector) RecordEvent

func (c *Collector) RecordEvent()

RecordEvent increments the event counter

func (*Collector) RecordIPCRequest

func (c *Collector) RecordIPCRequest(latencyNs int64, success bool)

RecordIPCRequest records an IPC request with latency

func (*Collector) RecordModuleEvent

func (c *Collector) RecordModuleEvent(name string)

RecordModuleEvent increments a module's event counter

func (*Collector) RecordUnban

func (c *Collector) RecordUnban()

RecordUnban increments the unban counter

func (*Collector) SetDaemonMode

func (c *Collector) SetDaemonMode(mode string)

SetDaemonMode sets the current daemon operating mode

func (*Collector) SetModuleStatus

func (c *Collector) SetModuleStatus(name, status string)

SetModuleStatus updates module status

func (*Collector) SetServerInfo

func (c *Collector) SetServerInfo(hostname, region, os, kernel, arch string)

SetServerInfo sets server inventory information

func (*Collector) SetVersion

func (c *Collector) SetVersion(version string)

SetVersion sets the daemon version in stats

func (*Collector) SetWatchdogState

func (c *Collector) SetWatchdogState(status int, mode string, cpuScore, memScore, ioScore float64)

SetWatchdogState sets the current watchdog pressure state

func (*Collector) Start

func (c *Collector) Start(ctx context.Context)

Start begins the stats collection goroutines Returns immediately if stats collection is disabled (no background work)

type Config

type Config struct {
	// Enable stats collection (default: true)
	Enabled bool

	// Collection intervals
	LiveInterval time.Duration // Memory/goroutines (default: 60s)
	IOInterval   time.Duration // Events/throughput (default: 300s)

	// File paths
	CurrentFile string // current.json path
	HistoryDir  string // history/ directory
	ProfileDir  string // profiles/ directory

	// Retention limits
	// Local retention is capped at 4 weeks maximum (28 days)
	// Long-term storage is user's responsibility via external TSDB
	HistoryRetentionDays int // Days to keep history (default: 14, max: 28)
	ProfileRetentionDays int // Days to keep profiles (default: 7)
	ProfileMaxCount      int // Max profiles to keep (default: 10)

	// Thresholds
	MemoryWarnMB      float64 // Warning threshold (default: 200)
	MemoryCritMB      float64 // Critical threshold (default: 500)
	GoroutinesWarn    int     // Warning threshold (default: 100)
	GoroutinesCrit    int     // Critical threshold (default: 500)
	StaleThresholdSec int     // Stale data threshold (default: 300)

	// Profiling
	ProfileEnabled     bool // pprof enabled (default: false)
	ProfileAutoCapture bool // Auto-capture on breach (default: false)

	// Logging
	LogDir     string // Watchdog log directory
	StatsLog   string // Stats log file
	AlertsLog  string // Alerts log file
	ProfileLog string // Profile log file

	// Reports
	ReportsEnabled       bool   // Enable report generation (default: true)
	ReportsDir           string // Reports output directory
	ReportsRetentionDays int    // Days to keep daily reports (default: 14, max: 28)
}

Config holds stats collection configuration All fields have safe defaults for backwards compatibility

func DefaultConfig

func DefaultConfig() *Config

DefaultConfig returns configuration with safe defaults Used when config keys are missing for backwards compatibility

func (*Config) IsProfileEnabled

func (c *Config) IsProfileEnabled() bool

IsProfileEnabled returns true if profiling is enabled

func (*Config) IsStatsEnabled

func (c *Config) IsStatsEnabled() bool

IsStatsEnabled returns true if stats collection is enabled Used to check before starting any background work

func (*Config) Validate

func (c *Config) Validate()

Validate checks config values and applies safe bounds

type Daemon

type Daemon struct {
	Version       string `json:"version"`
	UptimeSeconds int64  `json:"uptime_seconds"`
	PID           int    `json:"pid"`
	Mode          string `json:"mode"` // "normal", "degraded", "survival"
}

Daemon contains daemon identification info

type DailyStats

type DailyStats struct {
	SchemaVersion int       `json:"schema_version"`
	Date          string    `json:"date"` // YYYY-MM-DD
	GeneratedAt   time.Time `json:"generated_at"`

	// Peak values for the day
	PeakMemoryMB   float64 `json:"peak_memory_mb"`
	PeakGoroutines int     `json:"peak_goroutines"`
	PeakBansPerMin float64 `json:"peak_bans_per_min"`

	// Totals for the day
	TotalBans        int64 `json:"total_bans"`
	TotalUnbans      int64 `json:"total_unbans"`
	TotalEvents      int64 `json:"total_events"`
	TotalIPCRequests int64 `json:"total_ipc_requests"`
	TotalIPCErrors   int64 `json:"total_ipc_errors"`

	// Averages for the day
	AvgMemoryMB   float64 `json:"avg_memory_mb"`
	AvgGoroutines float64 `json:"avg_goroutines"`
	AvgLatencyMs  float64 `json:"avg_latency_ms"`

	// Alert counts
	WarningCount  int `json:"warning_count"`
	CriticalCount int `json:"critical_count"`

	// Sample count (for averaging)
	SampleCount int `json:"sample_count"`
}

DailyStats contains aggregated daily statistics Stored in history/ directory

func NewDailyStats

func NewDailyStats(date string) *DailyStats

NewDailyStats creates a new daily stats struct

type IPC

type IPC struct {
	RequestsTotal int64   `json:"requests_total"`
	AvgLatencyMs  float64 `json:"avg_latency_ms"`
	ErrorsTotal   int64   `json:"errors_total"`
}

IPC contains IPC communication metrics

type ModuleStats

type ModuleStats struct {
	Status     string
	EventCount atomic.Int64
}

ModuleStats tracks per-module statistics

type ModuleStatus

type ModuleStatus struct {
	Status string `json:"status"`
	Events int64  `json:"events"`
}

ModuleStatus contains status for a single module

type ProfileInfo

type ProfileInfo struct {
	Filename    string    `json:"filename"`
	Type        string    `json:"type"` // "heap", "cpu", "goroutine", "block"
	CreatedAt   time.Time `json:"created_at"`
	SizeBytes   int64     `json:"size_bytes"`
	DurationSec int       `json:"duration_sec,omitempty"` // For CPU profiles
}

ProfileInfo contains metadata about a saved profile

type Runtime

type Runtime struct {
	MemoryHeapMB  float64 `json:"memory_heap_mb"`
	MemoryAllocMB float64 `json:"memory_alloc_mb"`
	MemorySysMB   float64 `json:"memory_sys_mb"`
	Goroutines    int     `json:"goroutines"`
	GCCycles      uint32  `json:"gc_cycles"`
	GCPauseMs     float64 `json:"gc_pause_ms"`
}

Runtime contains Go runtime metrics

type Server

type Server struct {
	Hostname string `json:"hostname"`
	Region   string `json:"region"` // Cloud region or datacenter
	OS       string `json:"os"`
	Kernel   string `json:"kernel"`
	Arch     string `json:"arch"`
}

Server contains server inventory information

type SetCountEntry

type SetCountEntry struct {
	Count          int64  `json:"count"`
	Scale          string `json:"scale"`
	ScaleNum       int    `json:"scale_num"`
	Display        string `json:"display"`
	LastReconciled string `json:"last_reconciled"`
	Trend          string `json:"trend"`
}

SetCountEntry is per-set data in the snapshot

type SetCountSnapshot

type SetCountSnapshot struct {
	Timestamp        string                   `json:"timestamp"`
	DaemonPID        int                      `json:"daemon_pid"`
	ScaleMode        string                   `json:"scale_mode"`
	ExporterInterval int                      `json:"exporter_interval_seconds"`
	Sets             map[string]SetCountEntry `json:"sets"`
}

SetCountSnapshot is the JSON-serializable snapshot of all counters

type SetCounters

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

SetCounters tracks per-set element counts in daemon memory. Updated atomically on every add/delete/flush/replace operation.

func NewSetCounters

func NewSetCounters(cacheDir string) *SetCounters

NewSetCounters creates a new counter tracker

func (*SetCounters) Add

func (sc *SetCounters) Add(setName string, delta int64)

Add adjusts the count by delta (positive for adds, negative for deletes)

func (*SetCounters) AllSets

func (sc *SetCounters) AllSets() []string

AllSets returns the names of all tracked sets

func (*SetCounters) CacheWriterLoop

func (sc *SetCounters) CacheWriterLoop(ctx context.Context)

CacheWriterLoop runs the background cache file writer Writes every 10 seconds if dirty

func (*SetCounters) Get

func (sc *SetCounters) Get(setName string) int64

Get returns the current count for a set

func (*SetCounters) GlobalScale

func (sc *SetCounters) GlobalScale() string

GlobalScale returns the highest scale level across all sets

func (*SetCounters) RecommendedExporterInterval

func (sc *SetCounters) RecommendedExporterInterval() time.Duration

RecommendedExporterInterval returns the recommended exporter interval based on global scale

func (*SetCounters) ReconcileInterval

func (sc *SetCounters) ReconcileInterval() time.Duration

ReconcileInterval returns the recommended reconciliation interval

func (*SetCounters) Scale

func (sc *SetCounters) Scale(setName string) string

Scale returns the scale level for a set

func (*SetCounters) ScaleNum

func (sc *SetCounters) ScaleNum(setName string) int

ScaleNum returns the numeric scale level for Prometheus

func (*SetCounters) Set

func (sc *SetCounters) Set(setName string, count int64)

Set sets the count for a set to an absolute value Used after replace_set, load_cidrs, flush_set, and reconciliation

func (*SetCounters) SetReconciled

func (sc *SetCounters) SetReconciled(setName string, count int64)

SetReconciled marks when a set was last reconciled against the kernel

func (*SetCounters) Snapshot

func (sc *SetCounters) Snapshot() SetCountSnapshot

Snapshot returns a JSON-serializable snapshot of all counters

func (*SetCounters) WriteCacheFile

func (sc *SetCounters) WriteCacheFile() error

WriteCacheFile writes the snapshot to /run/nftban/set_counts.json Debounced: only writes if dirty and at least 10 seconds since last write

type Snapshot

type Snapshot struct {
	SchemaVersion int                     `json:"schema_version"`
	Timestamp     time.Time               `json:"timestamp"`
	Daemon        Daemon                  `json:"daemon"`
	Runtime       Runtime                 `json:"runtime"`
	Throughput    Throughput              `json:"throughput"`
	IPC           IPC                     `json:"ipc"`
	Watchdog      Watchdog                `json:"watchdog"`
	Server        Server                  `json:"server"`
	Modules       map[string]ModuleStatus `json:"modules"`
	Health        string                  `json:"health"`
	Alerts        []Alert                 `json:"alerts"`
}

Snapshot represents a point-in-time stats snapshot Written to current.json by the daemon

func NewSnapshot

func NewSnapshot() *Snapshot

NewSnapshot creates a new snapshot with schema version set

type Throughput

type Throughput struct {
	BansTotal    int64   `json:"bans_total"`
	UnbansTotal  int64   `json:"unbans_total"`
	EventsTotal  int64   `json:"events_total"`
	BansPerMin   float64 `json:"bans_per_min"`
	EventsPerMin float64 `json:"events_per_min"`
}

Throughput contains event processing metrics

type Watchdog

type Watchdog struct {
	Status   int     `json:"status"`    // 1 = running, 0 = not running
	Mode     string  `json:"mode"`      // "normal", "degraded", "survival"
	CPUScore float64 `json:"cpu_score"` // 0-100 pressure score
	MemScore float64 `json:"mem_score"` // 0-100 pressure score
	IOScore  float64 `json:"io_score"`  // 0-100 pressure score
}

Watchdog contains pressure monitoring metrics

Jump to

Keyboard shortcuts

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