🐺 A library to curb OOMs by running Go GC according to a user-defined policy.
Package watchdog runs a singleton memory watchdog in the process, which watches memory utilization and forces Go GC in accordance with a user-defined policy.
There three kinds of watchdogs:
watchdog.HeapDriven()
): applies a heap limit, adjusting GOGCwatchdog.SystemDriven()
): applies a limit to the totalwatchdog.CgroupDriven()
): discovers the memory limit fromThe watchdog's behaviour is controlled by the policy, a pluggable function that determines when to trigger GC based on the current utilization. This library ships with two policies:
watchdog.NewWatermarkPolicy()
): runs GC at configuredwatchdog.NewAdaptivePolicy()
): runs GC when the currentYou can easily write a custom policy tailored to the allocation patterns of your program.
The recommended way to set up the watchdog is as follows, in descending order of precedence. This logic assumes that the library supports setting a heap limit through an environment variable (e.g. MYAPP_HEAP_MAX) or config key.
Given the low-level nature of this component, some tests need to run in isolation, so that they don't carry over Go runtime metrics. For completeness, this module uses a Docker image for testing, so we can simulate cgroup memory limits.
The test execution and docker builds have been conveniently packaged in a Makefile. Run with:
$ make
The garbage collector that ships with the go runtime is pretty good in some regards (low-latency, negligible no stop-the-world), but it's insatisfactory in a number of situations that yield ill-fated outcomes:
For more information, check out these GitHub issues:
Dual-licensed: MIT, Apache Software License v2, by way of the Permissive License Stack.