Disable Transparent Hugepages (THP) for Self-Managed Deployments
On this page
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.
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:
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.
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/disabled && 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
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
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
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:
Distribution | Command | |
|---|---|---|
Ubuntu and Debian | | |
SUSE | | |
Red Hat, CentOS, Amazon Linux, and derivatives | |
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.