Database Manual / Self-Managed Deployments / Administration / Performance / TCMalloc Performance

Disable Transparent Hugepages (THP) for Self-Managed Deployments

Important

Upgraded TCMalloc in MongoDB 8.0

Starting in MongoDB 8.0, MongoDB uses an upgraded version of TCMalloc that improves performance with Transparent Hugepages enabled. If you are using MongoDB 8.0 or later, see Enable Transparent Hugepages (THP).

Transparent Hugepages (THP) is a Linux memory management system that reduces the overhead of Translation Lookaside Buffer (TLB) lookups. THP achieves this by combining small pages and making them appear as larger memory pages to the application.

When running MongoDB 7.0 or earlier on Linux, THP should be disabled for best performance. In earlier versions of MongoDB, database workloads often experience decreased performance with THP enabled because they often use non-contiguous, memory access patterns.

Note

THP operates at a system level, so it applies to all processes under the system. You cannot enable or disable THP per-process level.

To ensure that THP is disabled before mongod starts, create a service file for your operating system that disables THP at boot. The following instructions include examples for both the systemd and the System V init initialization systems.

Additionally, for RHEL and CentOS systems that use ktune and tuned performance profiles, you must create a custom tuned profile as well.

Create a Service File

To create a service file that disables THP, use the built-in initialization system for your operating system. Recent versions of Linux typically use systemd, which uses the systemctl command. Older versions of Linux use System V init, which uses the service command. For more information, see the documentation for your operating system.

Use the initialization system for your operating system:

1

Create the systemd unit file

Create the following file and save it at /etc/systemd/system/disable-transparent-huge-pages.service:

[Unit]
Description=Disable Transparent Hugepages (THP)
DefaultDependencies=no
After=sysinit.target local-fs.target
Before=mongod.service

[Service]
Type=oneshot
ExecStart=/bin/sh -c 'echo never | tee /sys/kernel/mm/transparent_hugepage/enabled > /dev/null && echo never | tee /sys/kernel/mm/transparent_hugepage/defrag > /dev/null'

[Install]
WantedBy=basic.target

Note

Some versions of Red Hat Enterprise Linux, and potentially other Red Hat-based derivatives, use a different path for the THP enabled file:

/sys/kernel/mm/redhat_transparent_hugepage/enabled

Verify which path is in use on your system and update the disable-transparent-huge-pages.service file accordingly.

2

Reload systemd unit files

To reload the systemd unit files and make disable-transparent-huge-pages.service available for use, run the following command :

sudo systemctl daemon-reload
3

Start the service

Run:

sudo systemctl start disable-transparent-huge-pages

To verify that the relevant THP settings have changed, run the following command:

cat /sys/kernel/mm/transparent_hugepage/enabled && cat /sys/kernel/mm/transparent_hugepage/defrag

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

cat /sys/kernel/mm/redhat_transparent_hugepage/enabled && cat /sys/kernel/mm/redhat_transparent_hugepage/defrag

The output should resemble the following:

never
never
4

Configure your operating system to run it on boot

To ensure that this setting is applied each time the operating system starts, run the following command:

sudo systemctl enable disable-transparent-huge-pages
5

(Optional) Customize tuned or ktune profile

If you use tuned or ktune profiles on RHEL/ CentOS, you must also create a custom tuned profile.

1

Create the init.d script

Create the following file and save it 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 Hugepages
# Description:       Disable Linux Transparent Hugepages, 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 /sys/kernel/mm/transparent_hugepage/enabled > /dev/null && echo 'never' | tee /sys/kernel/mm/transparent_hugepage/defrag > /dev/null

    unset thp_path
    ;;
esac
2

Make the script executable

Run:

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

Run the script

Run:

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

To verify that the relevant THP settings have changed, run the following command:

cat /sys/kernel/mm/transparent_hugepage/enabled && cat /sys/kernel/mm/transparent_hugepage/defrag

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

cat /sys/kernel/mm/redhat_transparent_hugepage/enabled && cat /sys/kernel/mm/redhat_transparent_hugepage/defrag

The output should resemble the following:

never
never
4

Configure your operating system to run it on boot

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

DistributionCommand

Ubuntu and Debian

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

SUSE

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

Red Hat, CentOS, Amazon Linux, and derivatives

sudo chkconfig --add disable-transparent-hugepages
5

(Optional) Customize tuned or ktune profile

If you are using tuned or ktune profiles on RHEL/ CentOS, you must also create a custom tuned profile.

Using tuned and ktune

Important

If you use tuned or ktune, perform the steps in this section after creating the service file.

tuned and ktune are kernel tuning utilities that can affect the Transparent Hugepages setting on your system. If you use tuned or ktune on your RHEL or CentOS system while running mongod, you must create a custom tuned profile to ensure that THP stays disabled.

Red Hat/CentOS 6

1

Create a new profile.

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

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

Edit ktune.sh.

Edit /etc/tune-profiles/virtual-guest-no-thp/ktune.sh and change the set_transparent_hugepages setting to the following:

set_transparent_hugepages never
3

Enable the new profile.

Enable the new profile:

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

Red Hat/CentOS 7 and 8

1

Create a new profile.

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

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

Edit tuned.conf.

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

[main]
include=virtual-guest

[vm]
transparent_hugepages=never

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

3

Enable the new profile.

Enable the new profile:

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