heroagent/pkg/system/stats

System Stats Package

The stats package provides a comprehensive solution for collecting, caching, and retrieving system statistics in Go applications. It uses Redis for caching to minimize system resource usage when frequently accessing system metrics.

Overview

This package offers a thread-safe, configurable system for monitoring:

• CPU usage and information
• Memory utilization
• Disk space and usage
• Process statistics
• Network speed and throughput
• Hardware information

The StatsManager provides a central interface for accessing all system statistics with built-in caching, background updates, and configurable expiration times.

Key Components

StatsManager

The core component that manages all statistics collection with Redis-based caching:

• Thread-safe operations with mutex protection
• Background worker for asynchronous updates
• Configurable expiration times for different stat types
• Debug mode for direct fetching without caching
• Automatic cache initialization and updates

Statistics Types

The package collects various system statistics:

1. System Information (system)

   • CPU details (cores, model, usage percentage)
   • Memory information (total, used, free, usage percentage)
   • Network speed (upload and download)

2. Disk Statistics (disk)

   • Information for all mounted partitions
   • Total, used, and free space
   • Usage percentages

3. Process Statistics (process)

   • List of running processes
   • CPU and memory usage per process
   • Process status and creation time
   • Command line information

4. Network Speed (network)

   • Current upload and download speeds
   • Formatted with appropriate units (Mbps/Kbps)

5. Hardware Statistics (hardware)

   • Combined system, disk, and network information
   • Formatted for easy display or JSON responses

Configuration

The Config struct allows customization of:

• Redis connection settings (address, password, database)
• Expiration times for different types of statistics
• Debug mode toggle
• Default timeout for waiting for stats
• Maximum queue size for update requests

Default configuration is provided through the DefaultConfig() function.

Usage Examples

Basic Usage

// Create a stats manager with default settings
manager, err := stats.NewStatsManagerWithDefaults()
if err != nil {
    log.Fatalf("Error creating stats manager: %v", err)
}
defer manager.Close()

// Get system information
sysInfo, err := manager.GetSystemInfo()
if err != nil {
    log.Printf("Error getting system info: %v", err)
} else {
    fmt.Printf("CPU Cores: %d\n", sysInfo.CPU.Cores)
    fmt.Printf("Memory Used: %.1f GB (%.1f%%)\n", 
        sysInfo.Memory.Used, sysInfo.Memory.UsedPercent)
}

// Get disk statistics
diskStats, err := manager.GetDiskStats()
if err != nil {
    log.Printf("Error getting disk stats: %v", err)
} else {
    for _, disk := range diskStats.Disks {
        fmt.Printf("%s: %.1f GB total, %.1f GB free (%.1f%% used)\n", 
            disk.Path, disk.Total, disk.Free, disk.UsedPercent)
    }
}

// Get top processes by CPU usage
processes, err := manager.GetTopProcesses(5)
if err != nil {
    log.Printf("Error getting top processes: %v", err)
} else {
    for i, proc := range processes {
        fmt.Printf("%d. %s (PID: %d, CPU: %.1f%%, Memory: %.1f MB)\n", 
            i+1, proc.Name, proc.PID, proc.CPUPercent, proc.MemoryMB)
    }
}

Custom Configuration

// Create a custom configuration
config := &stats.Config{
    RedisAddr:     "localhost:6379",
    RedisPassword: "",
    RedisDB:       0,
    Debug:         false,
    QueueSize:     100,
    DefaultTimeout: 5 * time.Second,
    ExpirationTimes: map[string]time.Duration{
        "system":   60 * time.Second,  // System info expires after 60 seconds
        "disk":     300 * time.Second, // Disk info expires after 5 minutes
        "process":  30 * time.Second,  // Process info expires after 30 seconds
        "network":  30 * time.Second,  // Network info expires after 30 seconds
        "hardware": 120 * time.Second, // Hardware stats expire after 2 minutes
    },
}

manager, err := stats.NewStatsManager(config)
if err != nil {
    log.Fatalf("Error creating stats manager: %v", err)
}
defer manager.Close()

Force Updates and Cache Management

// Force an immediate update of system stats
err := manager.ForceUpdate("system")
if err != nil {
    log.Printf("Error forcing update: %v", err)
}

// Clear the cache for a specific stats type
err = manager.ClearCache("disk")
if err != nil {
    log.Printf("Error clearing cache: %v", err)
}

// Clear the entire cache
err = manager.ClearCache("")
if err != nil {
    log.Printf("Error clearing entire cache: %v", err)
}

Debug Mode

// Enable debug mode to bypass caching
manager.Debug = true

// Get stats directly without using cache
sysInfo, err := manager.GetSystemInfo()

// Disable debug mode to resume caching
manager.Debug = false