298 lines
13 KiB
Markdown
298 lines
13 KiB
Markdown
# gopsutil: psutil for golang
|
|
|
|
[](https://github.com/shirou/gopsutil/actions/workflows/test.yml) [](https://coveralls.io/github/shirou/gopsutil?branch=master) [](https://pkg.go.dev/github.com/shirou/gopsutil/v3) [](https://godocs.io/github.com/shirou/gopsutil/v3) [](https://calver.org/)
|
|
|
|
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 backwards compatibility.
|
|
See [v3Changes.md](_tools/v3migration/v3Changes.md) for more detailed changes.
|
|
|
|
## Tag semantics
|
|
|
|
gopsutil tag policy is almost same as Semantic Versioning, but
|
|
automatically increases like [Ubuntu versioning](https://calver.org/).
|
|
|
|
For example, v2.17.04 means
|
|
|
|
- v2: major version
|
|
- 17: release year, 2017
|
|
- 04: release month
|
|
|
|
gopsutil aims to keep backwards compatibility until major version change.
|
|
|
|
Tagged at every end of month, but if there are only a few commits, it
|
|
can be skipped.
|
|
|
|
## Available Architectures
|
|
|
|
- FreeBSD i386/amd64/arm
|
|
- Linux i386/amd64/arm(raspberry pi)
|
|
- Windows i386/amd64/arm/arm64
|
|
- Darwin amd64/arm64
|
|
- OpenBSD amd64 (Thank you @mpfz0r!)
|
|
- Solaris amd64 (developed and tested on SmartOS/Illumos, Thank you
|
|
@jen20!)
|
|
|
|
These have 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 structs to golang
|
|
structs.
|
|
|
|
## Usage
|
|
|
|
```go
|
|
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.
|
|
|
|
You can set an alternative location to `/proc/N/mountinfo` by setting the
|
|
`HOST_PROC_MOUNTINFO` environment variable.
|
|
|
|
## Documentation
|
|
|
|
See https://pkg.go.dev/github.com/shirou/gopsutil/v3 or https://godocs.io/github.com/shirou/gopsutil/v3
|
|
|
|
## Requirements
|
|
|
|
- go1.16 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](https://www.kernel.org/doc/Documentation/ABI/testing/sysfs-block-dm)
|
|
- 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/Avg() (linux, freebsd, solaris)
|
|
- 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 code is ported from Ohai. many thanks.
|
|
|
|
## Current Status
|
|
|
|
- x: works
|
|
- b: almost works, but something is broken
|
|
|
|
|name |Linux |FreeBSD |OpenBSD |macOS |Windows |Solaris |Plan 9 |
|
|
|----------------------|-------|---------|---------|--------|---------|---------|---------|
|
|
|cpu\_times |x |x |x |x |x | |b |
|
|
|cpu\_count |x |x |x |x |x | |x |
|
|
|cpu\_percent |x |x |x |x |x | | |
|
|
|cpu\_times\_percent |x |x |x |x |x | | |
|
|
|virtual\_memory |x |x |x |x |x | b |x |
|
|
|swap\_memory |x |x |x |x | | |x |
|
|
|disk\_partitions |x |x |x |x |x | | |
|
|
|disk\_io\_counters |x |x |x | | | | |
|
|
|disk\_usage |x |x |x |x |x | | |
|
|
|net\_io\_counters |x |x |x |b |x | | |
|
|
|boot\_time |x |x |x |x |x | | |
|
|
|users |x |x |x |x |x | | |
|
|
|pids |x |x |x |x |x | | |
|
|
|pid\_exists |x |x |x |x |x | | |
|
|
|net\_connections |x | |x |x | | | |
|
|
|net\_protocols |x | | | | | | |
|
|
|net\_if\_addrs | | | | | | | |
|
|
|net\_if\_stats | | | | | | | |
|
|
|netfilter\_conntrack |x | | | | | | |
|
|
|
|
|
|
### Process class
|
|
|
|
|name |Linux |FreeBSD |OpenBSD |macOS |Windows |
|
|
|--------------------|-------|---------|---------|-------|---------|
|
|
|pid |x |x |x |x |x |
|
|
|ppid |x |x |x |x |x |
|
|
|name |x |x |x |x |x |
|
|
|cmdline |x |x | |x |x |
|
|
|create\_time |x | | |x |x |
|
|
|status |x |x |x |x | |
|
|
|cwd |x | | |x | |
|
|
|exe |x |x |x | |x |
|
|
|uids |x |x |x |x | |
|
|
|gids |x |x |x |x | |
|
|
|terminal |x |x |x | | |
|
|
|io\_counters |x |x |x | |x |
|
|
|nice |x |x |x |x |x |
|
|
|num\_fds |x | | | | |
|
|
|num\_ctx\_switches |x | | | | |
|
|
|num\_threads |x |x |x |x |x |
|
|
|cpu\_times |x | | | |x |
|
|
|memory\_info |x |x |x |x |x |
|
|
|memory\_info\_ex |x | | | | |
|
|
|memory\_maps |x | | | | |
|
|
|open\_files |x | | | | |
|
|
|send\_signal |x |x |x |x | |
|
|
|suspend |x |x |x |x | |
|
|
|resume |x |x |x |x | |
|
|
|terminate |x |x |x |x |x |
|
|
|kill |x |x |x |x | |
|
|
|username |x |x |x |x |x |
|
|
|ionice | | | | | |
|
|
|rlimit |x | | | | |
|
|
|num\_handlers | | | | | |
|
|
|threads |x | | | | |
|
|
|cpu\_percent |x | |x |x | |
|
|
|cpu\_affinity | | | | | |
|
|
|memory\_percent | | | | | |
|
|
|parent |x | |x |x |x |
|
|
|children |x |x |x |x |x |
|
|
|connections |x | |x |x | |
|
|
|is\_running | | | | | |
|
|
|page\_faults |x | | | | |
|
|
|
|
### Original Metrics
|
|
|
|
|item |Linux |FreeBSD |OpenBSD |macOS |Windows |Solaris |
|
|
|-----------------|-------|---------|---------|--------|--------|---------|
|
|
|**HostInfo** | | | | | | |
|
|
|hostname |x |x |x |x |x |x |
|
|
|uptime |x |x |x |x | |x |
|
|
|process |x |x |x | | |x |
|
|
|os |x |x |x |x |x |x |
|
|
|platform |x |x |x |x | |x |
|
|
|platformfamily |x |x |x |x | |x |
|
|
|virtualization |x | | | | | |
|
|
|**CPU** | | | | | | |
|
|
|VendorID |x |x |x |x |x |x |
|
|
|Family |x |x |x |x |x |x |
|
|
|Model |x |x |x |x |x |x |
|
|
|Stepping |x |x |x |x |x |x |
|
|
|PhysicalID |x | | | | |x |
|
|
|CoreID |x | | | | |x |
|
|
|Cores |x | | | |x |x |
|
|
|ModelName |x |x |x |x |x |x |
|
|
|Microcode |x | | | | |x |
|
|
|**LoadAvg** | | | | | | |
|
|
|Load1 |x |x |x |x | | |
|
|
|Load5 |x |x |x |x | | |
|
|
|Load15 |x |x |x |x | | |
|
|
|**GetDockerID** | | | | | | |
|
|
|container id |x |no |no |no |no | |
|
|
|**CgroupsCPU** | | | | | | |
|
|
|user |x |no |no |no |no | |
|
|
|system |x |no |no |no |no | |
|
|
|**CgroupsMem** | | | | | | |
|
|
|various |x |no |no |no |no | |
|
|
|
|
- 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
|
|
|
|
English is not my native language, so PRs correcting grammar or spelling
|
|
are welcome and appreciated.
|