Documentation
¶
Overview ¶
Package metrics provides metrics collection and reporting for plexd mesh nodes.
Index ¶
- Constants
- type AgentStats
- type AgentStatsCollector
- type Collector
- type Config
- type IngestClient
- type LatencyCollector
- type LatencyResult
- type LinuxSystemReader
- type LocalReporter
- type Manager
- type MetricsReporter
- type MultiReporter
- type PeerLister
- type Pinger
- type PlatformReporter
- type ReconnectCounter
- type SecretFetcher
- type SystemCollector
- type SystemReader
- type SystemStats
- type TunnelCollector
- type TunnelStats
- type TunnelStatsReader
Constants ¶
const ( GroupSystem = "system" GroupTunnel = "tunnel" GroupLatency = "latency" GroupAgent = "agent" )
Metric group constants identify the subsystem a metric belongs to.
const DefaultBatchSize = 100
DefaultBatchSize is the default maximum number of metric points per report batch.
const DefaultCollectInterval = 15 * time.Second
DefaultCollectInterval is the default interval between metric collection cycles.
const DefaultReportInterval = 60 * time.Second
DefaultReportInterval is the default interval between reporting metrics to the control plane.
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.
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 ¶
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 ¶
RegisterCollector adds a collector to the manager. Must be called before Run; it is not safe for concurrent use.
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 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.