gopsutil: psutil for golang

This is a port of psutil (https://github.com/giampaolo/psutil). The challenge is porting all psutil functions on some architectures.

v3 migration

from v3.20.10, gopsutil becomes v3 which breaks backawards compatiblity. See [v3Changes.md](_tools/v3migration/v3Changes.md) more detail changes.

Tag semantics

gopsutil tag policy is almost same as Semantic Versioning, but automatically increase like Ubuntu versioning.

for example, v2.17.04 means

• v2: major version
• 17: release year, 2017
• 04: release month

gopsutil aims to keep backwards-compatiblity until major version change.

Taged at every end of month, but there are only a few commits, it can be skipped.

Available Architectures

• FreeBSD i386/amd64/arm
• Linux i386/amd64/arm(raspberry pi)
• Windows/amd64
• Darwin i386/amd64
• OpenBSD amd64 (Thank you @mpfz0r!)
• Solaris amd64 (developed and tested on SmartOS/Illumos, Thank you @jen20!)

These are partial support:

• CPU on DragonFly BSD (#893, Thank you @gballet!)
• host on Linux RISC-V (#896, Thank you @tklauser!)

All works are implemented without cgo by porting c struct to golang struct.

Usage

package main

import (
    "fmt"

    "github.com/shirou/gopsutil/v3/mem"
    // "github.com/shirou/gopsutil/mem"  // to use v2
)

func main() {
    v, _ := mem.VirtualMemory()

    // almost every return value is a struct
    fmt.Printf("Total: %v, Free:%v, UsedPercent:%f%%\n", v.Total, v.Free, v.UsedPercent)

    // convert to JSON. String() is also implemented
    fmt.Println(v)
}

The output is below.

Total: 3179569152, Free:284233728, UsedPercent:84.508194%
{"total":3179569152,"available":492572672,"used":2895335424,"usedPercent":84.50819439828305, (snip...)}

You can set an alternative location to /proc by setting the HOST_PROC environment variable.

You can set an alternative location to /sys by setting the HOST_SYS environment variable.

You can set an alternative location to /etc by setting the HOST_ETC environment variable.

You can set an alternative location to /var by setting the HOST_VAR environment variable.

You can set an alternative location to /run by setting the HOST_RUN environment variable.

You can set an alternative location to /dev by setting the HOST_DEV environment variable.

Documentation

see http://godoc.org/github.com/shirou/gopsutil

Requirements

• go1.11 or above is required.

More Info

Several methods have been added which are not present in psutil, but will provide useful information.

• host/HostInfo() (linux)
  • Hostname
  • Uptime
  • Procs
  • OS (ex: "linux")
  • Platform (ex: "ubuntu", "arch")
  • PlatformFamily (ex: "debian")
  • PlatformVersion (ex: "Ubuntu 13.10")
  • VirtualizationSystem (ex: "LXC")
  • VirtualizationRole (ex: "guest"/"host")
• IOCounters
  • Label (linux only) The registered device mapper name
• cpu/CPUInfo() (linux, freebsd)
  • CPU (ex: 0, 1, ...)
  • VendorID (ex: "GenuineIntel")
  • Family
  • Model
  • Stepping
  • PhysicalID
  • CoreID
  • Cores (ex: 2)
  • ModelName (ex: "Intel(R) Core(TM) i7-2640M CPU @ 2.80GHz")
  • Mhz
  • CacheSize
  • Flags (ex: "fpu vme de pse tsc msr pae mce cx8 ...")
  • Microcode
• load/LoadAvg() (linux, freebsd)
  • Load1
  • Load5
  • Load15
• docker/GetDockerIDList() (linux only)
  • container id list ([]string)
• docker/CgroupCPU() (linux only)
  • user
  • system
• docker/CgroupMem() (linux only)
  • various status
• net_protocols (linux only)
  • system wide stats on network protocols (i.e IP, TCP, UDP, etc.)
  • sourced from /proc/net/snmp
• iptables nf_conntrack (linux only)
  • system wide stats on netfilter conntrack module
  • sourced from /proc/sys/net/netfilter/nf_conntrack_count

Some codes are ported from Ohai. many thanks.

Current Status

• x: work
• b: almost works, but something is broken

name cpu_times cpu_count cpu_percent cpu_times_percent	Linux x x x x	FreeBSD x x x x	OpenBSD x x x x	MacOSX x x x x	Windows x x x x	Solaris
virtual_memory swap_memory disk_partitions disk_io_counters disk_usage net_io_counters boot_time users pids pid_exists net_connections net_protocols net_if_addrs net_if_stats netfilter_conntrack =================== Process class name pid ppid name cmdline create_time status cwd exe uids gids terminal io_counters nice num_fds num_ctx_switches num_threads cpu_times memory_info memory_info_ex memory_maps open_files send_signal suspend resume terminate kill username ionice rlimit num_handlers threads cpu_percent cpu_affinity memory_percent parent children connections is_running page_faults Lin Original Metrics	x x x x x x x x x x x x x ux Free x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x	x x x x x x x x x x BSD Open x x x x x x x x x x x x x x x x x x x x x x	x x x x x x x x x x x BSD MacO x x x x x x x x x x x x x x x x x x x x x x	x x x x b x x x x x SX Wind x x x x x x x x x x x x x x x	x x x x x x x x ows	b
================== =	==== ==	===== ==	===== ==	==== ==	===== ==	=====
item L HostInfo	inux Fr	eeBSD Op	enBSD Ma	cOSX Wi	ndows So	laris
hostname uptime proces	x x x	x x x	x x x	x x	x	x x x
os platform platformfamily virtualization CPU	x x x x	x x x	x x x	x x x	x	x x x
VendorID	x	x	x	x	x	x
Family	x	x	x	x	x	x
Model	x	x	x	x	x	x
Stepping PhysicalID CoreID Cores	x x x x	x	x	x	x x	x x x x
ModelName Microcode LoadAvg Load1 Load5 Load15 GetDockerID container id CgroupsCPU user system CgroupsMem various	x x x x x x x x x	x x x x no no no no	x x x x no no no no	x x x x no no no no	x no no no no	x x

• future work
  • process_iter
  • wait_procs
  • Process class
    • as_dict
    • wait

License

New BSD License (same as psutil)

Related Works

I have been influenced by the following great works:

• psutil: https://github.com/giampaolo/psutil
• dstat: https://github.com/dagwieers/dstat
• gosigar: https://github.com/cloudfoundry/gosigar/
• goprocinfo: https://github.com/c9s/goprocinfo
• go-ps: https://github.com/mitchellh/go-ps
• ohai: https://github.com/opscode/ohai/
• bosun: https://github.com/bosun-monitor/bosun/tree/master/cmd/scollector/collectors
• mackerel: https://github.com/mackerelio/mackerel-agent/tree/master/metrics

How to Contribute

1. Fork it
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create new Pull Request

My English is terrible, so documentation or correcting comments are also welcome.