sysmet

README

sysmet

A no-JavaScript CGI-based lightweight system metrics collector and frontend, effectively a very tiny version of the Grafana + Telegraf + InfluxDB stack.

Usage

sysmet-update

sysmet-update is the metrics collector for the database. It is meant to be called every n duration, usually 15 seconds or a minute. It can only be called every second.

Using systemd-timers or crond is recommended. Below is an example for crond:

sysmet-update -db /opt/sysmet/db

sysmet-http

sysmet-http is the frontend daemon that serves the HTML pages on the given listen address. It should be used like so:

sysmet-http -db /opt/sysmet/db 127.0.0.1:5000

Most use cases should involve another external web server like Caddy to provide HTTPS. In Caddy's case, its Caddyfile could be as simple as this:

https://domain.com

reverse_proxy http://127.0.0.1:5000

sysmet-cgi

sysmet-cgi is the CGI version of sysmet-http. Most people should not use this.

API Documentation

Refer to pkg.go.dev as well as the test suites.

Note to Self

If I ever ponder about using BadgerDB over bbolt: don't, simply don't. Bbolt allows concurrent read opens AND (!!!) waits until the exclusive writer is done WITHOUT needing write permissions.

Documentation

Index

• Variables
• type BucketRange
• type Database
  • func Open(path string, write bool) (*Database, error)
  • func (db *Database) Close() error
  • func (db *Database) GC(age time.Duration) error
  • func (db *Database) Iterator(opts IteratorOpts) (*Iterator, error)
  • func (db *Database) Update(snapshot Snapshot) error
• type Iterator
  • func (i *Iterator) Close() error
  • func (i *Iterator) Prev(snapshot *Snapshot) bool
  • func (i *Iterator) ReadAll() []Snapshot
  • func (i *Iterator) ReadBucketEdges(precision time.Duration) SnapshotBuckets
  • func (i *Iterator) ReadExact(precision time.Duration) SnapshotBuckets
  • func (i *Iterator) ReadRemaining() []Snapshot
  • func (i *Iterator) Remaining() int
  • func (i *Iterator) Rewind()
• type IteratorOpts
• type Snapshot
  • func PrepareMetrics() (Snapshot, error)
• type SnapshotBucket
• type SnapshotBuckets
  • func (buckets *SnapshotBuckets) FillGaps(gapPerc float64)
  • func (buckets SnapshotBuckets) GapThreshold(perc float64) int

Variables

var ErrUninitialized = errors.New("bucket not initialized")

ErrUninitialized is returned when sysmet's bucket is not found in the database. This may happen when the database has never been updated before.

Types

type BucketRange

type BucketRange struct {
	// From is always after To.
	From time.Time     `json:"from"`
	To   time.Time     `json:"to"`
	Prec time.Duration `json:"prec"`
}

BucketRange describes the range of snapshot buckets.

type Database

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

Database describes a wrapped database instance.

func Open

func Open(path string, write bool) (*Database, error)

Open opens a database. Databases must be closed once they're done.

func (*Database) Close

func (db *Database) Close() error

Close closes the database. Calling Close twice does nothing.

func (*Database) GC

func (db *Database) GC(age time.Duration) error

GC cleans up the database. Since this is a fairly expensive operation, it should only be called rarely.

func (*Database) Iterator

func (db *Database) Iterator(opts IteratorOpts) (*Iterator, error)

Iterator returns a new database iterator with second precision. The iterator must be closed after it's done.

func (*Database) Update

func (db *Database) Update(snapshot Snapshot) error

Update updates a set of prepared metrics into the database.

type Iterator

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

Iterator is a backwards metric iterator that allows iterating over points.

func (*Iterator) Close

func (i *Iterator) Close() error

Close closes the reader.

func (*Iterator) Prev

func (i *Iterator) Prev(snapshot *Snapshot) bool

Prev reads the previous item into the given snapshot pointer or the last item if the Reader has never been used before. If snapshot is nil, then the iterator is still updated, but no unmarshaling is done.

False is returned if nothing is read and the reader is closed, otherwise true is.

func (*Iterator) ReadAll

func (i *Iterator) ReadAll() []Snapshot

ReadAll is similar to ReadRemaining, except the cursor is rewound to the requested position "from" and read again.

func (*Iterator) ReadBucketEdges

func (i *Iterator) ReadBucketEdges(precision time.Duration) SnapshotBuckets

ReadBucketEdges behaves similarly to ReadExact, except each bucket will only have the latest point. This is great when data has to be read over a wide range of time.

func (*Iterator) ReadExact

func (i *Iterator) ReadExact(precision time.Duration) SnapshotBuckets

ReadExact reads exactly the given time range, meaning the list of buckets will describe exactly the requested range and precision. The cursor will automatically be rewound back to the "from" position. The function returns a zero-value if from or to was 0.

func (*Iterator) ReadRemaining

func (i *Iterator) ReadRemaining() []Snapshot

ReadRemaining reads all of the reader from the current position to end.

func (*Iterator) Remaining

func (i *Iterator) Remaining() int

Remaining returns the number of remaining keys to read until either the database has nothing left or the requested range has been reached. The cursor position stays the same by the time this function returns.

func (*Iterator) Rewind

func (i *Iterator) Rewind()

Rewind resets the cursor back to the initial position.

type IteratorOpts

type IteratorOpts struct {
	// From is the time to start reading the metrics backwards. The default
	// zero-value means to read from the latest point.
	From time.Time
	// To is the time to stop reading the metrics backwards. By default, the
	// zero-value is used, which would read all metrics. The To time must
	// ALWAYS be before From.
	To time.Time
}

IteratorOpts is the options for reading. It describes the range of data to read.

type Snapshot

type Snapshot struct {
	CPUs      []cpu.TimesStat
	Memory    mem.VirtualMemoryStat
	Swap      mem.SwapMemoryStat
	Network   []net.IOCountersStat
	Disks     []disk.UsageStat
	Temps     []host.TemperatureStat
	LoadAvgs  load.AvgStat
	HostStats load.MiscStat

	Time uint32 `json:"-"`
}

Snapshot describes a single snapshot of data.

func PrepareMetrics

func PrepareMetrics() (Snapshot, error)

PrepareMetrics prepares a set of metrics to write at once.

type SnapshotBucket

type SnapshotBucket struct {
	Snapshots []Snapshot `json:"snapshots"`
}

SnapshotBucket contains a bucket of snapshot timeframes. It is used by ReadExact to allow the caller to manually calculate the averages.

type SnapshotBuckets

type SnapshotBuckets struct {
	Range     BucketRange      `json:"range"`
	Snapshots []Snapshot       `json:"-"`
	Buckets   []SnapshotBucket `json:"buckets"`
}

SnapshotBuckets contains all snapshots as well as buckets of those snapshots over the given time.

func (*SnapshotBuckets) FillGaps

func (buckets *SnapshotBuckets) FillGaps(gapPerc float64)

FillGaps fills the buckets with the given multiplier for determine the threshold. A good gapMult value is 0.10.

func (SnapshotBuckets) GapThreshold

func (buckets SnapshotBuckets) GapThreshold(perc float64) int

GapThreshold returns the threshold that determine a gap after n empty buckets. The given perc variable determines the percentage from 0 to 1 that determines after how many empty buckets should be treated as a gap.