metrics

README

sysc-metrics

sysc-metrics is a small Go library for read-only Linux system telemetry. It supplies the built-in monitoring widgets in sysc-shell without importing a CLI, TUI, HTTP server, or unrelated application framework.

The M0 contract and M1 core collectors are implemented.

Usage

package main

import (
	"fmt"
	"github.com/Nomadcxx/sysc-metrics"
)

func main() {
	snapshot, err := metrics.NewCPUSampler().Sample()
	if err != nil {
		panic(err)
	}
	if snapshot.Usage.Valid {
		fmt.Println(snapshot.Usage.Fraction)
	}
}

M1 is Linux-only and uses only the Go standard library. Samplers belong to one sequential polling owner; they do not start goroutines. First and discontinuous rate samples have Valid == false, while valid zero values remain valid. A snapshot may contain partial data and Issue values for failed individual sources or entities.

Polling cadence, caching, presentation, units shown to users, alerts, and filtering remain consumer responsibilities.

Scope

The first releases will collect:

• aggregate and per-core CPU usage, load, and frequency;
• memory and swap;
• mounted-filesystem capacity and block-device I/O rates;
• per-interface network counters and rates;
• thermal sensors and available GPU metrics;
• battery and UPS state, energy, rate, and estimated time;
• uptime and basic totals;
• process CPU and memory only when a consumer requests it.

UPower supplies the preferred battery aggregate. /sys/class/power_supply provides the fallback. Collectors use Linux interfaces such as /proc, /sys, statfs, and D-Bus directly.

The library will not provide power controls, recursive directory sizes, filesystem indexing, SMART, quotas, vendor administration, a daemon, or cross-platform abstractions.

Development gates

1. Define snapshot and sampling semantics, including first-sample behavior and counter reset handling.
2. Implement CPU, memory, filesystem, block-device, and network collectors with fixture tests.
3. Add thermal and battery collection, including UPower loss and sysfs fallback tests.
4. Add GPU and process collectors only for a confirmed shell consumer.
5. Qualify suspend/resume, device removal, permission errors, and real hardware before v0.1.0.

See the design and roadmap. Package directories will be added with their first tested behavior; the repository will not track empty scaffolding.

Licence

sysc-metrics uses the BSD 3-Clause License.

Documentation

Overview

Package metrics provides read-only Linux system telemetry snapshots.

Index

• type BatterySnapshot
  • func ReadBattery() (BatterySnapshot, error)
• type BatteryState
• type BlockDevice
• type BlockRates
• type BlockSampler
  • func NewBlockSampler() *BlockSampler
  • func (s *BlockSampler) Sample() (BlockSnapshot, error)
• type BlockSnapshot
• type CPUCore
• type CPUSampler
  • func NewCPUSampler() *CPUSampler
  • func (s *CPUSampler) Sample() (CPUSnapshot, error)
• type CPUSnapshot
• type CPUUsage
• type Capacity
• type Filesystem
• type FilesystemSnapshot
  • func ReadFilesystems() (FilesystemSnapshot, error)
• type Issue
  • func (i Issue) Error() string
  • func (i Issue) Unwrap() error
• type MemorySnapshot
  • func ReadMemory() (MemorySnapshot, error)
• type NetworkInterface
• type NetworkRates
• type NetworkSampler
  • func NewNetworkSampler() *NetworkSampler
  • func (s *NetworkSampler) Sample() (NetworkSnapshot, error)
• type NetworkSnapshot
• type UptimeSnapshot
  • func ReadUptime() (UptimeSnapshot, error)

Types

type BatterySnapshot

type BatterySnapshot struct {
	CollectedAt   time.Time
	Present       bool
	Charge        float64 // 0..1
	ChargeValid   bool
	State         BatteryState
	EnergyJoules  float64
	RateWatts     float64
	RateValid     bool
	TimeRemaining time.Duration
	TimeValid     bool
	Issues        []Issue
}

BatterySnapshot is the aggregate battery observation. Present is false on a machine with no battery; that is not an error.

func ReadBattery

func ReadBattery() (BatterySnapshot, error)

ReadBattery collects the current aggregate battery. It prefers sysfs power-supply devices of type Battery or UPS. A machine with none reports Present false.

type BatteryState

type BatteryState uint8

BatteryState is the charging state of the aggregate battery.

const (
	BatteryUnknown BatteryState = iota
	BatteryCharging
	BatteryDischarging
	BatteryFull
)

type BlockDevice

type BlockDevice struct {
	Name            string
	Major           uint32
	Minor           uint32
	ReadBytes       uint64
	WriteBytes      uint64
	ReadOperations  uint64
	WriteOperations uint64
	Busy            time.Duration
	Rates           BlockRates
}

BlockDevice contains cumulative counters and derived rates for one block device.

type BlockRates

type BlockRates struct {
	ReadBytesPerSecond       float64
	WriteBytesPerSecond      float64
	ReadOperationsPerSecond  float64
	WriteOperationsPerSecond float64
	BusyFraction             float64
	Valid                    bool
}

BlockRates contains rates derived from two block-device observations. Valid distinguishes observed zero rates from unavailable derived values.

type BlockSampler

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

BlockSampler retains previous block counters for sequential rate sampling.

func NewBlockSampler

func NewBlockSampler() *BlockSampler

NewBlockSampler returns a block sampler owned by one sequential polling caller.

func (*BlockSampler) Sample

func (s *BlockSampler) Sample() (BlockSnapshot, error)

Sample returns one block-device snapshot. The sampler is not safe for concurrent use.

type BlockSnapshot

type BlockSnapshot struct {
	CollectedAt time.Time
	Devices     []BlockDevice
	Issues      []Issue
}

BlockSnapshot contains block-device data collected at one time. Devices and Issues are caller-owned snapshot slices.

type CPUCore

type CPUCore struct {
	ID             int
	Usage          CPUUsage
	FrequencyHz    uint64
	FrequencyValid bool
}

CPUCore contains one core's usage and best-effort frequency.

type CPUSampler

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

CPUSampler retains the previous CPU counters for sequential rate sampling.

func NewCPUSampler

func NewCPUSampler() *CPUSampler

NewCPUSampler returns a CPU sampler owned by one sequential polling caller.

func (*CPUSampler) Sample

func (s *CPUSampler) Sample() (CPUSnapshot, error)

Sample returns one CPU snapshot. The sampler is not safe for concurrent use.

type CPUSnapshot

type CPUSnapshot struct {
	CollectedAt time.Time
	Usage       CPUUsage
	Cores       []CPUCore
	Load1       float64
	Load5       float64
	Load15      float64
	LoadValid   bool
	Issues      []Issue
}

CPUSnapshot contains aggregate and per-core CPU data collected at one time. Cores and Issues are caller-owned snapshot slices.

type CPUUsage

type CPUUsage struct {
	Fraction float64
	Valid    bool
}

CPUUsage contains a utilization fraction. Valid distinguishes an observed zero from no sample.

type Capacity

type Capacity struct {
	TotalBytes     uint64
	UsedBytes      uint64
	AvailableBytes uint64
}

Capacity contains byte totals. Byte fields are uint64 values.

type Filesystem

type Filesystem struct {
	MountID    uint64
	MountPoint string
	Source     string
	Type       string
	ReadOnly   bool
	Capacity   Capacity
}

Filesystem contains one mounted filesystem and its byte capacity.

type FilesystemSnapshot

type FilesystemSnapshot struct {
	CollectedAt time.Time
	Filesystems []Filesystem
	Issues      []Issue
}

FilesystemSnapshot contains mounted filesystem data collected at one time. Filesystems and Issues are caller-owned snapshot slices.

func ReadFilesystems

func ReadFilesystems() (FilesystemSnapshot, error)

ReadFilesystems returns one mounted-filesystem snapshot from Linux.

type Issue

type Issue struct {
	Source string
	Err    error
}

Issue describes a recoverable source or entity failure in a partial snapshot.

func (Issue) Error

func (i Issue) Error() string

Error returns the source and underlying error.

func (Issue) Unwrap

func (i Issue) Unwrap() error

Unwrap returns the underlying source error.

type MemorySnapshot

type MemorySnapshot struct {
	CollectedAt time.Time
	Memory      Capacity
	Swap        Capacity
}

MemorySnapshot contains memory and swap byte capacities collected at one time.

func ReadMemory

func ReadMemory() (MemorySnapshot, error)

ReadMemory returns one memory and swap snapshot from Linux.

type NetworkInterface

type NetworkInterface struct {
	Name            string
	Index           uint32
	ReceiveBytes    uint64
	ReceivePackets  uint64
	ReceiveErrors   uint64
	ReceiveDropped  uint64
	TransmitBytes   uint64
	TransmitPackets uint64
	TransmitErrors  uint64
	TransmitDropped uint64
	Rates           NetworkRates
}

NetworkInterface contains cumulative counters and derived rates for one interface.

type NetworkRates

type NetworkRates struct {
	ReceiveBytesPerSecond    float64
	TransmitBytesPerSecond   float64
	ReceivePacketsPerSecond  float64
	TransmitPacketsPerSecond float64
	Valid                    bool
}

NetworkRates contains rates derived from two network observations. Valid distinguishes observed zero rates from unavailable derived values.

type NetworkSampler

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

NetworkSampler retains previous interface counters for sequential rate sampling.

func NewNetworkSampler

func NewNetworkSampler() *NetworkSampler

NewNetworkSampler returns a network sampler owned by one sequential polling caller.

func (*NetworkSampler) Sample

func (s *NetworkSampler) Sample() (NetworkSnapshot, error)

Sample returns one network-interface snapshot. The sampler is not safe for concurrent use.

type NetworkSnapshot

type NetworkSnapshot struct {
	CollectedAt time.Time
	Interfaces  []NetworkInterface
	Issues      []Issue
}

NetworkSnapshot contains network-interface data collected at one time. Interfaces and Issues are caller-owned snapshot slices.

type UptimeSnapshot

type UptimeSnapshot struct {
	CollectedAt time.Time
	Uptime      time.Duration
}

UptimeSnapshot contains uptime as a duration collected at one time.

func ReadUptime

func ReadUptime() (UptimeSnapshot, error)

ReadUptime returns one uptime snapshot from Linux.