gopsutil: golang版的psutil

这是psutil (https://github.com/giampaolo/psutil) 的移植版。挑战在于将所有psutil函数移植到某些架构上。

迁移

v4迁移

有一些破坏性变更。请参阅v4发布说明。

标签语义

gopsutil的标签策略几乎与语义化版本控制相同，但会自动增加，类似于Ubuntu版本控制。

例如，v4.24.04表示

• v4: 主版本
• 24: 发布年份，2024年
• 04: 发布月份

gopsutil旨在保持向后兼容性，直到主版本变更。

每月底打标签，但如果只有少量提交，可能会跳过。

可用架构

• FreeBSD i386/amd64/arm
• Linux i386/amd64/arm(树莓派)
• 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上的主机 (#896, 感谢@tklauser!)

所有工作都是通过将C结构移植到golang结构来实现的，无需使用cgo。

使用方法

package main

import (
    "fmt"

    "github.com/shirou/gopsutil/v4/mem"
)

func main() {
    v, _ := mem.VirtualMemory()

    // 几乎每个返回值都是一个结构体
    fmt.Printf("总计: %v, 空闲:%v, 使用率:%f%%\n", v.Total, v.Free, v.UsedPercent)

    // 转换为JSON。String()方法也已实现
    fmt.Println(v)
}

输出如下：

总计: 3179569152, 空闲:284233728, 使用率:84.508194%
{"total":3179569152,"available":492572672,"used":2895335424,"usedPercent":84.50819439828305, (省略...)}

你可以通过设置HOST_PROC环境变量来指定一个替代的/proc位置。

你可以通过设置HOST_SYS环境变量来指定一个替代的/sys位置。

你可以通过设置HOST_ETC环境变量来指定一个替代的/etc位置。

你可以通过设置HOST_VAR环境变量来指定一个替代的/var位置。

你可以通过设置HOST_RUN环境变量来指定一个替代的/run位置。

你可以通过设置HOST_DEV环境变量来指定一个替代的/dev位置。

你可以通过设置HOST_ROOT环境变量来指定一个替代的/位置。

你可以通过设置HOST_PROC_MOUNTINFO环境变量来指定一个替代的/proc/N/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上启用了启动时间的缓存，请注意如果NTP在启动后更改了启动时间，可能会返回意外的值。

• 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)

// 输出：
// 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)
  • 主机名
  • 运行时间
  • 进程数
  • 操作系统（如："linux"）
  • 平台（如："ubuntu"、"arch"）
  • 平台系列（如："debian"）
  • 平台版本（如："Ubuntu 13.10"）
  • 虚拟化系统（如："LXC"）
  • 虚拟化角色（如："guest"/"host"）
• IOCounters
  • 标签（仅限 Linux）已注册的设备映射器名称
• cpu/CPUInfo() (Linux, FreeBSD)
  • CPU（如：0, 1, ...）
  • 厂商 ID（如："GenuineIntel"）
  • 系列
  • 型号
  • 步进
  • 物理 ID
  • 核心 ID
  • 核心数（如：2）
  • 型号名称（如："Intel(R) Core(TM) i7-2640M CPU @ 2.80GHz"）
  • 频率
  • 缓存大小
  • 标志（如："fpu vme de pse tsc msr pae mce cx8 ..."）
  • 微码
• load/Avg() (Linux, FreeBSD, Solaris)
  • 1分钟负载
  • 5分钟负载
  • 15分钟负载
• docker/GetDockerIDList() (仅限 Linux)
  • 容器 ID 列表 ([]string)
• docker/CgroupCPU() (仅限 Linux)
  • 用户
  • 系统
• 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: 基本可用，但有些问题
• c: 仅在 CGO 中可用

功能名称	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
disk_usage	x	x	x	x	x			x
net_io_counters	x	x	x	b	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

进程类

名称	Linux	FreeBSD	OpenBSD	macOS	Windows
进程ID	x	x	x	x	x
父进程ID	x	x	x	x	x
名称	x	x	x	x	x
命令行	x	x		x	x
创建时间	x			x	x
状态	x	x	x	x
当前工作目录	x			x	x
可执行文件路径	x	x	x		x
用户ID	x	x	x	x
组ID	x	x	x	x
终端	x	x	x
I/O计数器	x	x	x		x
优先级	x	x	x	x	x
文件描述符数量	x
上下文切换次数	x
线程数	x	x	x	x	x
CPU时间	x				x
内存信息	x	x	x	x	x
扩展内存信息	x
内存映射	x
打开的文件	x
发送信号	x	x	x	x
挂起	x	x	x	x
恢复	x	x	x	x
终止	x	x	x	x	x
杀死	x	x	x	x
用户名	x	x	x	x	x
I/O优先级
资源限制	x
处理程序数量
线程	x
CPU使用率	x		x	x	x
CPU亲和性
内存使用率	x				x
父进程	x		x	x	x
子进程	x	x	x	x	x
网络连接	x		x	x
是否运行
页面错误	x

原始指标

项目	Linux	FreeBSD	OpenBSD	macOS	Windows	Solaris	AIX
主机信息
主机名	x	x	x	x	x	x	X
运行时间	x	x	x	x		x	x
进程	x	x	x			x
操作系统	x	x	x	x	x	x	x
平台	x	x	x	x		x	x
平台系列	x	x	x	x		x	x
虚拟化	x
CPU
供应商ID	x	x	x	x	x	x	x
系列	x	x	x	x	x	x	x
型号	x	x	x	x	x	x	x
步进	x	x	x	x	x	x
物理ID	x					x
核心ID	x					x
核心数	x				x	x	x
型号名称	x	x	x	x	x	x	x
微码	x					x
负载平均值
1分钟负载	x	x	x	x			x
5分钟负载	x	x	x	x			x
15分钟负载	x	x	x	x			x
获取Docker ID
容器ID	x	否	否	否	否
Cgroups CPU
用户	x	否	否	否	否
系统	x	否	否	否	否
Cgroups内存
各种	x	否	否	否	否

• 未来工作
  • 进程迭代器
  • 等待进程
  • 进程类
    • as_dict
    • wait
  • AIX进程

许可证

新BSD许可证（与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

如何贡献

1. 复刻（Fork）项目
2. 创建你的功能分支（git checkout -b my-new-feature）
3. 提交你的更改（git commit -am '添加某个功能'）
4. 推送到分支（git push origin my-new-feature）
5. 创建新的拉取请求

英语不是我的母语，因此欢迎并感谢纠正语法或拼写错误的拉取请求。