Skip to main content
The load package provides functions to retrieve system load averages and miscellaneous process statistics. These metrics are essential for monitoring system performance and resource utilization.

Key Features

Load Average

Get 1, 5, and 15-minute load averages

Process Stats

Monitor process counts and context switches

Main Functions

Avg

Retrieves the system load averages for the past 1, 5, and 15 minutes.
func Avg() (*AvgStat, error)
func AvgWithContext(ctx context.Context) (*AvgStat, error)
Returns: AvgStat containing load averages

Misc

Retrieves miscellaneous host-wide process statistics.
func Misc() (*MiscStat, error)
func MiscWithContext(ctx context.Context) (*MiscStat, error)
Returns: MiscStat containing process counts and context switches

Data Structures

AvgStat

Contains system load averages.
type AvgStat struct {
    Load1  float64 // 1-minute load average
    Load5  float64 // 5-minute load average
    Load15 float64 // 15-minute load average
}
Load1
float64
Load average over the last 1 minute
Load5
float64
Load average over the last 5 minutes
Load15
float64
Load average over the last 15 minutes

MiscStat

Contains process-related statistics.
type MiscStat struct {
    ProcsTotal   int // Total number of processes
    ProcsCreated int // Number of processes created since boot
    ProcsRunning int // Number of running processes
    ProcsBlocked int // Number of blocked processes
    Ctxt         int // Number of context switches since boot
}
ProcsTotal
int
Total number of processes currently on the system
ProcsCreated
int
Total number of processes created since system boot
ProcsRunning
int
Number of processes currently in running state
ProcsBlocked
int
Number of processes currently blocked waiting for I/O
Ctxt
int
Total number of context switches since system boot

Understanding Load Average

Load average represents the average number of processes waiting to run or currently running on the CPU. It’s a measure of system utilization:
  • < 1.0 - System is underutilized
  • ≈ CPU cores - System is fully utilized
  • > CPU cores - System is overloaded
For example, on a 4-core system:
  • Load of 2.0 = 50% utilization
  • Load of 4.0 = 100% utilization
  • Load of 8.0 = System is overloaded (200%)

Usage Examples

Get Load Average

package main

import (
    "fmt"
    "github.com/shirou/gopsutil/v4/load"
)

func main() {
    loadAvg, err := load.Avg()
    if err != nil {
        panic(err)
    }
    
    fmt.Printf("Load Averages:\n")
    fmt.Printf("  1 min:  %.2f\n", loadAvg.Load1)
    fmt.Printf("  5 min:  %.2f\n", loadAvg.Load5)
    fmt.Printf("  15 min: %.2f\n", loadAvg.Load15)
}

Monitor System Load

package main

import (
    "fmt"
    "github.com/shirou/gopsutil/v4/cpu"
    "github.com/shirou/gopsutil/v4/load"
)

func main() {
    // Get number of CPU cores
    cpuCount, _ := cpu.Counts(true)
    
    loadAvg, err := load.Avg()
    if err != nil {
        panic(err)
    }
    
    // Calculate utilization percentage
    util1 := (loadAvg.Load1 / float64(cpuCount)) * 100
    util5 := (loadAvg.Load5 / float64(cpuCount)) * 100
    util15 := (loadAvg.Load15 / float64(cpuCount)) * 100
    
    fmt.Printf("CPU Cores: %d\n", cpuCount)
    fmt.Printf("Load Average & Utilization:\n")
    fmt.Printf("  1 min:  %.2f (%.1f%%)\n", loadAvg.Load1, util1)
    fmt.Printf("  5 min:  %.2f (%.1f%%)\n", loadAvg.Load5, util5)
    fmt.Printf("  15 min: %.2f (%.1f%%)\n", loadAvg.Load15, util15)
    
    // Alert if system is overloaded
    if loadAvg.Load1 > float64(cpuCount) {
        fmt.Println("\n⚠️  WARNING: System is overloaded!")
    }
}

Get Process Statistics

package main

import (
    "fmt"
    "github.com/shirou/gopsutil/v4/load"
)

func main() {
    misc, err := load.Misc()
    if err != nil {
        panic(err)
    }
    
    fmt.Printf("Process Statistics:\n")
    fmt.Printf("  Total Processes: %d\n", misc.ProcsTotal)
    fmt.Printf("  Running: %d\n", misc.ProcsRunning)
    fmt.Printf("  Blocked: %d\n", misc.ProcsBlocked)
    fmt.Printf("  Created Since Boot: %d\n", misc.ProcsCreated)
    fmt.Printf("  Context Switches: %d\n", misc.Ctxt)
}

Combined Monitoring

package main

import (
    "fmt"
    "time"
    "github.com/shirou/gopsutil/v4/load"
)

func main() {
    for {
        loadAvg, err := load.Avg()
        if err != nil {
            fmt.Println("Error:", err)
            continue
        }
        
        misc, err := load.Misc()
        if err != nil {
            fmt.Println("Error:", err)
            continue
        }
        
        fmt.Printf("\n[%s]\n", time.Now().Format("15:04:05"))
        fmt.Printf("Load: %.2f %.2f %.2f | ", 
            loadAvg.Load1, loadAvg.Load5, loadAvg.Load15)
        fmt.Printf("Procs: %d total, %d running, %d blocked\n",
            misc.ProcsTotal, misc.ProcsRunning, misc.ProcsBlocked)
        
        time.Sleep(5 * time.Second)
    }
}

Using Context

package main

import (
    "context"
    "fmt"
    "time"
    "github.com/shirou/gopsutil/v4/load"
)

func main() {
    ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
    defer cancel()
    
    loadAvg, err := load.AvgWithContext(ctx)
    if err != nil {
        panic(err)
    }
    
    misc, err := load.MiscWithContext(ctx)
    if err != nil {
        panic(err)
    }
    
    fmt.Printf("Load: %.2f, Processes: %d\n", 
        loadAvg.Load1, misc.ProcsTotal)
}

Platform Support

The load package is supported on:
  • Linux
  • macOS (Darwin)
  • FreeBSD
  • OpenBSD
  • Solaris
  • AIX
  • Windows (limited support)

Platform-Specific Behavior

Linux

  • Load averages read from /proc/loadavg
  • Process statistics from /proc/stat
  • All fields fully supported

macOS/BSD

  • Load averages from sysinfo syscall
  • Some process statistics may have limited availability

Windows

  • Limited support for load average calculation
  • May use alternative metrics

Data Sources

Linux

  • /proc/loadavg - Load average values
  • /proc/stat - Process and context switch statistics
  • sysinfo() syscall - Fallback method

Other Platforms

  • Platform-specific syscalls
  • Kernel statistics APIs

Common Use Cases

  • Performance Monitoring - Track system load trends
  • Alerting - Trigger alerts when load exceeds thresholds
  • Capacity Planning - Determine when to scale resources
  • Process Monitoring - Track process creation and execution
  • Scheduling - Optimize workload distribution
  • Troubleshooting - Identify performance bottlenecks

Best Practices

Always compare load average to the number of CPU cores. A load of 4.0 means different things on 2-core vs 8-core systems.
High numbers of blocked processes may indicate I/O bottlenecks.
Very high context switch rates can indicate thrashing or excessive multitasking.

See Also

Build docs developers (and LLMs) love