Adaptive GOMAXPROCS

A smart Go library that automatically detects and sets optimal GOMAXPROCS values for your applications, with support for containers, dynamic adjustment, and various deployment environments.

Features

• ?? Automatic Detection: Intelligently detects optimal GOMAXPROCS based on system resources
• ?? Container-Aware: Supports Docker, Kubernetes, and other containerized environments
• ?? Dynamic Adjustment: Real-time adjustment based on CPU usage patterns
• ??? Safety Margins: Configurable safety margins to prevent resource oversubscription
• ?? Flexible Logging: Customizable logging with structured output
• ?? Highly Configurable: Extensive configuration options for different use cases

Installation

go get 

Quick Start

Basic Usage

packagemainimport("log""")funcmain(){// Set optimal GOMAXPROCS automaticallyinfo,err:=adaptive.SetOptimal()iferr!=nil{log.Fatal(err)}log.Printf("Set GOMAXPROCS to %d (detected %d cores)",info.RecommendedProcs,info.DetectedCores)// Your application code here...}

Dynamic Adjustment

packagemainimport("log""time""")funcmain(){// Start dynamic GOMAXPROCS adjustmentmanager,err:=adaptive.StartDynamic()iferr!=nil{log.Fatal(err)}deferadaptive.StopGlobal()// Your application runs here...time.Sleep(10*time.Minute)// Check current CPU usagelog.Printf("Current CPU usage: %.2f%%",manager.GetLastCPUUsage()*100)}

Configuration

Custom Configuration

config:=adaptive.Config{MinProcs:1,MaxProcs:16,SafetyMargin:0.15,// 15% safety marginEnableLogging:true,UpdateInterval:30*time.Second,CPUThresholds:adaptive.CPUThresholds{HighUsage:0.8,// 80% - increase GOMAXPROCSLowUsage:0.3,// 30% - decrease GOMAXPROCS},}info,err:=adaptive.SetOptimal(config)iferr!=nil{log.Fatal(err)}

Environment-Specific Configurations

For Containers/Kubernetes

config:=adaptive.DefaultConfig()config.SafetyMargin=0.2// Higher safety margin for containersconfig.MaxProcs=8// Limit maximum processorsadaptive.SetOptimal(config)

For High-Performance Applications

config:=adaptive.DefaultConfig()config.SafetyMargin=0.05// Lower safety marginconfig.UpdateInterval=10*time.Second// More frequent adjustmentsconfig.CPUThresholds.HighUsage=0.9// Allow higher CPU usageadaptive.StartDynamic(config)

API Reference

Core Functions

SetOptimal(config ...Config) (*ResourceInfo, error)

Sets GOMAXPROCS to the optimal value based on detected system resources.

DetectResources() (*ResourceInfo, error)

Analyzes the system and returns detailed resource information without changing GOMAXPROCS.

StartDynamic(config ...Config) (*AdaptiveManager, error)

Starts dynamic GOMAXPROCS adjustment based on CPU usage patterns.

StopGlobal()

Stops the global dynamic adjustment manager.

Configuration Types

Config

Main configuration struct with the following fields:

• MinProcs (int): Minimum number of processors to use
• MaxProcs (int): Maximum number of processors to use
• SafetyMargin (float64): Percentage (0.0-1.0) to reduce from detected cores
• EnableLogging (bool): Controls whether to log GOMAXPROCS changes
• Logger (Logger): Custom logger interface
• UpdateInterval (time.Duration): Interval for dynamic adjustment
• CPUThresholds (CPUThresholds): CPU usage thresholds for adjustment

CPUThresholds

Defines CPU usage thresholds:

• HighUsage (float64): Threshold to increase GOMAXPROCS
• LowUsage (float64): Threshold to decrease GOMAXPROCS

ResourceInfo

Contains detected system information:

• DetectedCores (int): Number of CPU cores detected
• ContainerLimit (float64): Container CPU limit (if detected)
• IsContainer (bool): Whether running in a container
• Source (string): Detection method used
• RecommendedProcs (int): Recommended GOMAXPROCS value

Advanced Usage

Custom Logger

import"log"customLogger:=log.New(os.Stdout,"[CUSTOM] ",log.LstdFlags)config:=adaptive.DefaultConfig()config.Logger=customLoggeradaptive.SetOptimal(config)

Resource Detection Only

info,err:=adaptive.DetectResources()iferr!=nil{log.Fatal(err)}log.Printf("Detected %d cores from %s",info.DetectedCores,info.Source)ifinfo.IsContainer{log.Printf("Container limit: %.2f",info.ContainerLimit)}

Manual Manager Control

config:=adaptive.DefaultConfig()manager:=adaptive.NewAdaptiveManager(config)// Start the managererr:=manager.Start()iferr!=nil{log.Fatal(err)}// Check if runningifmanager.IsRunning(){log.Println("Dynamic adjustment is active")}// Stop the managermanager.Stop()

Detection Methods

The library uses multiple detection methods in order of preference:

1. Container Detection:

   • Docker cgroups v1 (/sys/fs/cgroup/cpu/cpu.cfs_quota_us)
   • Docker cgroups v2 (/sys/fs/cgroup/cpu.max)
   • Kubernetes Downward API
   • Environment variables (CPU_LIMIT)

2. System Detection:

   • /proc/cpuinfo parsing
   • runtime.NumCPU() fallback

Container Support

Docker

The library automatically detects Docker container CPU limits:

# DockerfileFROMgolang:1.21-alpineCOPY . .RUN go build -o app .# Set CPU limitCMD ["./app"]

# Run with CPU limit
docker run --cpus="2.5" your-app

Kubernetes

# deployment.yamlapiVersion:apps/v1kind:Deploymentmetadata:name:your-appspec:template:spec:containers:- name:appimage:your-app:latestresources:limits:cpu:"2"requests:cpu:"1"

Docker Compose

# docker-compose.ymlversion:'3.8'services:app:build:.deploy:resources:limits:cpus:'2.5'reservations:cpus:'1'

Best Practices

1. Choose Appropriate Safety Margins

• Development: 0.1 (10%) - allows some oversubscription
• Production: 0.15-0.2 (15-20%) - more conservative
• Containers: 0.2+ (20%+) - account for container overhead

2. Configure CPU Thresholds Wisely

// For CPU-intensive applicationsconfig.CPUThresholds=adaptive.CPUThresholds{HighUsage:0.9,// Allow high CPU usageLowUsage:0.4,// Scale down when underutilized}// For latency-sensitive applicationsconfig.CPUThresholds=adaptive.CPUThresholds{HighUsage:0.7,// Scale up earlyLowUsage:0.2,// Keep resources available}

3. Monitor and Log

config:=adaptive.DefaultConfig()config.EnableLogging=true// Custom logger with structured outputconfig.Logger=log.New(os.Stdout,"[GOMAXPROCS] ",log.LstdFlags|log.Lshortfile)

4. Test in Your Environment

// Test detection before using in productioninfo,err:=adaptive.DetectResources()iferr!=nil{log.Printf("Detection failed: %v",err)}log.Printf("Would set GOMAXPROCS to %d (detected %d, source: %s)",info.RecommendedProcs,info.DetectedCores,info.Source)

Performance Considerations

• Detection Overhead: Resource detection is fast (< 1ms typically)
• Dynamic Adjustment: Uses minimal CPU (< 0.1% overhead)
• Memory Usage: Very low memory footprint (< 1MB)
• Thread Safety: All operations are thread-safe

Troubleshooting

Common Issues

1. Permission Denied: Ensure read access to /proc/cpuinfo and cgroup files
2. No Container Limit Detected: Check if running in a properly configured container
3. High CPU Usage: Adjust UpdateInterval or CPU thresholds

Debug Mode

config:=adaptive.DefaultConfig()config.EnableLogging=true// Get detailed informationinfo,err:=adaptive.DetectResources()log.Printf("Debug: %+v",info)

Validation

// Validate configurationconfig:=adaptive.Config{MinProcs:1,MaxProcs:32,SafetyMargin:0.1,}ifconfig.MinProcs<1{log.Fatal("MinProcs must be at least 1")}ifconfig.MaxProcs<config.MinProcs{log.Fatal("MaxProcs must be >= MinProcs")}

Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Roadmap

• Support for more container runtimes (Podman, CRI-O)
• Advanced CPU usage prediction algorithms
• Integration with monitoring systems (Prometheus, etc.)
• Support for NUMA topology awareness
• Automatic detection of application characteristics

License

This project is licensed under the GNU Lesser General Public License (LGPL) - see the LICENSE file for details.