go-autotune

Automatically configure GOMAXPROCS and GOMEMLIMIT for your applications to match CPU quota and memory limits assigned. Supports both Windows and Linux.

How

• For Linux, CPU and memory limits are obtained from cgroup v2 interface files.
• For Windows, Job Objects API is used.

Usage

Simply blank import github.com/tprasadtp/go-autotune in your main package.

package main

import (
	_ "github.com/tprasadtp/go-autotune" // Automatically adjusts GOMAXPROCS & GOMEMLIMIT
)

See API docs and example for more info.

Requirements (Linux)

This module only supports cgroups V2. Following Linux distributions enable it by default.

• Container Optimized OS (since M97)
• Ubuntu (since 21.10)
• Debian (since Debian 11 Bullseye)
• Fedora (since 31)
• Arch Linux (since April 2021)
• RHEL and RHEL-like distributions (since 9)
• Kubernetes 1.25 or later
• containerd v1.4 or later
• cri-o v1.20 or later

For systemd user level units, CPU delegation is enabled by default for systemd 252 or later. For older versions, It needs to be enabled manually. This also affects rootless docker and podman.

Requirements (Windows)

• Windows 10 or later
• Windows Server 2019 or later.

Incompatible Modules

This module is incompatible with other modules which also tweak GOMAXPROCS and GOMEMLIMIT. Following golangci-lint snippet might help avoid any issues.

linters-settings:
  # <snip other linter settings>
  gomodguard:
    blocked:
      modules:
        # <snip other modules>
        - go.uber.org/automaxprocs:
            reason: >-
              Does not handle fractional CPUs well and does not support Windows.
            recommendations:
              - github.com/tprasadtp/go-autotune
        - github.com/KimMachineGun/automemlimit:
            reason: >-
              Does not support cgroups mounted at non standard location.
              Also does not support memory.high and does not support Windows.
            recommendations:
              - github.com/tprasadtp/go-autotune
linters:
  enabled:
    # <snip other enabled linters>
    - gomodguard

Example Docker Images

Example docker images are only provided for limited number of platforms/architectures. However the library will work on all platforms which meet the requirements specified above, even when running outside of containers. See example for more info.

docker run --rm --cpus=1.5 --memory=250M ghcr.io/tprasadtp/go-autotune

Windows

Linux

Testing

Testing on Linux requires cgroups v2 support enabled and systemd 252 or later. Testing on Windows requires Windows 10 20H2/Windows Server 2019 or later.

go test -cover -v ./...

Important

Tests extensively use systemd-run on Linux and Job Objects API on Windows respectively. Thus, running unit tests/integration tests within containers is not supported.