Lomanic
/
gopsutil
mirror of https://github.com/shirou/gopsutil
1
0
Fork 0
Code Issues Releases Activity

convert README from reStructuredText to Markdown

Browse Source
pull/1128/head
Yoshiki Shibukawa 4 years ago
parent 5268453c1e
commit 05e51b6d4b
2 changed files with 294 additions and 332 deletions
Show Stats Download Patch File Download Diff File

294
README.md
Unescape Escape View File

@ -0,0 +1,294 @@
# gopsutil: psutil for golang
[![Test](https://github.com/shirou/gopsutil/actions/workflows/test.yml/badge.svg)](https://github.com/shirou/gopsutil/actions/workflows/test.yml) [![Coverage Status](https://coveralls.io/repos/github/shirou/gopsutil/badge.svg?branch=master)](https://coveralls.io/github/shirou/gopsutil?branch=master) [![Go Reference](https://pkg.go.dev/badge/github.com/shirou/gopsutil.svg)](https://pkg.go.dev/github.com/shirou/gopsutil)
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 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.
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/amd64
- Darwin i386/amd64
- 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.
## 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](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/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 code is ported from Ohai. many thanks.
## Current Status
- x: work
- b: almost works, but something is broken
|name |Linux |FreeBSD |OpenBSD |macOS |Windows |Solaris |
|----------------------|-------|---------|---------|--------|---------|---------|
|cpu\_times |x |x |x |x |x | |
|cpu\_count |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 |
|swap\_memory |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 | | | | |
|exe |x |x |x | |x |
|uids |x |x |x |x | |
|gids |x |x |x |x | |
|terminal |x |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 |
|proces |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 grammer or spelling
are welcome and appreciated.

332
README.rst
Unescape Escape View File

@ -1,332 +0,0 @@
gopsutil: psutil for golang
==============================
.. image:: https://github.com/shirou/gopsutil/workflows/Test/badge.svg
:target: https://github.com/shirou/gopsutil/actions?query=workflow%3ATest
.. image:: https://coveralls.io/repos/shirou/gopsutil/badge.svg?branch=master
:target: https://coveralls.io/r/shirou/gopsutil?branch=master
.. image:: https://godoc.org/github.com/shirou/gopsutil?status.svg
:target: http://godoc.org/github.com/shirou/gopsutil
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 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.
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/amd64
- Darwin i386/amd64
- 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
---------
.. code:: 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 :code:`/proc` by setting the :code:`HOST_PROC` environment variable.
You can set an alternative location to :code:`/sys` by setting the :code:`HOST_SYS` environment variable.
You can set an alternative location to :code:`/etc` by setting the :code:`HOST_ETC` environment variable.
You can set an alternative location to :code:`/var` by setting the :code:`HOST_VAR` environment variable.
You can set an alternative location to :code:`/run` by setting the :code:`HOST_RUN` environment variable.
You can set an alternative location to :code:`/dev` by setting the :code:`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 <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/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 code is ported from Ohai. many thanks.
Current Status
------------------
- x: work
- b: almost works, but something is broken
=================== ====== ======= ======= ====== ======= =======
name Linux FreeBSD OpenBSD MacOSX Windows Solaris
cpu_times x x x x x
cpu_count 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
swap_memory 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 MacOSX 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
exe x x x x
uids x x x x
gids x x x x
terminal x 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 MacOSX Windows Solaris
**HostInfo**
hostname x x x x x x
uptime x x x x x
proces 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 grammer or spelling are
welcome and appreciated.
Write Preview
Loading…
Cancel
Save