From 0c12b63ef2ab4e467b81f76f34da44da2a9cec44 Mon Sep 17 00:00:00 2001 From: Michael Anthony Knyszek Date: Tue, 5 Dec 2023 20:50:20 +0000 Subject: [PATCH] _content/doc: update huge page details with max_ptes_none workarounds Go 1.21.1 and Go 1.22 have ceased working around an issue with Linux kernel defaults for transparent huge pages that can result in excessive memory overheads. (https://bugzilla.kernel.org/show_bug.cgi?id=93111) Many Linux distributions disable huge pages altogether these days, so this problem isn't quite as far-reaching as it used to be. Also, the problem only affects Go programs with very particular memory usage patterns. That being said, because the runtime used to actively deal with this problem (but with some unpredictable behavior), it's preventing users that don't have a lot of control over their execution environment from upgrading to Go beyond Go 1.20. This adds documentation about this change in behavior in both the GC guide and the Go 1.21 release notes. For golang/go#64332. Change-Id: I29baaffcc678d08255364a3cd6f11211ce4164ba Reviewed-on: https://go-review.googlesource.com/c/website/+/547675 Auto-Submit: Michael Knyszek Reviewed-by: Mauri de Souza Meneguzzo Reviewed-by: Michael Pratt LUCI-TryBot-Result: Go LUCI --- _content/doc/gc-guide.html | 16 +++++++++++++--- _content/doc/go1.21.md | 8 +++++++- 2 files changed, 20 insertions(+), 4 deletions(-) diff --git a/_content/doc/gc-guide.html b/_content/doc/gc-guide.html index 2fe7c735..51395c2d 100644 --- a/_content/doc/gc-guide.html +++ b/_content/doc/gc-guide.html @@ -1539,7 +1539,7 @@ we recommend the following additional settings for Go programs.

  • -

    +

    Set /sys/kernel/mm/transparent_hugepage/khugepaged/max_ptes_none to 0.
    @@ -1551,8 +1551,18 @@ we recommend the following additional settings for Go programs. runtime does to return memory to the OS. Before Go 1.21, the Go runtime tried to mitigate the negative effects of the default setting, but it came with a CPU cost. - With Go 1.21+ and Linux 6.2+, the Go runtime will coalesce regular pages - into huge pages itself with its own more accurate heuristics. + With Go 1.21+ and Linux 6.2+, the Go runtime no longer mutates huge page + state. +
    +
    + If you experience an increase in memory usage when upgrading to Go 1.21.1 or + later, try applying this setting; it will likely resolve your issue. + As an additional workaround, you can call + the Prctl + function with PR_SET_THP_DISABLE to disable huge pages at + the process level, or you can set GODEBUG=disablethp=1 (to be + added in Go 1.21.6 and Go 1.22) to disable huge pages for heap memory. + Note that the GODEBUG setting may be removed in a future release.

    • diff --git a/_content/doc/go1.21.md b/_content/doc/go1.21.md index 4e849fdd..26d7076f 100644 --- a/_content/doc/go1.21.md +++ b/_content/doc/go1.21.md @@ -231,7 +231,13 @@ now manages which parts of the heap may be backed by huge pages more explicitly. This leads to better utilization of memory: small heaps should see less memory used (up to 50% in pathological cases) while large heaps should see fewer broken huge pages for dense parts of the -heap, improving CPU usage and latency by up to 1%. +heap, improving CPU usage and latency by up to 1%. A consequence of this +change is that the runtime no longer tries to work around a particular +problematic Linux configuration setting, which may result in higher +memory overheads. The recommended fix is to adjust the OS's huge page +settings according to the [GC guide](/doc/gc-guide#Linux_transparent_huge_pages). +However, other workarounds are available as well. See the [section on +`max_ptes_none`](/doc/gc-guide#Linux_THP_max_ptes_none_workaround). As a result of runtime-internal garbage collection tuning,