telemetry

package

v0.1.11 Latest Latest Go to latest Published: Oct 8, 2026 License: MIT Imports: 4 Imported by: 0

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/Sir-Adnan/wg-guard

Links

Open Source Insights

Documentation ¶

Overview ¶

Package telemetry owns the bounded live operational snapshot shared by dashboard, API and metrics readers. It starts no goroutine; the node's central scheduler calls Sampler.Sample.

Index ¶

Constants
type Counter
type Health
type History
type Issues
- func (i Issues) Codes() []string
- func (i Issues) Has(issue Issues) bool
type Metric
type Point
type RawSample
type Sampler
- func New(source Source, cadence time.Duration) *Sampler
- func (s *Sampler) Sample(ctx context.Context, now time.Time) (Point, error)
- func (s *Sampler) Snapshot(now time.Time, limit int) History
type Source
type SourceFunc
- func (f SourceFunc) Read(ctx context.Context, now time.Time) (RawSample, error)
type UintMetric

Constants ¶

View Source

const (
	DefaultCadence  = 10 * time.Second
	HistoryCapacity = 180
)

Variables ¶

This section is empty.

Functions ¶

This section is empty.

Types ¶

type Counter ¶

type Counter struct {
	Identity  string
	RXBytes   uint64
	TXBytes   uint64
	Available bool
}

Counter carries internal continuity identity and cumulative byte counters. Identity is never copied into Point, so topology cannot leak to readers.

type Health ¶

type Health string

Health is the aggregate operational state of one point.

const (
	HealthHealthy     Health = "healthy"
	HealthDegraded    Health = "degraded"
	HealthUnavailable Health = "unavailable"
)

type History ¶

type History struct {
	Cadence   time.Duration
	Latest    Point
	Points    []Point
	Available bool
}

History is an immutable caller-owned view of the ring.

type Issues ¶

type Issues uint32

Issues is a bounded bitset of stable, non-secret health reasons.

const (
	IssueSourceUnavailable Issues = 1 << iota
	IssueHostMetricsUnavailable
	IssueHostNetworkUnavailable
	IssueVPNMetricsUnavailable
	IssueAWGInterfaceMissing
	IssueReadinessFailed
	IssueAccountingError
	IssueSampleStale
	IssueAccountingUnavailable
)

func (Issues) Codes ¶

func (i Issues) Codes() []string

Codes returns stable API-safe issue codes in deterministic order.

func (Issues) Has ¶

func (i Issues) Has(issue Issues) bool

Has reports whether an issue is present.

type Metric ¶

type Metric struct {
	Value     float64
	Available bool
}

Metric is a floating-point measurement whose zero can be meaningful.

type Point ¶

type Point struct {
	At time.Time

	CPUPercent       Metric
	MemoryUsedBytes  UintMetric
	MemoryTotalBytes UintMetric
	MemoryPercent    Metric
	DiskUsedBytes    UintMetric
	DiskTotalBytes   UintMetric
	DiskPercent      Metric
	Load1            Metric
	UptimeSeconds    UintMetric

	ProcessRSSBytes  UintMetric
	ProcessHeapBytes UintMetric
	Goroutines       UintMetric

	HostRXBytes UintMetric
	HostTXBytes UintMetric
	VPNRXBytes  UintMetric
	VPNTXBytes  UintMetric

	HostRXRate Metric
	HostTXRate Metric
	VPNRXRate  Metric
	VPNTXRate  Metric

	OnlineUsers        UintMetric
	ActivePeers        UintMetric
	EnabledInterfaces  UintMetric
	ObservedInterfaces UintMetric

	Health Health
	Issues Issues
}

Point is a value-only public telemetry point. It deliberately contains no interface names, subprocess errors, database errors or other topology.

type RawSample ¶

type RawSample struct {
	At time.Time

	HostAvailable     bool
	CPUPercent        *float64
	MemTotalBytes     uint64
	MemAvailableBytes uint64
	DiskTotalBytes    uint64
	DiskFreeBytes     uint64
	Load1             *float64
	Uptime            time.Duration

	ProcessRSSBytes         uint64
	ProcessHeapBytes        uint64
	ProcessMetricsAvailable bool
	Goroutines              uint64

	HostNetwork Counter
	VPNNetwork  Counter

	OnlineUsers       uint64
	ActivePeers       uint64
	ActivityAvailable bool

	EnabledInterfaces   uint64
	ObservedInterfaces  uint64
	InterfacesAvailable bool

	Ready              bool
	ReadinessAvailable bool

	RecentAccountingError bool
	AccountingAvailable   bool
}

RawSample is the collector-to-sampler contract. Availability flags make a real zero distinct from a source that could not be read.

type Sampler ¶

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

Sampler derives rates/health and owns the fixed-size history ring.

func New ¶

func New(source Source, cadence time.Duration) *Sampler

New constructs a sampler without starting background work.

func (*Sampler) Sample ¶

func (s *Sampler) Sample(ctx context.Context, now time.Time) (Point, error)

Sample reads and appends exactly one point. Calls are serialized, while Snapshot readers remain unblocked during source I/O.

func (*Sampler) Snapshot ¶

func (s *Sampler) Snapshot(now time.Time, limit int) History

Snapshot returns the newest limit points in chronological order. A stale latest view is degraded without mutating the stored historical point.

type Source ¶

type Source interface {
	Read(context.Context, time.Time) (RawSample, error)
}

Source collects one raw point. Implementations may return partial metrics; an error means the sample as a whole is unavailable and its details must be sent only to protected logs.

type SourceFunc ¶

type SourceFunc func(context.Context, time.Time) (RawSample, error)

SourceFunc adapts a function to Source.

func (SourceFunc) Read ¶

func (f SourceFunc) Read(ctx context.Context, now time.Time) (RawSample, error)

Read implements Source.

type UintMetric ¶

type UintMetric struct {
	Value     uint64
	Available bool
}

UintMetric is an exact integer measurement whose zero can be meaningful.

Source Files ¶

View all Source files

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