gogctuner

README

gogctuner: GC Tuner for Go Applications

gogctuner is a Go library designed to automatically adjust the garbage collection (GC) parameters to optimize CPU usage based on the target memory usage percentage.

How it works

• Pre Go1.19 Versions: Utilizes a tuning strategy inspired by Uber's article, which adjusts the GOGC parameter based on the live heap size and target memory limit.
• Go1.19 and Later: Takes advantage of the soft memory limit feature introduced in Go 1.19, offering more granular control over GC behavior.

Features

• Memory Usage Based Tuning: Automatically adjusts GC parameters to maintain a specified percentage of memory usage.
• Cross-Version Compatibility: Compatible with Go versions below 1.19 and leverages the SetMemoryLimit features in Go 1.19 and above.
• cgroups Support: Works seamlessly with both cgroups and cgroupsv2 for enhanced resource management.
• Cross-OS Compatibility: Ensures functionality across multiple operating systems.

Usage

Static Configuration

Use static configuration by setting the MaxRAMPercentage at the initialization of your application:

package main

import (
  "github.com/fangwentong/gogctuner"
)

func main() {
  gogctuner.EnableGCTuner(
    gogctuner.WithStaticConfig(gogctuner.Config{MaxRAMPercentage: 90}),
  )
  // Your application code here
}

Dynamic Configuration

For dynamic configuration that allows runtime updates, you can use a configurator:

package main

import (
  "github.com/fangwentong/gogctuner"
)

func main() {
  configurator := gogctuner.NewGcConfigurator()

  // Integrate with your dynamic config implementation here:
  conf := readFromYourConfigCenter("your_config_key")
  configurator.SetConfig(conf) // set initial config
  // register config updates callback
  registerConfigUpdateCallback("your_config_key", func(conf gogctuner.Config) {
    configurator.SetConfig(conf)
  })

  gogctuner.EnableGCTuner(
    gogctuner.WithConfigurator(configurator),
  )
  // Your application code here
}

Reference

• Golang GC Guide: https://tip.golang.org/doc/gc-guide
• How We Saved 70K Cores Across 30 Mission-Critical Services (Large-Scale, Semi-Automated Go GC Tuning @Uber): https://www.uber.com/blog/how-we-saved-70k-cores-across-30-mission-critical-services/
• https://github.com/cch123/gogctuner
• https://github.com/VictoriaMetrics/VictoriaMetrics/tree/master/lib/cgroup

License

This project is licensed under the MIT License, see the LICENSE file for details.

Documentation

Index

• func EnableGCTuner(options ...Option) error
• func NewGcConfigurator() *gcConfigurator
• type Config
  • func (c *Config) CheckValid() error
• type Configurator
• type Logger
• type Option
  • func WithConfigurator(configurator Configurator) Option
  • func WithLogger(logger Logger) Option
  • func WithStaticConfig(config Config) Option

Functions

func EnableGCTuner

func EnableGCTuner(options ...Option) error

func NewGcConfigurator

func NewGcConfigurator() *gcConfigurator

Types

type Config

type Config struct {
	// GOGC is the maximum effective GOGC if specified.
	// When MaxRAMPercentage == 0, the GOGC pararameter will be set to debug.SetGCPercent.
	// If MaxRAMPercentage is set, in go1.18 and lower, gctuner dynamically adjusts GOGC(debug.SetGCPercent)
	// to meet the target memory limit, the GOGC specified here limits the maximum GOGC value.
	// In go1.19 and above, gctuner uses GOMEMLIMIT (debug.SetMemoryLimit) to meet target memory limit,
	// if GOGC is specified here, memory will be controlled by both GOGC and GOMEMLIMIT, triggering either of them will trigger GC.
	// In general, it is recommended that the user directly use MaxRAMPercentage without setting the GOGC parameter here.
	GOGC int `json:"gogc,omitempty" yaml:"gogc,omitempty"`

	// MaxRAMPercentage is the maximum memory usage, range (0, 100]
	MaxRAMPercentage float64 `json:"max_ram_percentage,omitempty" yaml:"max_ram_percentage,omitempty"`
}

Config is the configuration for adaptive GC

func (*Config) CheckValid

func (c *Config) CheckValid() error

type Configurator

type Configurator interface {
	// GetConfig retrieves the gctuner Config
	GetConfig() (Config, error)

	// Updates is the channel of config update events, which will be triggered upon config updates.
	// It returns nil if the configurator does not support config updates.
	// The gctuner will obtain the latest config by calling GetConfig.
	Updates() <-chan interface{}
}

Configurator is an interface for configuration management

type Logger

type Logger interface {
	Logf(format string, v ...interface{})
	Errorf(format string, v ...interface{})
}

type Option

type Option func(*opts)

func WithConfigurator

func WithConfigurator(configurator Configurator) Option

WithConfigurator sets the configurator for gctuner

func WithLogger

func WithLogger(logger Logger) Option

WithLogger sets the logger for gctuner, if not specified, a stdout logger is used by default.

func WithStaticConfig

func WithStaticConfig(config Config) Option

WithStaticConfig sets a static config for gctuner, which will not be updated.