Disable Transparent Huge Pages (THP)

Transparent Huge Pages (THP) is a Linux memory management systemthat reduces the overhead of Translation Lookaside Buffer (TLB) lookupson machines with large amounts of memory by using larger memory pages.

However, database workloads often perform poorly with THP enabled,because they tend to have sparse rather than contiguous memory accesspatterns. When running MongoDB on Linux, THP should be disabled forbest performance.

To ensure that THP is disabled before mongod starts,you should create a new init.d script to apply the appropriate THPsetting, and configure it to run at boot. Additionally, forRHEL / CentOS systems that make useof ktune and tuned performance profiles, you mustcreate a custom tuned profile as well.

Init Script

Create the init.d script.

Create the following file at /etc/init.d/disable-transparent-hugepages:

#!/bin/bash
### BEGIN INIT INFO
# Provides:          disable-transparent-hugepages
# Required-Start:    $local_fs
# Required-Stop:
# X-Start-Before:    mongod mongodb-mms-automation-agent
# Default-Start:     2 3 4 5
# Default-Stop:      0 1 6
# Short-Description: Disable Linux transparent huge pages
# Description:       Disable Linux transparent huge pages, to improve
#                    database performance.
### END INIT INFO
 
case $1 in
  start)
    if [ -d /sys/kernel/mm/transparent_hugepage ]; then
      thp_path=/sys/kernel/mm/transparent_hugepage
    elif [ -d /sys/kernel/mm/redhat_transparent_hugepage ]; then
      thp_path=/sys/kernel/mm/redhat_transparent_hugepage
    else
      return 0
    fi
 
    echo 'never' | tee ${thp_path}/enabled > /dev/null
 
    unset thp_path
    ;;
esac

Note

Prior to version 4.2, MongoDB also checks the THP _defrag_setting and presents a startup warning if defrag isenabled. As long as THP itself is disabled inthe init.d script, MongoDB is unaffected by the defragsetting. However, to avoid this message, you may set defrag tonever by adding the following line to the init.dscript, just before the unset thp_path statement:

echo 'never' | tee ${thp_path}/defrag > /dev/null

Make it executable.

Run the following command to make the script executable:

sudo chmod 755 /etc/init.d/disable-transparent-hugepages

Run the script.

Run the script manually once to ensure that the appropriate THPsetting has been changed:

sudo /etc/init.d/disable-transparent-hugepages start

Verify that THP has successfully been set to [never] by running thefollowing command:

cat /sys/kernel/mm/transparent_hugepage/enabled

On Red Hat Enterprise Linux, CentOS, and potentially other RedHat-based derivatives, you may instead need to use the following:

cat /sys/kernel/mm/redhat_transparent_hugepage/enabled

Configure your operating system to run it on boot.

To ensure that this setting is applied each time your systemboots, run the following command for your Linux distribution:

sudo update-rc.d disable-transparent-hugepages defaults

sudo insserv /etc/init.d/disable-transparent-hugepages

sudo chkconfig —add disable-transparent-hugepages

Customize tuned / ktune profile, if applicable.

If you are using tuned or ktune onRHEL/ CentOS,you must now also create a custom tuned profile.

Using tuned and ktune

Important

If using tuned or ktune, you must also perform the steps inthis section after installing the init script.

tuned and ktune are dynamic kernel tuning tools that can affectthe transparent huge pages setting on your system. If you are usingtuned / ktune on your RHEL/ CentOS system while running mongod, you must create a customtuned profile to ensure that THP remains disabled.

Red Hat/CentOS 6

Create a new profile.

Create a new profile from an existing profile by copying therelevant directory. This example uses thevirtual-guest profile as the base, and usesvirtual-guest-no-thp as the new profile:

sudo cp -r /etc/tune-profiles/virtual-guest /etc/tune-profiles/virtual-guest-no-thp

Edit ktune.sh.

Edit /etc/tune-profiles/virtual-guest-no-thp/ktune.shand change the set_transparent_hugepages setting to thefollowing:

set_transparent_hugepages never

Enable the new profile.

Enable the new profile:

sudo tuned-adm profile virtual-guest-no-thp

Red Hat/CentOS 7 and 8

Create a new profile.

Create a new directory to hold the custom tuned profile.This example inherits from the existing virtual-guestprofile, and uses virtual-guest-no-thp as the new profile:

sudo mkdir /etc/tuned/virtual-guest-no-thp

Edit tuned.conf.

Create and edit /etc/tuned/virtual-guest-no-thp/tuned.conf so that it contains thefollowing:

[main]
include=virtual-guest
 
[vm]
transparent_hugepages=never

This example inherits from the existing virtual-guestprofile. Select the profile most appropriate for your system.

Enable the new profile.

Enable the new profile:

sudo tuned-adm profile virtual-guest-no-thp