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