Skip to content

DOCS-6767: production notes first pass #2568

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 1 commit into from
Closed

DOCS-6767: production notes first pass #2568

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
142 changes: 83 additions & 59 deletions source/administration/production-notes.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ Production Notes
:class: twocols

This page details system configurations that affect MongoDB,
especially in production.
especially when running in production.

.. include:: /includes/fact-mms-summary.rst

Expand All @@ -23,6 +23,11 @@ MongoDB Binaries
Supported Platforms
~~~~~~~~~~~~~~~~~~~

MongoDB provides builds for the following supported platforms. For
running **in production**, refer to the
:ref:`prod-notes-recommended-platforms` for operating system
recommendations.

.. include:: /includes/fact-platforms.rst

.. versionchanged:: 3.2
Expand All @@ -34,11 +39,12 @@ Supported Platforms
Recommended Platforms
~~~~~~~~~~~~~~~~~~~~~

We recommend the following operating systems for production use:
While MongoDB supports a variety of platorms, the following operating
systems are recommended for production use:

- Amazon Linux
- Debian 7.1
- Red Hat / CentOS 6.2+
- RHEL / CentOS 6.2+
- SLES 11+
- Ubuntu LTS 12.04
- Ubuntu LTS 14.04
Expand All @@ -51,7 +57,7 @@ Use the Latest Stable Packages

Be sure you have the latest stable release.

All releases are available on the `Downloads
All MongoDB releases are available on the `Downloads
<http://www.mongodb.org/downloads>`_ page. The `Downloads
<http://www.mongodb.org/downloads>`_ page is a good place to verify the
current stable release, even if you are installing via a package
Expand All @@ -62,17 +68,22 @@ Use 64-bit Builds

Always use 64-bit builds for production.

Although the 32-bit builds exist, they are **unsuitable** for
.. important::
.. include:: /includes/fact-deprecated-32bit.rst

Although the 32-bit builds exist for Linux and Windows, they are **unsuitable** for
production deployments. 32-bit builds also do **not** support the
WiredTiger storage engine. For more information, see the :ref:`32-bit
limitations page <faq-32-bit-limitations>`

.. note::
.. include:: /includes/fact-deprecated-32bit.rst

MongoDB ``dbPath``
------------------

The files in the :setting:`~storage.dbPath` directory must correspond
to the configured :term:`storage engine`. :program:`mongod` will not start if
:setting:`~storage.dbPath` contains data files created by a storage
engine other than the one specified by :option:`--storageEngine`.

.. versionchanged:: 3.2

As of MongoDB 3.2, MongoDB uses the :ref:`WiredTiger
Expand All @@ -84,10 +95,8 @@ MongoDB ``dbPath``
<storage-mmapv1>`, the storage engine available in previous versions
of MongoDB, and :ref:`WiredTiger <storage-wiredtiger>`.

The files in the :setting:`~storage.dbPath` directory must correspond
to the configured storage engine. :program:`mongod` will not start if
:setting:`~storage.dbPath` contains data files created by a storage
engine other than the one specified by :option:`--storageEngine`.
:program:`mongod` must possess read and write permissions for the specified
:setting:`~storage.dbPath`.

.. _prod-notes-concurrency:

Expand Down Expand Up @@ -122,7 +131,9 @@ readers and writers to the documents in a collection. Clients can read
documents while write operations are in progress, and multiple threads
can modify different documents in a collection at the same time.

.. seealso:: :ref:`prod-notes-ram`
.. seealso:: :ref:`prod-notes-ram` provides information about how WiredTiger
takes advantage of multiple CPU cores and how to improve operation
throughput.

Data Consistency
----------------
Expand All @@ -134,7 +145,7 @@ MongoDB uses *write ahead logging* to an on-disk :term:`journal`.
Journaling guarantees that MongoDB can quickly recover :doc:`write
operations </core/write-operations>` that were written to the journal
but not written to data files in cases where :program:`mongod`
terminated as a result of a crash or other serious failure.
terminated due to a crash or other serious failure.

Leave journaling enabled in order to ensure that :program:`mongod` will
be able to recover its data files and keep the data files in a valid
Expand All @@ -146,10 +157,12 @@ Read Concern

.. versionadded:: 3.2

.. include:: /includes/usage-read-concern-majority.rst
If using :readconcern:`"majority"` :doc:`read concern
</reference/read-concern>`, use :writeconcern:`{ w: "majority" }
<"majority">` :doc:`write concern </reference/write-concern>` for write
operations to ensure that a single thread can read its own writes.

For more information on read concern, see
:doc:`/reference/read-concern`.
.. include:: /includes/fact-enable-majority-readConcern.rst

Write Concern
~~~~~~~~~~~~~
Expand All @@ -173,7 +186,7 @@ MongoDB deployment should only be accessible to specific systems that
require access, such as application servers, monitoring services, and
other MongoDB components.

.. note::
.. important::
By default, :doc:`authorization </core/authorization>` is not
enabled, and :program:`mongod` assumes a trusted environment. Enable
:setting:`~security.authorization` mode as needed. For more
Expand Down Expand Up @@ -209,11 +222,11 @@ See :ref:`http-interface-security`.
Manage Connection Pool Sizes
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

To avoid overloading the connection resources of a single
:program:`mongod` or :program:`mongos` instance, ensure that clients
maintain reasonable connection pool sizes. Adjust the connection pool
size to suit your use case, beginning at 110-115% of the typical number
of concurrent database requests.
Avoid overloading the connection resources of a :program:`mongod` or
:program:`mongos` instance by adjusting the connection pool size to suit
your use case. Start at 110-115% of the typical number of current database
requests, and modify the connection pool size as needed. Refer to the
:ref:`connection-pool-options` for adjusting the connection pool size.

The :dbcommand:`connPoolStats` command returns information regarding
the number of open connections to the current database for
Expand All @@ -237,19 +250,22 @@ Allocate Sufficient RAM and CPU
MMAPv1
``````

Due to its concurrency model, the MMAPv1 storage engine does not
require many CPU cores . As such, increasing the number of cores can
help but does not provide significant return.
Due to its concurrency model, the :ref:`MMAPv1 <storage-mmapv1>` storage engine does not
require many CPU cores. As such, increasing the number of cores can
improve performance but does not provide significant return.

At a minimum, ensure that your :program:`mongod` or :program:`mongos`
has access to two real cores or one physical CPU.

Increasing the amount of RAM accessible to MongoDB may help reduce the
frequency of page faults.

WiredTiger
``````````

The WiredTiger storage engine is multithreaded and can take advantage
of many CPU cores. Specifically, the total number of active threads
(i.e. concurrent operations) relative to the number of CPUs can impact
The :ref:`WiredTiger <storage-wiredtiger>` storage engine is multithreaded and can take advantage
of additional CPU cores. Specifically, the total number of active threads
(i.e. concurrent operations) relative to the number of available CPUs can impact
performance:

- Throughput *increases* as the number of concurrent active operations
Expand All @@ -258,7 +274,7 @@ performance:
- Throughput *decreases* as the number of concurrent active operations
exceeds the number of CPUs by some threshold amount.

The threshold amount depends on your application. You can determine the
The threshold depends on your application. You can determine the
optimum number of concurrent active operations for your application by
experimenting and measuring throughput. The output from
:program:`mongostat` provides statistics on the number of active
Expand All @@ -274,6 +290,7 @@ Use Solid State Disks (SSDs)
MongoDB has good results and a good price-performance ratio with
SATA SSD (Solid State Disk).


Use SSD if available and economical. Spinning disks can be
performant, but SSDs' capacity for random I/O operations works well
with the update model of MMAPv1.
Expand Down Expand Up @@ -314,26 +331,33 @@ Configuring NUMA on Windows
```````````````````````````

On Windows, memory interleaving must be enabled through the machine's BIOS.
Please consult your system documentation for details.
Consult your system documentation for details.

Configuring NUMA on Linux
`````````````````````````

When running MongoDB on Linux, you may instead use the ``numactl``
command and start the MongoDB programs (:program:`mongod`, including
the :doc:`config servers </core/sharded-cluster-config-servers>`;
:program:`mongos`; or clients) in the following manner:
When running MongoDB on Linux, you should disable *zone reclaim* in the
``sysctl`` settings using one of the following commands:

.. code-block:: sh

echo 0 | sudo tee /proc/sys/vm/zone_reclaim_mode

.. code-block:: sh

numactl --interleave=all <path>
sudo sysctl -w vm.zone_reclaim_mode=0

where ``<path>`` is the path to the program you are starting. Then,
disable *zone reclaim* in the ``proc`` settings using the following command:
Then, you should use the ``numactl`` command to start the MongoDB programs
(:program:`mongod`, including the :doc:`config servers
</core/sharded-cluster-config-servers>`; :program:`mongos`; and clients) in
the following manner:

.. code-block:: sh

echo 0 > /proc/sys/vm/zone_reclaim_mode
numactl --interleave=all <path> <options>

where ``<path>`` is the path to the program you are starting, and ``<options>``
are any optional arguments to pass to the program.

To fully disable NUMA behavior, you must perform both operations. For more
information, see the `Documentation for /proc/sys/vm/*
Expand All @@ -356,7 +380,7 @@ requires extra swap space due to commitment limits. For details,
see :ref:`MongoDB on Windows <production-windows-pagefile>`.

For the WiredTiger storage engine, given sufficient memory pressure,
WiredTiger may store data in swap space .
WiredTiger may store data in swap space.

RAID
````
Expand Down Expand Up @@ -501,7 +525,7 @@ using EXT4 with WiredTiger.
Recommended Configuration
`````````````````````````

For the MMAPv1 storage engine and the WiredTiger storage engines,
For the WiredTiger and MMAPv1 storage engines,
consider the following recommendations:

- Turn off ``atime`` for the storage volume containing the :term:`database
Expand Down Expand Up @@ -538,7 +562,7 @@ For the MMAPv1 storage engine:
<device>`` to change the readahead settings. Refer to your specific
operating system manual for more information.

For all MongoDB deployments:
For **all** MongoDB deployments:

- Use the Network Time Protocol (NTP) to synchronize time among
your hosts. This is especially important in sharded clusters.
Expand Down Expand Up @@ -591,6 +615,12 @@ This procedure is neither exact nor exhaustive: many symbols used by
MongoDB on Windows
~~~~~~~~~~~~~~~~~~

MongoDB 3.0 Using WiredTiger
````````````````````````````

For MongoDB instances using the WiredTiger storage engine, performance
on Windows is comparable to performance on Linux.

MongoDB Using MMAPv1
````````````````````

Expand Down Expand Up @@ -633,12 +663,6 @@ accommodate Windows' commitment rules during peak database use.
result in transient overcommitment situations that may lead to
abrupt server shutdown with a VirtualProtect error 1455.

MongoDB 3.0 Using WiredTiger
````````````````````````````

For MongoDB instances using the WiredTiger storage engine, performance
on Windows is comparable to performance on Linux.

MongoDB on Virtual Environments
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Expand Down Expand Up @@ -693,18 +717,13 @@ should set ``tcp_keepalive_time`` to 120 to ameliorate this problem.
VMWare
``````

MongoDB is compatible with VMWare.
.. include:: /includes/extracts/vm-memory-considerations-vmware.rst

As some users have run into issues with VMWare's memory overcommit
feature, you should disable the feature.

Further, MongoDB is known to run poorly with VMWare's balloon driver
(``vmmemctl``), so you should disable this as well. VMWare uses the
balloon driver to reduce physical memory usage on the host hardware by
allowing the hypervisor to swap to disk while hiding this fact from
the guest, which continues to see the same amount of (virtual)
physical memory. This interferes with MongoDB's memory management,
and you are likely to experience significant performance degradation.
Disable VMWare's Migration with vMotion ("live migration"). The live migration of
a virtual machine can cause performance problems and affect
:doc:`replica set </core/replica-set-high-availability>` and
:doc:`sharded cluster high availability
</core/sharded-cluster-high-availability>` mechanisms.

It is possible to clone a virtual machine running MongoDB.
You might use this function to
Expand All @@ -713,6 +732,11 @@ set. If you clone a VM with journaling enabled, the clone snapshot will
be valid. If not using journaling, first stop :program:`mongod`,
then clone the VM, and finally, restart :program:`mongod`.

KVM
```

.. include:: /includes/extracts/vm-memory-considerations-kvm.rst

Performance Monitoring
----------------------

Expand Down
28 changes: 28 additions & 0 deletions source/includes/extracts-production-notes-base.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,28 @@
ref: _virtual-machine-memory-considerations
content: |
MongoDB is compatible with {{software}}.

{{software}} supports *memory overcommitment*, where you can assign more memory
to your virtual machines than the physical machine has available. When
memory is overcommitted, the hypervisor reallocates memory between the
virtual machines. {{software}}'s balloon driver {{balloonDriverLiteral}} reclaims the
pages that are considered least valuable. The balloon driver resides
inside the guest operating system. When the balloon driver expands,
it may induce the guest operating system to reclaim memory from guest
applications, which can interfere with MongoDB's memory management and
affect MongoDB's performance.

You can disable the balloon driver and {{software}}'s memory overcommitment
feature to mitigate these problems. However, disabling the balloon driver
can cause the hypervisor to use its swap, as there is no other available
mechanism to perform the memory reclamation. Accessing data in swap
is much slower than accessing data in memory, which can in turn affect
performance. Instead of disabling the balloon driver and memory
overcommitment features, map and reserve the full amount of memory for
the virtual machine running MongoDB. This ensures that the balloon
will not be inflated in the local operating system if there is memory
pressure in the hypervisor due to an overcommitted configuration.

When using MongoDB with {{software}}, ensure that the CPU reservation does not
exceed more than 2 virtual CPUs per physical core.
...
16 changes: 16 additions & 0 deletions source/includes/extracts-production-notes.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,16 @@
ref: vm-memory-considerations-vmware
source:
file: extracts-production-notes-base.yaml
ref: _virtual-machine-memory-considerations
replacement:
software: "VMWare"
balloonDriverLiteral: "(``vmmemctl``)"
---
ref: vm-memory-considerations-kvm
source:
file: extracts-production-notes-base.yaml
ref: _virtual-machine-memory-considerations
replacement:
software: "KVM"
balloonDriverLiteral: ""
...
4 changes: 2 additions & 2 deletions source/includes/extracts-wired-tiger-base.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -30,8 +30,8 @@ content: |
decrease WiredTiger cache size.

The default WiredTiger cache size value assumes that there is a
single :program:`mongod` instance per node. If a single node
contains multiple instances, then you should decrease the setting to
single :program:`mongod` instance per machine. If a single machine
contains multiple MongoDB instances, then you should decrease the setting to
accommodate the other :program:`mongod`
instances.

Expand Down
2 changes: 2 additions & 0 deletions source/reference/connection-string.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -185,6 +185,8 @@ Connection Options
timeout, though different drivers might vary. See the
:doc:`driver </applications/drivers>` documentation.

.. _connection-pool-options:

Connection Pool Options
~~~~~~~~~~~~~~~~~~~~~~~

Expand Down