metrics

package
v0.3.0 Latest Latest
Warning

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

Go to latest
Published: Jul 28, 2026 License: Apache-2.0 Imports: 21 Imported by: 0

Documentation

Overview

Package metrics provides metrics collection and reporting for plexd mesh nodes.

Index

Constants

View Source
const (
	GroupSystem  = "system"
	GroupTunnel  = "tunnel"
	GroupLatency = "latency"
	GroupAgent   = "agent"
)

Metric group constants identify the subsystem a metric belongs to.

View Source
const DefaultBatchSize = 100

DefaultBatchSize is the default maximum number of metric points per report batch.

View Source
const DefaultCollectInterval = 15 * time.Second

DefaultCollectInterval is the default interval between metric collection cycles.

View Source
const DefaultReportInterval = 60 * time.Second

DefaultReportInterval is the default interval between reporting metrics to the control plane.

View Source
const DefaultStaleThreshold = 5 * time.Minute

DefaultStaleThreshold is the default duration after which a handshake is considered stale.

Variables

This section is empty.

Functions

This section is empty.

Types

type AgentStats

type AgentStats struct {
	GoroutineCount int     `json:"goroutine_count"`
	HeapAllocBytes uint64  `json:"heap_alloc_bytes"`
	HeapSysBytes   uint64  `json:"heap_sys_bytes"`
	GCPauseTotalNs uint64  `json:"gc_pause_total_ns"`
	GCNumGC        uint32  `json:"gc_num_gc"`
	UptimeSeconds  float64 `json:"uptime_seconds"`
	ReconnectCount int     `json:"reconnect_count"`
}

AgentStats holds agent runtime metrics.

type AgentStatsCollector

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

AgentStatsCollector implements Collector for agent runtime metrics.

func NewAgentStatsCollector

func NewAgentStatsCollector(startTime time.Time, reconnects ReconnectCounter, logger *slog.Logger) *AgentStatsCollector

NewAgentStatsCollector creates a new AgentStatsCollector. The reconnects parameter may be nil if reconnect counting is not available.

func (*AgentStatsCollector) Collect

func (c *AgentStatsCollector) Collect(ctx context.Context) ([]api.MetricPoint, error)

Collect reads Go runtime stats and returns a single MetricPoint.

type Collector

type Collector interface {
	Collect(ctx context.Context) ([]api.MetricPoint, error)
}

Collector collects metrics from a specific subsystem.

type Config

type Config struct {
	// Enabled controls whether metrics collection is active.
	// Default: true (set by ApplyDefaults).
	Enabled bool `yaml:"enabled"`

	// CollectInterval is the interval between collection cycles.
	// Must be at least 5s.
	CollectInterval time.Duration `yaml:"collect_interval"`

	// ReportInterval is the interval between reporting to the control plane.
	// Must be at least 10s and >= CollectInterval.
	ReportInterval time.Duration `yaml:"report_interval"`

	// BatchSize is the maximum number of metric points per report batch.
	// Must be > 0. Default: 100.
	BatchSize int `yaml:"batch_size"`

	// LocalEndpoint configures an optional local data-plane endpoint.
	LocalEndpoint api.LocalEndpointConfig `yaml:"local_endpoint"`
}

Config holds the configuration for metrics collection and reporting.

func (*Config) ApplyDefaults

func (c *Config) ApplyDefaults()

ApplyDefaults sets default values for zero-valued fields. On a zero-valued Config, Enabled defaults to true. To disable metrics, set Enabled=false before or after calling ApplyDefaults.

func (*Config) Validate

func (c *Config) Validate() error

Validate checks that configuration values are within acceptable ranges.

type IngestClient added in v0.2.0

type IngestClient interface {
	ReportMetrics(ctx context.Context, nodeID string, samples []api.MetricSample) (*api.IngestReceipt, error)
}

IngestClient is the control-plane seam a PlatformReporter reports flattened metric samples through. It is defined here (rather than reused from the api package) so the metrics package owns the exact shape it depends on.

type LatencyCollector

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

LatencyCollector implements Collector for peer latency metrics.

func NewLatencyCollector

func NewLatencyCollector(pinger Pinger, lister PeerLister, logger *slog.Logger) *LatencyCollector

NewLatencyCollector creates a new LatencyCollector.

func (*LatencyCollector) Collect

func (c *LatencyCollector) Collect(ctx context.Context) ([]api.MetricPoint, error)

Collect measures latency to all known peers and returns the results as MetricPoints.

type LatencyResult

type LatencyResult struct {
	PeerID  string `json:"peer_id"`
	RTTNano int64  `json:"rtt_nano"`
}

LatencyResult holds the latency measurement for a single peer.

type LinuxSystemReader

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

LinuxSystemReader reads system metrics from /proc and syscall on Linux.

func NewLinuxSystemReader

func NewLinuxSystemReader(mountPoint, netIface string) *LinuxSystemReader

NewLinuxSystemReader creates a new LinuxSystemReader. mountPoint is the filesystem path for disk stats (e.g., "/"). netIface is the network interface for rx/tx bytes (e.g., "eth0"); empty means sum all interfaces.

func (*LinuxSystemReader) ReadStats

func (r *LinuxSystemReader) ReadStats(ctx context.Context) (*SystemStats, error)

ReadStats reads system metrics from /proc and syscall.

type LocalReporter

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

LocalReporter implements MetricsReporter by posting metric batches to a locally-configured HTTPS endpoint with bearer-token authentication.

func NewLocalReporter

func NewLocalReporter(cfg api.LocalEndpointConfig, fetcher SecretFetcher, nsk []byte, nodeID string, logger *slog.Logger) *LocalReporter

NewLocalReporter creates a LocalReporter from the given configuration.

func (*LocalReporter) ReportMetrics

func (r *LocalReporter) ReportMetrics(ctx context.Context, nodeID string, batch api.MetricBatch) error

ReportMetrics posts the metric batch as JSON to the configured local endpoint, authenticating with a bearer token resolved from the secret store.

type Manager

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

Manager orchestrates metric collection and reporting.

func NewManager

func NewManager(cfg Config, collectors []Collector, reporter MetricsReporter, nodeID string, logger *slog.Logger) *Manager

NewManager creates a new Manager. Config defaults are applied automatically.

func (*Manager) RegisterCollector

func (m *Manager) RegisterCollector(c Collector)

RegisterCollector adds a collector to the manager. Must be called before Run; it is not safe for concurrent use.

func (*Manager) Run

func (m *Manager) Run(ctx context.Context) error

Run starts the collect and report loops. It blocks until ctx is cancelled.

type MetricsReporter

type MetricsReporter interface {
	ReportMetrics(ctx context.Context, nodeID string, batch api.MetricBatch) error
}

MetricsReporter abstracts the control plane metrics reporting API.

type MultiReporter

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

MultiReporter fans out metric reporting to both a platform and a local MetricsReporter concurrently. The platform error is surfaced to the caller; a local error is logged as a warning but does not fail the call.

func NewMultiReporter

func NewMultiReporter(platform, local MetricsReporter, logger *slog.Logger) *MultiReporter

NewMultiReporter creates a MultiReporter that reports to both platform and local reporters.

func (*MultiReporter) ReportMetrics

func (m *MultiReporter) ReportMetrics(ctx context.Context, nodeID string, batch api.MetricBatch) error

ReportMetrics sends the batch to both reporters concurrently. The platform error is returned; a local error is logged as a warning.

type PeerLister

type PeerLister interface {
	PeerIDs() []string
}

PeerLister provides the list of current peer IDs to measure.

type Pinger

type Pinger interface {
	Ping(ctx context.Context, peerID string) (rttNano int64, err error)
}

Pinger abstracts the latency measurement mechanism.

type PlatformReporter added in v0.2.0

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

PlatformReporter implements MetricsReporter by flattening each metric point into wire samples and posting them to the platform ingest endpoint through an IngestClient.

func NewPlatformReporter added in v0.2.0

func NewPlatformReporter(client IngestClient, logger *slog.Logger) *PlatformReporter

NewPlatformReporter creates a PlatformReporter that reports through client.

func (*PlatformReporter) ReportMetrics added in v0.2.0

func (r *PlatformReporter) ReportMetrics(ctx context.Context, nodeID string, batch api.MetricBatch) error

ReportMetrics flattens the batch into wire samples and posts them through the ingest client. Points that fail conversion are logged and skipped. When no samples survive, it returns nil without calling the client (the ingest contract rejects an empty array). Every sample the reporter discards is counted and periodically summarized, because dropping is invisible to the manager's own status.

type ReconnectCounter

type ReconnectCounter interface {
	ReconnectCount() int
}

ReconnectCounter provides the current reconnect count.

type SecretFetcher

type SecretFetcher interface {
	FetchSecret(ctx context.Context, nodeID, name string, version int) (*api.SecretEnvelope, error)
}

SecretFetcher abstracts the control plane client for secret retrieval.

type SystemCollector

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

SystemCollector implements Collector for system resource metrics.

func NewSystemCollector

func NewSystemCollector(reader SystemReader, logger *slog.Logger) *SystemCollector

NewSystemCollector creates a new SystemCollector.

func (*SystemCollector) Collect

func (c *SystemCollector) Collect(ctx context.Context) ([]api.MetricPoint, error)

Collect reads system stats and returns a single MetricPoint.

type SystemReader

type SystemReader interface {
	ReadStats(ctx context.Context) (*SystemStats, error)
}

SystemReader abstracts OS-level system metrics retrieval.

type SystemStats

type SystemStats struct {
	CPUUsagePercent  float64 `json:"cpu_usage_percent"`
	MemoryUsedBytes  uint64  `json:"memory_used_bytes"`
	MemoryTotalBytes uint64  `json:"memory_total_bytes"`
	DiskUsedBytes    uint64  `json:"disk_used_bytes"`
	DiskTotalBytes   uint64  `json:"disk_total_bytes"`
	NetworkRxBytes   uint64  `json:"network_rx_bytes"`
	NetworkTxBytes   uint64  `json:"network_tx_bytes"`
	LoadAvg1         float64 `json:"load_avg_1"`
	LoadAvg5         float64 `json:"load_avg_5"`
	LoadAvg15        float64 `json:"load_avg_15"`
}

SystemStats holds the raw system resource readings.

type TunnelCollector

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

TunnelCollector implements Collector for per-peer tunnel metrics.

func NewTunnelCollector

func NewTunnelCollector(reader TunnelStatsReader, logger *slog.Logger) *TunnelCollector

NewTunnelCollector creates a new TunnelCollector. StaleThreshold defaults to DefaultStaleThreshold (5m).

func NewTunnelCollectorWithThreshold

func NewTunnelCollectorWithThreshold(reader TunnelStatsReader, logger *slog.Logger, staleThreshold time.Duration) *TunnelCollector

NewTunnelCollectorWithThreshold creates a TunnelCollector with a custom stale threshold.

func (*TunnelCollector) Collect

func (c *TunnelCollector) Collect(ctx context.Context) ([]api.MetricPoint, error)

Collect reads tunnel stats and returns a MetricPoint per peer. Handshakes older than StaleThreshold are marked as stale.

type TunnelStats

type TunnelStats struct {
	PeerID             string    `json:"peer_id"`
	LastHandshakeTime  time.Time `json:"last_handshake_time"`
	RxBytes            uint64    `json:"rx_bytes"`
	TxBytes            uint64    `json:"tx_bytes"`
	HandshakeSucceeded bool      `json:"handshake_succeeded"`
	HandshakeStale     bool      `json:"handshake_stale"`
	PacketLossPercent  float64   `json:"packet_loss_percent"`
}

TunnelStats holds tunnel health data for a single peer.

type TunnelStatsReader

type TunnelStatsReader interface {
	ReadTunnelStats(ctx context.Context) ([]TunnelStats, error)
}

TunnelStatsReader abstracts WireGuard tunnel stats retrieval.

Jump to

Keyboard shortcuts

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