/go-autotune

Automatically configure GOMAXPROCS and GOMEMLIMIT. Supports both Linux and Windows.

Primary LanguageGoMIT LicenseMIT

go-autotune

go-reference go-version license test lint release version

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

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.

Disabling Automatic Configuration

To disable automatic configuration at runtime (for compiled binaries), Set GOAUTOTUNE environment variable to 0 or false.

Supporting Kubernetes In-place Resource Resize

This can be done using time.Ticker and a background goroutine. See API docs for examples.

See Kubernetes docs for more info.

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

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 and Job Objects API on Linux and Windows respectively. Thus, running unit tests/integration tests within containers is not supported.