gopsutil

psutil for golang

10,470

1,580

10,470

199

View on GitHub

Top Related Projects

cadvisor

16,909

Analyzes resource usage and performance characteristics of running containers.

telegraf

14,466

Agent for collecting, processing, aggregating, and writing metrics, logs, and other arbitrary data.

Quick Overview

gopsutil is a cross-platform library for retrieving process and system utilization written in Go. It provides an easy-to-use interface for accessing information about CPU, memory, disk, network, and other system resources. The library aims to be a Go equivalent of the Python psutil library.

Pros

Cross-platform support (Windows, Linux, macOS, FreeBSD)
Comprehensive system information retrieval (CPU, memory, disk, network, etc.)
Easy-to-use API with idiomatic Go design
Actively maintained with regular updates and bug fixes

Cons

Some platform-specific features may not be available on all operating systems
Performance overhead for certain operations, especially on Windows
Limited documentation for advanced usage scenarios
Potential security implications when used with elevated privileges

Code Examples

Get CPU usage percentage:

import "github.com/shirou/gopsutil/v3/cpu"

percent, err := cpu.Percent(time.Second, false)
if err != nil {
    log.Fatal(err)
}
fmt.Printf("CPU usage: %.2f%%\n", percent[0])

Get memory information:

import "github.com/shirou/gopsutil/v3/mem"

vmStat, err := mem.VirtualMemory()
if err != nil {
    log.Fatal(err)
}
fmt.Printf("Total memory: %v, Used: %v, Free: %v\n", vmStat.Total, vmStat.Used, vmStat.Free)

List all processes:

import "github.com/shirou/gopsutil/v3/process"

processes, err := process.Processes()
if err != nil {
    log.Fatal(err)
}
for _, p := range processes {
    name, _ := p.Name()
    fmt.Printf("PID: %d, Name: %s\n", p.Pid, name)
}

Getting Started

To use gopsutil in your Go project, follow these steps:

Install the library:
```
go get github.com/shirou/gopsutil/v3
```

Import the desired packages in your Go code:

import (
    "github.com/shirou/gopsutil/v3/cpu"
    "github.com/shirou/gopsutil/v3/mem"
    "github.com/shirou/gopsutil/v3/disk"
)

Start using the library functions in your code as shown in the examples above.

Competitor Comparisons

node_exporter

10,934

Exporter for machine metrics

Pros of node_exporter

Designed specifically for Prometheus monitoring, offering seamless integration
Provides a wide range of exporters for various system metrics out-of-the-box
Highly extensible with custom collectors and textfile inputs

Cons of node_exporter

Limited to Linux and Unix-like systems, lacking Windows support
Focused on exporting metrics rather than providing a general-purpose system information library
Requires running as a separate process, which may increase resource usage

Code Comparison

node_exporter (Go):

func (c *cpuCollector) Update(ch chan<- prometheus.Metric) error {
    times, err := c.cpu.Times(false)
    if err != nil {
        return err
    }
    for _, t := range times {
        ch <- prometheus.MustNewConstMetric(c.cpu.User, prometheus.CounterValue, t.User)
    }
    return nil
}

gopsutil (Go):

func CPUTimes(percpu bool) ([]CPUTimesStat, error) {
    var ret []CPUTimesStat
    var err error
    if percpu {
        ret, err = perCPUTimes()
    } else {
        ret, err = allCPUTimes()
    }
    return ret, err
}

Both libraries provide CPU metrics, but node_exporter focuses on exporting Prometheus-compatible metrics, while gopsutil offers a more general-purpose API for retrieving system information.

cadvisor

16,909

Analyzes resource usage and performance characteristics of running containers.

Pros of cAdvisor

Provides a web UI for real-time resource usage and performance data visualization
Designed specifically for containerized environments, offering deep insights into Docker containers
Integrates well with Kubernetes and other container orchestration platforms

Cons of cAdvisor

More focused on container metrics, potentially less versatile for general system monitoring
Heavier resource footprint compared to gopsutil due to its comprehensive features
May require additional setup and configuration for non-containerized environments

Code Comparison

gopsutil:

cpu, _ := cpu.Percent(time.Second, false)
mem, _ := mem.VirtualMemory()
disk, _ := disk.Usage("/")

cAdvisor:

containerInfo, err := client.ContainerInfo("/docker/containerID", &v1.ContainerInfoRequest{NumStats: 1})
cpuUsage := containerInfo.Stats[0].Cpu.Usage.Total
memoryUsage := containerInfo.Stats[0].Memory.Usage

Summary

gopsutil is a lightweight, general-purpose system information library for Go, suitable for various monitoring tasks across different operating systems. cAdvisor, on the other hand, is specialized for container monitoring, offering rich features and visualizations specifically tailored for containerized environments. The choice between the two depends on the specific use case, with gopsutil being more versatile for general system monitoring and cAdvisor excelling in container-centric scenarios.

telegraf

14,466

Agent for collecting, processing, aggregating, and writing metrics, logs, and other arbitrary data.

Pros of Telegraf

More comprehensive data collection capabilities, supporting a wide range of input plugins for various systems and services
Built-in support for sending data to multiple output destinations, including InfluxDB and other time-series databases
Highly configurable and extensible, allowing users to create custom plugins

Cons of Telegraf

Larger footprint and more complex setup compared to gopsutil
May be overkill for simple system monitoring tasks
Steeper learning curve due to its extensive feature set

Code Comparison

gopsutil:

cpu, _ := cpu.Percent(time.Second, false)
mem, _ := mem.VirtualMemory()
disk, _ := disk.Usage("/")

Telegraf:

[[inputs.cpu]]
[[inputs.mem]]
[[inputs.disk]]
  mount_points = ["/"]
[[outputs.influxdb]]
  urls = ["http://localhost:8086"]

Summary

Gopsutil is a lightweight library focused on system information retrieval, ideal for simple monitoring tasks or integration into Go applications. Telegraf, on the other hand, is a full-featured agent for collecting, processing, and outputting metrics, suitable for more complex monitoring scenarios and integration with time-series databases. While gopsutil offers direct programmatic access to system metrics, Telegraf provides a configuration-based approach with extensive plugin support for various data sources and outputs.

Convert designs to code with AI

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot

README

gopsutil: psutil for golang

This is a port of psutil (https://github.com/giampaolo/psutil). The challenge is porting all psutil functions on some architectures.

migration

v4 migration

There are some breaking changes. Please see v4 release note.

Tag semantics

gopsutil tag policy is almost same as Semantic Versioning, but automatically increases like Ubuntu versioning.

For example, v4.24.04 means

v4: major version
24: release year, 2024
04: release month

gopsutil aims to keep backwards compatibility 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 i386/amd64/arm/arm64
Darwin amd64/arm64
OpenBSD i386/amd64/armv7/arm64/riscv64 (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

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

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.

You can set an alternative location to / by setting the HOST_ROOT environment variable.

You can set an alternative location to /proc/N/mountinfo by setting the HOST_PROC_MOUNTINFO environment variable.

Adding settings using `context` (from v3.23.6)

As of v3.23.6, it is now possible to pass a path location using context: import "github.com/shirou/gopsutil/v3/common" and pass a context with common.EnvMap set to common.EnvKey, and the location will be used within each function.

	ctx := context.WithValue(context.Background(), 
		common.EnvKey, common.EnvMap{common.HostProcEnvKey: "/myproc"},
	)
	v, err := mem.VirtualMemoryWithContext(ctx)

First priority is given to the value set in context, then the value from the environment variable, and finally the default location.

Caching

As of v3.24.1, it is now possible to cached some values. These values default to false, not cached.

Be very careful that enabling the cache may cause inconsistencies. For example, if you enable caching of boottime on Linux, be aware that unintended values may be returned if the boottime is changed by NTP after booted.

host
- EnableBootTimeCache
process
- EnableBootTimeCache

`Ex` struct (from v4.24.5)

gopsutil is designed to work across multiple platforms. However, there are differences in the information available on different platforms, such as memory information that exists on Linux but not on Windows.

As of v4.24.5, to access this platform-specific information, gopsutil provides functions named Ex within the package. Currently, these functions are available in the mem and sensor packages.

The Ex structs are specific to each platform. For example, on Linux, there is an ExLinux struct, which can be obtained using the mem.NewExLinux() function. On Windows, it's mem.ExWindows(). These Ex structs provide platform-specific information.

ex := NewExWindows()
v, err := ex.VirtualMemory()
if err != nil {
    panic(err)
}

fmt.Println(v.VirtualAvail)
fmt.Println(v.VirtualTotal)

// Output:
// 140731958648832
// 140737488224256

gopsutil aims to minimize platform differences by offering common functions. However, there are many requests to obtain unique information for each platform. The Ex structs are designed to meet those requests. Additional functionalities might be added in the future. The use of these structures makes it clear that the information they provide is specific to each platform, which is why they have been designed in this way.

Documentation

See https://pkg.go.dev/github.com/shirou/gopsutil/v4 or https://godocs.io/github.com/shirou/gopsutil/v4

Requirements

go1.18 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
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/Avg() (linux, freebsd, solaris)
- 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: works
b: almost works, but something is broken
c: works in CGO only

name	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

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

Original Metrics

item	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
ModelName	x	x	x	x	x	x	x
Microcode	x					x
LoadAvg
Load1	x	x	x	x			x
Load5	x	x	x	x			x
Load15	x	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
- AIX processes

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

Fork it
Create your feature branch (git checkout -b my-new-feature)
Commit your changes (git commit -am 'Add some feature')
Push to the branch (git push origin my-new-feature)
Create new Pull Request

English is not my native language, so PRs correcting grammar or spelling are welcome and appreciated.

Top Related Projects

Convert designs to code with AI

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot

Top Related Projects

Quick Overview

Pros

Cons

Code Examples

Getting Started

Competitor Comparisons

Pros of node_exporter

Cons of node_exporter

Code Comparison

Pros of cAdvisor

Cons of cAdvisor

Code Comparison

Summary

Pros of Telegraf

Cons of Telegraf

Code Comparison

Summary

Convert designs to code with AI

README

gopsutil: psutil for golang

migration

v4 migration

Tag semantics

Available Architectures

Usage

Adding settings using context (from v3.23.6)

Caching

Ex struct (from v4.24.5)

Documentation

Requirements

More Info

Current Status

Process class

Original Metrics

License

Related Works

How to Contribute

Top Related Projects

Convert designs to code with AI

Adding settings using `context` (from v3.23.6)

`Ex` struct (from v4.24.5)