# gopsutil — Cross-Platform System Information Library for Go

> A Go port of the Python psutil library that retrieves system and process metrics including CPU, memory, disk, network, and host information across Linux, macOS, Windows, and FreeBSD.

## Install

Save in your project root:

# gopsutil — Cross-Platform System Information Library for Go

## Quick Use
```bash
go get github.com/shirou/gopsutil/v4

// Get CPU usage
import "github.com/shirou/gopsutil/v4/cpu"
percent, _ := cpu.Percent(time.Second, false)
fmt.Printf("CPU: %.1f%%
", percent[0])

// Get memory info
import "github.com/shirou/gopsutil/v4/mem"
v, _ := mem.VirtualMemory()
fmt.Printf("Mem: %.1f%% used
", v.UsedPercent)
```

## 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

---
Source: https://tokrepo.com/en/workflows/asset-495389b0
Author: AI Open Source