systemstat

README

systemstat

Documentation online

systemstat is a package written in Go generated automatically by gobi.

systemstat allows you to add system statistics to your go program; it currently polls the linux kernel for CPU usage, free/used memory and swap sizes, and uptime for your go process, as well as the system you're running it on, and the system load. It can be used to make a crippled version of top that monitors the current go process and ignores other processes and the number of users with ttys. See the examples directory for go-top.go, which is my attempt at a top clone. Bear in mind that the intention of systemstat is to allow your process to monitor itself and it's environment, not to replace top.

Install (with GOPATH set on your machine)

---

• Step 1: Get the systemstat package

go get bitbucket.org/bertimus9/systemstat

• Step 2 (Optional): Run tests

$ go test -v bitbucket.org/bertimus9/systemstat

• Step 3 (Optional): Run example

$ cd to the first directory in your $GOPATH
$ cd src/bitbucket.org/bertimus9/systemstat
$ go run examples/go-top.go

##Usage

package main

import (
	"bitbucket.org/bertimus9/systemstat"
	"fmt"
)

var sample systemstat.MemSample

// This example shows how easy it is to get memory information
func main() {
	sample = systemstat.GetMemSample()
	fmt.Println("Total available RAM in kb:", sample.MemTotal, "k total")
	fmt.Println("Used RAM in kb:", sample.MemUsed, "k used")
	fmt.Println("Free RAM in kb:", sample.MemFree, "k free")
	fmt.Printf("The output is similar to, but somewhat different than:\n\ttop -n1 | grep Mem:\n")
}

##License

Copyright (c) 2013 Phillip Bond

Licensed under the MIT License

see file LICENSE

Documentation

Index

• type CPUAverage
  • func GetCPUAverage(first CPUSample, second CPUSample) CPUAverage
• type CPUSample
  • func GetCPUSample() (samp CPUSample)
• type LoadAvgSample
  • func GetLoadAvgSample() (samp LoadAvgSample)
• type MemSample
  • func GetMemSample() (samp MemSample)
• type ProcCPUAverage
  • func GetProcCPUAverage(first ProcCPUSample, second ProcCPUSample, procUptime float64) (avg ProcCPUAverage)
• type ProcCPUSample
  • func GetProcCPUSample() (samp ProcCPUSample)
• type SimpleCPUAverage
  • func GetSimpleCPUAverage(first CPUSample, second CPUSample) SimpleCPUAverage
• type UptimeSample
  • func GetUptime() (samp UptimeSample)

Types

type CPUAverage

type CPUAverage struct {
	UserPct    float64
	NicePct    float64
	SystemPct  float64
	IdlePct    float64
	IowaitPct  float64
	IrqPct     float64
	SoftIrqPct float64
	StealPct   float64
	GuestPct   float64
	Time       time.Time
	Seconds    float64 // how many seconds between the two samples
}

CPUAverage is an object that represents the average cpu usage over a time period. It is calculated by taking the difference between two CPUSamples (whose units are clock ticks), dividing by the number of elapsed ticks between the samples, and converting to a percent.

func GetCPUAverage

func GetCPUAverage(first CPUSample, second CPUSample) CPUAverage

GetCPUAverage returns the average cpu usage between two CPUSamples.

type CPUSample

type CPUSample struct {
	User    uint64    // time spent in user mode
	Nice    uint64    // time spent in user mode with low priority (nice)
	System  uint64    // time spent in system mode
	Idle    uint64    // time spent in the idle task
	Iowait  uint64    // time spent waiting for I/O to complete (since Linux 2.5.41)
	Irq     uint64    // time spent servicing  interrupts  (since  2.6.0-test4)
	SoftIrq uint64    // time spent servicing softirqs (since 2.6.0-test4)
	Steal   uint64    // time spent in other OSes when running in a virtualized environment
	Guest   uint64    // time spent running a virtual CPU for guest operating systems under the control of the Linux kernel.
	Name    string    // name of the line in /proc/stat; cpu, cpu1, etc
	Time    time.Time // when the sample was taken
	Total   uint64    // total of all time fields
}

CPUSample is an object that represents the breakdown of time spent by the CPU in various types of tasks. Two CPUSamples are required to find the average usage over time, represented by the CPUAverage object. The CPUSample is taken from the line "cpu" from /proc/stat in the Linux kernel.

Summarized from the proc(5) man page: /proc/stat :

kernel/system  statistics.   Varies  with  architecture.

func GetCPUSample

func GetCPUSample() (samp CPUSample)

GetCPUSample takes a snapshot of kernel statistics from the /proc/stat file.

type LoadAvgSample

type LoadAvgSample struct {
	One     float64
	Five    float64
	Fifteen float64
	Time    time.Time
}

func GetLoadAvgSample

func GetLoadAvgSample() (samp LoadAvgSample)

GetLoadAvgSample takes a snapshot of load info from the /proc/loadavg file.

type MemSample

type MemSample struct {
	Buffers   uint64
	Cached    uint64
	MemTotal  uint64
	MemUsed   uint64
	MemFree   uint64
	SwapTotal uint64
	SwapUsed  uint64
	SwapFree  uint64
	Time      time.Time
}

func GetMemSample

func GetMemSample() (samp MemSample)

GetMemSample takes a snapshot of memory info from the /proc/meminfo file.

type ProcCPUAverage

type ProcCPUAverage struct {
	UserPct            float64   // time spent in user mode
	SystemPct          float64   // time spent in system mode
	TotalPct           float64   // total of all time fields
	PossiblePct        float64   // total of all time fields
	CumulativeTotalPct float64   // total of all time throughout process life
	Time               time.Time // when the sample was taken
	Seconds            float64   // how many seconds between the two samples
}

func GetProcCPUAverage

func GetProcCPUAverage(first ProcCPUSample, second ProcCPUSample, procUptime float64) (avg ProcCPUAverage)

GetProcCPUAverage returns the average cpu usage of this running process

type ProcCPUSample

type ProcCPUSample struct {
	User         float64   // time spent in user mode
	System       float64   // time spent in system mode
	Time         time.Time // when the sample was taken
	Total        float64   // total of all time fields
	ProcMemUsedK int64
}

func GetProcCPUSample

func GetProcCPUSample() (samp ProcCPUSample)

GetProcCPUSample takes a snapshot of kernel statistics from the /proc/stat file.

type SimpleCPUAverage

type SimpleCPUAverage struct {
	BusyPct float64 // percent of time spent by CPU performing all non-idle tasks
	IdlePct float64 // percent of time spent by CPU in the idle task
}

SimpleCPUAverage is an object that represents the average cpu usage over a time period. It is calculated by taking the difference between two CPUSamples (whose units are clock ticks), dividing by the number of elapsed ticks between the samples, and converting to a percent. It is a simplified version of the CPUAverage in that it only accounts for time in the Idle task and all other time (Busy).

func GetSimpleCPUAverage

func GetSimpleCPUAverage(first CPUSample, second CPUSample) SimpleCPUAverage

GetSimpleCPUAverage returns an aggregated average cpu usage between two CPUSamples.

type UptimeSample

type UptimeSample struct {
	Uptime float64
	Time   time.Time
}

func GetUptime

func GetUptime() (samp UptimeSample)

GetUptime takes a snapshot of load info from the /proc/loadavg file.