Skip to content

Commit c338cfe

Browse files
author
Michael Paik
committed
DOCS-2131
DOCS-2131 ProdNotes Edits
1 parent 0335a4c commit c338cfe

File tree

6 files changed

+191
-2
lines changed

6 files changed

+191
-2
lines changed

‎source/administration/production-notes.txt

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -457,8 +457,9 @@ consider the following recommendations:
457457
MongoDB when under heavy use and can produce errors and lead to
458458
failed connections to MongoDB processes and loss of service.
459459

460-
- Disable ``transparent huge pages`` as MongoDB performs
461-
better with normal (4096 bytes) virtual memory pages.
460+
- Disable Transparent Huge Pages, as MongoDB performs better with
461+
normal (4096 bytes) virtual memory pages. See :doc:`Transparent Huge
462+
Pages Settings </reference/transparent-huge-pages>`.
462463

463464
- Disable NUMA in your BIOS. If that is not possible, see
464465
:ref:`MongoDB on NUMA Hardware <production-numa>`.

‎source/includes/steps-disable-thp-in-grub.yaml

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
title: Edit ``grub`` configuration file
2+
stepnum: 1
3+
ref: edit-grub
4+
pre: |
5+
If your system uses ``grub-legacy``, you can edit the configuration
6+
file directly.
7+
action:
8+
- pre: |
9+
Add ``transparent_hugepage=never`` to the ``kernel`` line of your ``/etc/grub.conf`` or ``/boot/grub/grub.conf`` as ``root``:
10+
language: cfg
11+
code: |
12+
kernel <kernel path> <kernel options> transparent_hugepage=never
13+
- pre: |
14+
If your system uses ``grub2``, you can edit the ``GRUB_CMDLINE_LINUX_DEFAULT`` value in ``/etc/default/grub`` as ``root`` to add ``transparent_hugepage=never`` to any existing kernel options:
15+
language: cfg
16+
code: |
17+
GRUB_CMDLINE_LINUX_DEFAULT="<kernel options> transparent_hugepage=never"
18+
- pre: |
19+
and subsequently run
20+
language: cfg
21+
code: |
22+
grub2-mkconfig -o <grub2 configuration file location>
23+
- post: |
24+
as ``root``.
25+
26+
See your operating system's documentation for details on the
27+
precise location of the ``grub-legacy`` or ``grub2`` configuration file.
28+
---
29+
title: Reboot the system.
30+
stepnum: 2
31+
ref: reboot
32+
...

‎source/includes/steps-disable-thp-in-ktune.yaml

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
title: Create a new profile
2+
stepnum: 1
3+
ref: copy-profile
4+
action:
5+
- pre: |
6+
If necessary, create a new profile from an existing default
7+
profile by copying the relevant directory. In the example we use
8+
the ``default`` profile as the base and call our new profile
9+
``no-thp``, but you may start with any profile and name the
10+
new profile whatever you wish.
11+
language: sh
12+
code: |
13+
cp -r /etc/tune-profiles/default /etc/tune-profiles/no-thp
14+
post: |
15+
You may also opt to edit an existing profile.
16+
---
17+
title: Edit ``ktune.sh``
18+
stepnum: 2
19+
ref: edit-ktune
20+
action:
21+
- pre: |
22+
Locate the ``ktune.sh`` file in the new profile directory
23+
(``/etc/tune-profiles/no-thp/ktune.sh`` in this case) and add
24+
the following:
25+
language: cfg
26+
code: |
27+
set_transparent_hugepages never
28+
post: |
29+
to the ``start()`` block of the file, before the ``return 0``
30+
statement.
31+
---
32+
title: Enable the new profile
33+
stepnum: 3
34+
ref: enable-profile
35+
action:
36+
- pre: |
37+
Finally, enable the new profile by issuing:
38+
language: sh
39+
code: |
40+
tune-adm profile no-thp
41+
post: |
42+
where ``no-thp`` should be replaced with the name of the profile
43+
you defined, if it is different.
44+
45+
.. warning::
46+
47+
If you are using ``tuned`` and ``ktune`` and do not wish to
48+
disable them, you **must** use this method, or ``tuned`` may
49+
override THP settings configured using either of the other
50+
two methods.
51+
...

‎source/includes/steps-disable-thp-in-rc.local.yaml

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
title: Edit ``/etc/rc.local``
2+
stepnum: 1
3+
ref: edit-rclocal
4+
pre: |
5+
``/etc/rc.local`` is a user-configurable script that is run at the end of
6+
post-boot system initialization. Add the following script lines to the file
7+
as ``root`` to disable THP upon each boot.
8+
action:
9+
- language: sh
10+
code: |
11+
if test -f /sys/kernel/mm/transparent_hugepage/khugepaged/defrag; then
12+
echo 0 > /sys/kernel/mm/transparent_hugepage/khugepaged/defrag
13+
fi
14+
if test -f /sys/kernel/mm/transparent_hugepage/defrag; then
15+
echo never > /sys/kernel/mm/transparent_hugepage/defrag
16+
fi
17+
if test -f /sys/kernel/mm/transparent_hugepage/enabled; then
18+
echo never > /sys/kernel/mm/transparent_hugepage/enabled
19+
fi
20+
- post: |
21+
These lines should immediately precede ``exit 0``, which should
22+
already be the last line in the file. Note that on Red Hat
23+
Enterprise Linux, CentOS, and potentially other Red Hat-based
24+
derivatives, ``transparent_hugepage`` in the paths in the script
25+
should be replaced by ``redhat_transparent_hugepages``.
26+
---
27+
title: Apply the changes to ``/etc/rc.local`` as ``root``
28+
stepnum: 2
29+
ref: source
30+
action:
31+
- language: sh
32+
code: |
33+
source /etc/rc.local
34+
...

‎source/includes/toc-administration-reference.yaml

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,11 @@ description: |
44
considerations and optimal configurations for systems that run
55
MongoDB deployments.
66
---
7+
file: /reference/transparent-huge-pages
8+
description: |
9+
Describes Transparent Huge Pages (THP) and provides detailed
10+
instructions on disabling them.
11+
---
712
file: /reference/system-collections
813
description: |
914
Introduces the internal collections that MongoDB uses to track

‎source/reference/transparent-huge-pages.txt

Lines changed: 66 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,66 @@
1+
=====================================
2+
Transparent Huge Pages (THP) Settings
3+
=====================================
4+
5+
.. default-domain:: mongodb
6+
7+
Transparent Huge Pages (THP) is a Linux memory management kernel
8+
module used to reduce the overhead of Translation Lookaside Buffer
9+
(TLB) lookups on machines with large amounts of memory, and therefore
10+
a large number of memory pages. In effect, it presents system memory
11+
as a smaller number of much larger pages rather than as a larger
12+
number of 4096-byte pages.
13+
14+
However, THP is known to perform poorly under database workloads,
15+
which tend to have sparse rather than contiguous memory access
16+
patterns. You must disable THP on Linux machines used to run MongoDB
17+
instances to ensure best performance.
18+
19+
There are three ways to disable Transparent Huge Pages on Linux.
20+
21+
In Boot-Time Configuration (Preferred)
22+
--------------------------------------
23+
24+
.. include:: /includes/steps/disable-thp-in-grub.rst
25+
26+
Using ``tuned`` and ``ktune`` (Necessary if you use ``tuned``)
27+
--------------------------------------------------------------
28+
29+
``tuned`` and ``ktune`` are dynamic kernel tuning tools that act in
30+
accordance with policies set by the system administrator. One of the
31+
settings available to ``tuned`` and ``ktune`` is whether or not to use
32+
THP.
33+
34+
To disable transparent hugepages, you need to edit or create a new
35+
profile that sets THP to ``never``.
36+
37+
.. include:: /includes/steps/disable-thp-in-ktune.rst
38+
39+
In ``/etc/rc.local`` (Alternate)
40+
--------------------------------
41+
42+
.. include:: /includes/steps/disable-thp-in-rc.local.rst
43+
44+
Test Your Changes
45+
-----------------
46+
47+
Whichever of the three methods you use, you can check the status of THP support by issuing the command:
48+
49+
.. code:: sh
50+
51+
cat /sys/mm/kernel/mm/transparent_hugepage/enabled
52+
53+
or
54+
55+
.. code:: sh
56+
57+
cat /sys/mm/kernel/mm/redhat_transparent_hugepage/enabled
58+
59+
on Red Hat Enterprise Linux, CentOS, and potentially other Red
60+
Hat-based derivatives.
61+
62+
Correct output resembles:
63+
64+
.. code:: sh
65+
66+
always madvise [never]

0 commit comments

Comments
 (0)