gopsutil — Cross-Platform System Information Library for Go

Introduction

gopsutil is a Go library that provides a cross-platform API for retrieving system utilization data such as CPU, memory, disk, network, and process information. Inspired by Python's psutil, it abstracts away OS-specific system calls behind a unified Go interface, making it straightforward to build monitoring tools, dashboards, and health-check endpoints.

What gopsutil Does

• Retrieves CPU usage percentages, core counts, and frequency information
• Reports virtual and swap memory usage, available capacity, and page statistics
• Lists disk partitions, usage stats, and I/O counters per device
• Provides network interface stats, connection tables, and I/O counters
• Enumerates running processes with CPU, memory, and file descriptor details

Architecture Overview

gopsutil implements separate sub-packages (cpu, mem, disk, net, host, process) each containing platform-specific implementations behind build tags. On Linux it reads /proc and /sys filesystems, on macOS it calls sysctl and IOKit, and on Windows it uses Win32 API calls. A common struct-based API normalizes these differences so calling code works unchanged across platforms.

Self-Hosting & Configuration

• Import specific sub-packages to avoid pulling in unused platform code
• Use context-aware variants of functions for timeout and cancellation support
• Set environment variable HOST_PROC to /host/proc when running inside containers to read host metrics
• Configure HOST_SYS and HOST_ETC for non-standard filesystem layouts
• Use the process sub-package with elevated permissions for full process enumeration on Windows

Key Features

• Cross-platform: works on Linux, macOS, Windows, FreeBSD, and OpenBSD
• No CGO required: pure Go implementation on most platforms
• Container-aware: supports reading host metrics from within Docker or Kubernetes pods
• Process management: list, filter, and inspect individual process details
• Sensor data: read temperature sensors and fan speeds where available

Comparison with Similar Tools

• psutil (Python) — the original inspiration; richer feature set in Python but gopsutil brings the same concept to Go with native performance
• machineid — focused only on unique machine identification; gopsutil covers the full system metrics spectrum
• procfs (Prometheus) — Linux-only /proc parser; gopsutil is cross-platform and higher-level
• go-sysinfo (Elastic) — similar goals with a focus on Elastic stack integration; gopsutil has broader community adoption

FAQ

Q: Does gopsutil work inside Docker containers? A: Yes. Set HOST_PROC=/host/proc and mount the host's /proc filesystem to read host-level metrics from inside a container.

Q: Does it require CGO? A: No. gopsutil is pure Go on Linux and macOS. On Windows, it uses syscall without CGO.

Q: How often should I poll for CPU usage? A: cpu.Percent accepts an interval parameter. A one-second interval provides reasonable accuracy. Shorter intervals increase CPU overhead.

Q: Can I monitor individual process resource usage? A: Yes. Use process.NewProcess(pid) to get CPU percent, memory info, open files, and other per-process details.

Sources

• https://github.com/shirou/gopsutil
• https://pkg.go.dev/github.com/shirou/gopsutil/v4