1# gopsutil: psutil for golang
2
3[](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)
4
5This is a port of psutil (https://github.com/giampaolo/psutil). The
6challenge is porting all psutil functions on some architectures.
7
8## v3 migration
9
10from v3.20.10, gopsutil becomes v3 which breaks backwards compatiblity.
11See [v3Changes.md](_tools/v3migration/v3Changes.md) more detail changes.
12
13## Tag semantics
14
15gopsutil tag policy is almost same as Semantic Versioning, but
16automatically increase like Ubuntu versioning.
17
18for example, v2.17.04 means
19
20- v2: major version
21- 17: release year, 2017
22- 04: release month
23
24gopsutil aims to keep backwards-compatiblity until major version change.
25
26Tagged at every end of month, but if there are only a few commits, it
27can be skipped.
28
29## Available Architectures
30
31- FreeBSD i386/amd64/arm
32- Linux i386/amd64/arm(raspberry pi)
33- Windows i386/amd64/arm/arm64
34- Darwin i386/amd64
35- OpenBSD amd64 (Thank you @mpfz0r!)
36- Solaris amd64 (developed and tested on SmartOS/Illumos, Thank you
37 @jen20!)
38
39These have partial support:
40
41- CPU on DragonFly BSD (#893, Thank you @gballet!)
42- host on Linux RISC-V (#896, Thank you @tklauser!)
43
44All works are implemented without cgo by porting C structs to golang
45structs.
46
47## Usage
48
49```go
50package main
51
52import (
53 "fmt"
54
55 "github.com/shirou/gopsutil/v3/mem"
56 // "github.com/shirou/gopsutil/mem" // to use v2
57)
58
59func main() {
60 v, _ := mem.VirtualMemory()
61
62 // almost every return value is a struct
63 fmt.Printf("Total: %v, Free:%v, UsedPercent:%f%%\n", v.Total, v.Free, v.UsedPercent)
64
65 // convert to JSON. String() is also implemented
66 fmt.Println(v)
67}
68```
69
70The output is below.
71
72 Total: 3179569152, Free:284233728, UsedPercent:84.508194%
73 {"total":3179569152,"available":492572672,"used":2895335424,"usedPercent":84.50819439828305, (snip...)}
74
75You can set an alternative location to `/proc` by setting the `HOST_PROC`
76environment variable.
77
78You can set an alternative location to `/sys` by setting the `HOST_SYS`
79environment variable.
80
81You can set an alternative location to `/etc` by setting the `HOST_ETC`
82environment variable.
83
84You can set an alternative location to `/var` by setting the `HOST_VAR`
85environment variable.
86
87You can set an alternative location to `/run` by setting the `HOST_RUN`
88environment variable.
89
90You can set an alternative location to `/dev` by setting the `HOST_DEV`
91environment variable.
92
93## Documentation
94
95see http://godoc.org/github.com/shirou/gopsutil
96
97## Requirements
98
99- go1.16 or above is required.
100
101## More Info
102
103Several methods have been added which are not present in psutil, but
104will provide useful information.
105
106- host/HostInfo() (linux)
107 - Hostname
108 - Uptime
109 - Procs
110 - OS (ex: "linux")
111 - Platform (ex: "ubuntu", "arch")
112 - PlatformFamily (ex: "debian")
113 - PlatformVersion (ex: "Ubuntu 13.10")
114 - VirtualizationSystem (ex: "LXC")
115 - VirtualizationRole (ex: "guest"/"host")
116- IOCounters
117 - Label (linux only) The registered [device mapper
118 name](https://www.kernel.org/doc/Documentation/ABI/testing/sysfs-block-dm)
119- cpu/CPUInfo() (linux, freebsd)
120 - CPU (ex: 0, 1, ...)
121 - VendorID (ex: "GenuineIntel")
122 - Family
123 - Model
124 - Stepping
125 - PhysicalID
126 - CoreID
127 - Cores (ex: 2)
128 - ModelName (ex: "Intel(R) Core(TM) i7-2640M CPU @ 2.80GHz")
129 - Mhz
130 - CacheSize
131 - Flags (ex: "fpu vme de pse tsc msr pae mce cx8 ...")
132 - Microcode
133- load/LoadAvg() (linux, freebsd)
134 - Load1
135 - Load5
136 - Load15
137- docker/GetDockerIDList() (linux only)
138 - container id list ([]string)
139- docker/CgroupCPU() (linux only)
140 - user
141 - system
142- docker/CgroupMem() (linux only)
143 - various status
144- net_protocols (linux only)
145 - system wide stats on network protocols (i.e IP, TCP, UDP, etc.)
146 - sourced from /proc/net/snmp
147- iptables nf_conntrack (linux only)
148 - system wide stats on netfilter conntrack module
149 - sourced from /proc/sys/net/netfilter/nf_conntrack_count
150
151Some code is ported from Ohai. many thanks.
152
153## Current Status
154
155- x: works
156- b: almost works, but something is broken
157
158|name |Linux |FreeBSD |OpenBSD |macOS |Windows |Solaris |Plan 9 |
159|----------------------|-------|---------|---------|--------|---------|---------|---------|
160|cpu\_times |x |x |x |x |x | |b |
161|cpu\_count |x |x |x |x |x | |x |
162|cpu\_percent |x |x |x |x |x | | |
163|cpu\_times\_percent |x |x |x |x |x | | |
164|virtual\_memory |x |x |x |x |x | b |x |
165|swap\_memory |x |x |x |x | | |x |
166|disk\_partitions |x |x |x |x |x | | |
167|disk\_io\_counters |x |x |x | | | | |
168|disk\_usage |x |x |x |x |x | | |
169|net\_io\_counters |x |x |x |b |x | | |
170|boot\_time |x |x |x |x |x | | |
171|users |x |x |x |x |x | | |
172|pids |x |x |x |x |x | | |
173|pid\_exists |x |x |x |x |x | | |
174|net\_connections |x | |x |x | | | |
175|net\_protocols |x | | | | | | |
176|net\_if\_addrs | | | | | | | |
177|net\_if\_stats | | | | | | | |
178|netfilter\_conntrack |x | | | | | | |
179
180
181### Process class
182
183|name |Linux |FreeBSD |OpenBSD |macOS |Windows |
184|--------------------|-------|---------|---------|-------|---------|
185|pid |x |x |x |x |x |
186|ppid |x |x |x |x |x |
187|name |x |x |x |x |x |
188|cmdline |x |x | |x |x |
189|create\_time |x | | |x |x |
190|status |x |x |x |x | |
191|cwd |x | | |x | |
192|exe |x |x |x | |x |
193|uids |x |x |x |x | |
194|gids |x |x |x |x | |
195|terminal |x |x |x | | |
196|io\_counters |x |x |x | |x |
197|nice |x |x |x |x |x |
198|num\_fds |x | | | | |
199|num\_ctx\_switches |x | | | | |
200|num\_threads |x |x |x |x |x |
201|cpu\_times |x | | | |x |
202|memory\_info |x |x |x |x |x |
203|memory\_info\_ex |x | | | | |
204|memory\_maps |x | | | | |
205|open\_files |x | | | | |
206|send\_signal |x |x |x |x | |
207|suspend |x |x |x |x | |
208|resume |x |x |x |x | |
209|terminate |x |x |x |x |x |
210|kill |x |x |x |x | |
211|username |x |x |x |x |x |
212|ionice | | | | | |
213|rlimit |x | | | | |
214|num\_handlers | | | | | |
215|threads |x | | | | |
216|cpu\_percent |x | |x |x | |
217|cpu\_affinity | | | | | |
218|memory\_percent | | | | | |
219|parent |x | |x |x |x |
220|children |x |x |x |x |x |
221|connections |x | |x |x | |
222|is\_running | | | | | |
223|page\_faults |x | | | | |
224
225### Original Metrics
226
227|item |Linux |FreeBSD |OpenBSD |macOS |Windows |Solaris |
228|-----------------|-------|---------|---------|--------|--------|---------|
229|**HostInfo** | | | | | | |
230|hostname |x |x |x |x |x |x |
231|uptime |x |x |x |x | |x |
232|proces |x |x |x | | |x |
233|os |x |x |x |x |x |x |
234|platform |x |x |x |x | |x |
235|platformfamily |x |x |x |x | |x |
236|virtualization |x | | | | | |
237|**CPU** | | | | | | |
238|VendorID |x |x |x |x |x |x |
239|Family |x |x |x |x |x |x |
240|Model |x |x |x |x |x |x |
241|Stepping |x |x |x |x |x |x |
242|PhysicalID |x | | | | |x |
243|CoreID |x | | | | |x |
244|Cores |x | | | |x |x |
245|ModelName |x |x |x |x |x |x |
246|Microcode |x | | | | |x |
247|**LoadAvg** | | | | | | |
248|Load1 |x |x |x |x | | |
249|Load5 |x |x |x |x | | |
250|Load15 |x |x |x |x | | |
251|**GetDockerID** | | | | | | |
252|container id |x |no |no |no |no | |
253|**CgroupsCPU** | | | | | | |
254|user |x |no |no |no |no | |
255|system |x |no |no |no |no | |
256|**CgroupsMem** | | | | | | |
257|various |x |no |no |no |no | |
258
259- future work
260 - process_iter
261 - wait_procs
262 - Process class
263 - as_dict
264 - wait
265
266## License
267
268New BSD License (same as psutil)
269
270## Related Works
271
272I have been influenced by the following great works:
273
274- psutil: https://github.com/giampaolo/psutil
275- dstat: https://github.com/dagwieers/dstat
276- gosigar: https://github.com/cloudfoundry/gosigar/
277- goprocinfo: https://github.com/c9s/goprocinfo
278- go-ps: https://github.com/mitchellh/go-ps
279- ohai: https://github.com/opscode/ohai/
280- bosun:
281 https://github.com/bosun-monitor/bosun/tree/master/cmd/scollector/collectors
282- mackerel:
283 https://github.com/mackerelio/mackerel-agent/tree/master/metrics
284
285## How to Contribute
286
2871. Fork it
2882. Create your feature branch (git checkout -b my-new-feature)
2893. Commit your changes (git commit -am 'Add some feature')
2904. Push to the branch (git push origin my-new-feature)
2915. Create new Pull Request
292
293English is not my native language, so PRs correcting grammar or spelling
294are welcome and appreciated.
View as plain text