shirou/gopsutil
GitHub: shirou/gopsutil
gopsutil 是 psutil 的 Go 语言移植版，提供跨平台的系统与进程资源监控数据采集能力。
Stars: 11882 | Forks: 1676
# gopsutil: Go 语言的 psutil
[](https://github.com/shirou/gopsutil/actions/workflows/test.yml) [](https://pkg.go.dev/github.com/shirou/gopsutil/v4) [](https://calver.org/)
这是 psutil (https://github.com/giampaolo/psutil) 的一个移植版本。挑战
在于将所有的 psutil 功能移植到某些架构上。
## 迁移
### v4 迁移
存在一些破坏性更新。请查阅 [v4 发布说明](https://github.com/shirou/gopsutil/releases/tag/v4.24.5)。
## 标签语义
gopsutil 的标签策略与语义化版本控制几乎相同，但
会像 [Ubuntu 版本控制](https://calver.org/) 那样自动递增。
例如，v4.24.04 表示
- v4：主版本号
- 24：发布年份，2024 年
- 04：发布月份
gopsutil 致力于在主版本变更之前保持向后兼容性。
在每个月末进行标签标记，但如果只有少数几次提交，则
可能会跳过。
## 支持的架构
- FreeBSD i386/amd64/arm
- Linux i386/amd64/arm(raspberry pi)
- Windows i386/amd64/arm/arm64
- Darwin amd64/arm64
- OpenBSD i386/amd64/armv7/arm64/riscv64 (感谢 @mpfz0r！)
- Solaris amd64 (在 SmartOS/Illumos 上开发并测试，感谢 @jen20！)
- DragonFly BSD 上的 CPU (#893, 感谢 @gballet！)
- Linux RISC-V 上的 host (#896, 感谢 @tklauser！)
所有的工作都是通过将 C 结构体移植为 Go 结构体来实现的，没有使用 cgo。
## 用法
```
package main
import (
"fmt"
"github.com/shirou/gopsutil/v4/mem"
)
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)
}
```
输出如下。
```
Total: 3179569152, Free:284233728, UsedPercent:84.508194%
{"total":3179569152,"available":492572672,"used":2895335424,"usedPercent":84.50819439828305, (snip...)}
```
你可以使用以下环境变量来为各种系统目录设置备用位置：
- /proc: `HOST_PROC`
- /sys: `HOST_SYS`
- /etc: `HOST_ETC`
- /var: `HOST_VAR`
- /run: `HOST_RUN`
- /dev: `HOST_DEV`
- /: `HOST_ROOT`
- /proc/N/mountinfo: `HOST_PROC_MOUNTINFO`
### 使用 `context` 添加设置（自 v3.23.6 起）
从 v3.23.6 开始，现在可以使用 `context` 来传递路径位置：导入 `"github.com/shirou/gopsutil/v3/common"`，并传递一个将 `common.EnvMap` 设置为 `common.EnvKey` 的 context，该位置将在每个函数中使用。
```
ctx := context.WithValue(context.Background(),
common.EnvKey, common.EnvMap{common.HostProcEnvKey: "/myproc"},
)
v, err := mem.VirtualMemoryWithContext(ctx)
```
优先级首先赋予 `context` 中设置的值，其次是环境变量的值，最后是默认位置。
### 缓存
从 v3.24.1 开始，现在可以对某些值进行缓存。这些值默认为 false，即不缓存。
请注意，启用缓存可能会导致不一致。例如，如果你在 Linux 上启用了 boottime 缓存，请注意，如果[在启动后 boottime 被 NTP 修改](https://github.com/shirou/gopsutil/issues/1070#issuecomment-842512782)，则可能会返回意外的值。
- `host`
- EnableBootTimeCache
- `process`
- EnableBootTimeCache
### `Ex` 结构体（自 v4.24.5 起）
gopsutil 旨在跨多个平台运行。然而，不同平台上可用的信息存在差异，例如 Linux 上存在内存信息，而 Windows 上则没有。
从 v4.24.5 开始，为了访问这些特定于平台的信息，gopsutil 在包中提供了名为 `Ex` 的函数。目前，这些函数可在 mem 和 sensor 包中使用。
Ex 结构体是特定于每个平台的。例如，在 Linux 上有一个 `ExLinux` 结构体，可以使用 `mem.NewExLinux()` 函数获取。在 Windows 上，则是 `mem.ExWindows()`。这些 Ex 结构体提供了特定于平台的信息。
```
ex := NewExWindows()
v, err := ex.VirtualMemory()
if err != nil {
panic(err)
}
fmt.Println(v.VirtualAvail)
fmt.Println(v.VirtualTotal)
// Output:
// 140731958648832
// 140737488224256
```
gopsutil 旨在通过提供通用函数来最小化平台差异。然而，有很多获取每个平台独有信息的需求。Ex 结构体旨在满足这些需求。未来可能会添加额外的功能。使用这些结构体可以明确表明它们提供的信息是特定于每个平台的，这也是采用这种设计方式的原因。
## 文档
参见 https://pkg.go.dev/github.com/shirou/gopsutil/v4 或 https://godocs.io/github.com/shirou/gopsutil/v4
## 要求
- 需要 go1.18 或更高版本。
## 更多信息
添加了一些 psutil 中不存在的方法，但
将提供有用的信息。
- host/HostInfo() (linux)
- Hostname
- Uptime
- Procs
- OS (例如: "linux")
- Platform (例如: "ubuntu", "arch")
- PlatformFamily (例如: "debian")
- PlatformVersion (例如: "Ubuntu 13.10")
- VirtualizationSystem (例如: "LXC")
- VirtualizationRole (例如: "guest"/"host")
- IOCounters
- Label (仅限 linux) 注册的 [device mapper
名称](https://www.kernel.org/doc/Documentation/ABI/testing/sysfs-block-dm)
- cpu/CPUInfo() (linux, freebsd)
- CPU (例如: 0, 1, ...)
- VendorID (例如: "GenuineIntel")
- Family
- Model
- Stepping
- PhysicalID
- CoreID
- Cores (例如: 2)
- ModelName (例如: "Intel(R) Core(TM) i7-2640M CPU @ 2.80GHz")
- Mhz
- CacheSize
- Flags (例如: "fpu vme de pse tsc msr pae mce cx8 ...")
- Microcode
- load/Avg() (linux, freebsd, solaris)
- Load1
- Load5
- Load15
- docker/GetDockerIDList() (仅限 linux)
- container id 列表 ([]string)
- docker/CgroupCPU() (仅限 linux)
- user
- system
- docker/CgroupMem() (仅限 linux)
- 各种状态
- net_protocols (仅限 linux)
- 网络协议的系统级统计信息 (如 IP, TCP, UDP 等)
- 来源于 /proc/net/snmp
- iptables nf_conntrack (仅限 linux)
- netfilter conntrack 模块的系统级统计信息
- 来源于 /proc/sys/net/netfilter/nf_conntrack_count
部分代码移植自 Ohai。非常感谢。
## 当前状态
- x: 正常工作
- b: 基本正常工作，但有些功能存在问题
|名称 |Linux |FreeBSD |OpenBSD |macOS |Windows |Solaris |Plan 9 |AIX |
|----------------------|-------|---------|---------|--------|---------|---------|---------|---------|
|cpu\_times |x |x |x |x |x | |b |x |
|cpu\_count |x |x |x |x |x | |x |x |
|cpu\_percent |x |x |x |x |x | | |x |
|cpu\_times\_percent |x |x |x |x |x | | |x |
|virtual\_memory |x |x |x |x |x |b |x |x |
|swap\_memory |x |x |x |x | | |x |X |
|disk\_partitions |x |x |x |x |x | | |x |
|disk\_io\_counters |x |x |x |x |x | | | |
|disk\_usage |x |x |x |x |x | | |x |
|net\_io\_counters |x |x |x |b |x |x | | |
|boot\_time |x |x |x |x |x | | |X |
|users |x |x |x |x |x | | |x |
|pids |x |x |x |x |x | | | |
|pid\_exists |x |x |x |x |x | | | |
|net\_connections |x |x |x |x | | | |x |
|net\_protocols |x | | | | | | |x |
|net\_if\_addrs | | | | | | | |x |
|net\_if\_stats | | | | | | | |x |
|netfilter\_conntrack |x | | | | | | | |
|sensors_temperature |x | | |x |x |x | | |
### Process 类
|名称 |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 |x |
|create\_time |x | | |x |x |
|status |x |x |x |x | |
|cwd |x |x |x |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 | | |x |x |
|num\_ctx\_switches |x | | | | |
|num\_threads |x |x |x |x |x |
|cpu\_times |x | | | |x |
|memory\_info |x |x |x |x |x |
|memory\_maps |x | | | | |
|open\_files |x | | | |x |
|send\_signal |x |x |x |x | |
|suspend |x |x |x |x |x |
|resume |x |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 |x |
|cpu\_affinity | | | | | |
|memory\_percent |x | | | |x |
|parent |x | |x |x |x |
|children |x |x |x |x |x |
|connections |x | |x |x | |
|is\_running | | | | | |
|page\_faults |x | | | |x |
### gopsutil 原生指标
|项目 |Linux |FreeBSD |OpenBSD |macOS |Windows |Solaris |AIX |
|------------------------|-------|---------|---------|--------|--------|---------|---------|
|**HostInfo** | | | | | | | |
|hostname |x |x |x |x x |x |X |
|uptime |x |x |x |x | |x |x |
|process |x |x |x | | |x | |
|os |x |x |x |x |x |x |x |
|platform |x |x |x |x | |x |x |
|platformfamily |x |x |x |x | |x |x |
|virtualization |x | | | | | | |
|**CPU** | | | | | | | |
|VendorID |x |x |x |x |x |x |x |
|Family |x |x |x |x |x |x |x |
|Model |x |x |x |x |x |x |x |
|Stepping |x |x |x |x |x |x | |
|PhysicalID |x | | | | |x | |
|CoreID |x | | | | |x | |
|Cores |x | | |x |x |x |x |
|ModelName |x |x |x |x |x |x |x |
|Microcode |x | | | | |x | |
|**LoadAvg** | | | | | | | |
|Load1 |x |x |x |x |x |x |x |
|Load5 |x |x |x |x |x |x |x |
|Load15 |x |x |x |x |x |x |x |
|**Docker GetDockerID** | | | | | | | |
|container id |x |no |no |no |no |no |no |
|**Docker CgroupsCPU** | | | | | | | |
|user |x |no |no |no |no |no |no |
|system |x |no |no |no |no |no |no |
|**Docker CgroupsMem** | | | | | | | |
|various |x |no |no |no |no |no |no |
- 未来工作
- process_iter
- wait_procs
- Process class
- as_dict
- wait
- AIX processes
## 许可证
New BSD License (与 psutil 相同)
## 相关作品
我受到了以下优秀作品的影响：
- 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
标签：EVTX分析, 日志审计