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

Expand ▾ Collapse ▴

Documentation

Overview

Example (Simple)

    This example shows how easy it is to get memory information

    Output:
    
    

    Index

    Examples

    Constants

    This section is empty.

    Variables

    This section is empty.

    Functions

    This section is empty.

    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.

                          Directories

                          Path Synopsis