DOCS-491 editing and organization

Sam Kleinman · Sam Kleinman · commit 5395dd089582 · 2013-01-05T10:17:39.000-05:00
diff --git a/source/faq/diagnostics.txt b/source/faq/diagnostics.txt
@@ -79,3 +79,123 @@ If your replica set or shard cluster experiences keepalive-related
 issues, you must must alter the ``tcp_keepalive_time`` value on all
 machines hosting MongoDB processes. This includes all machines hosting
 :program:`mongos` or :program:`mongod` servers.
+
+Do I need to configure swap space?
+----------------------------------
+
+Always configure systems to have swap space. Without swap, your system
+may not be reliant in some situations with extreme memory constrains,
+memory leaks, or multiple programs using the same memory.  Think of
+the swap space as something like a steam release valve that allows the
+system to release extra pressure without affecting the overall
+functioning of the system.
+
+Nevertheless, systems running MongoDB *do not* need swap for routine
+operation. Database files are :ref:`memory-mapped
+<faq-storage-memory-mapped-files>` and should constitute most of your
+MongoDB memory use. Therefore, it is unlikely that :program:`mongod`
+will ever use any swap space in normal operation. The operating system
+will release memory from the memory mapped files without needing
+swap and MongoDB can write data to the data files without needing the swap
+system.
+
+.. _faq-fundamentals-working-set:
+
+Must my working set size fit RAM?
+---------------------------------
+
+Your working set should stay in memory to achieve good performance.
+Otherwise many random disk IO's will occur, and unless you are using
+SSD, this can be quite slow.
+
+One area to watch specifically in managing the size of your working set
+is index access patterns. If you are inserting into indexes at random
+locations (as would happen with id's that are randomly
+generated by hashes), you will continually be updating the whole index.
+If instead you are able to create your id's in approximately ascending
+order (for example, day concatenated with a random id), all the updates
+will occur at the right side of the b-tree and the working set size for
+index pages will be much smaller.
+
+It is fine if databases and thus virtual size are much larger than RAM.
+
+.. todo Commenting out for now:
+
+   .. _faq-fundamentals-working-set-size:
+
+   How can I measure working set size?
+   -----------------------------------
+
+   Measuring working set size can be difficult; even if it is much
+   smaller than total RAM. If the database is much larger than RAM in
+   total, all memory will be indicated as in use for the cache. Thus you
+   need a different way to estimate the working set size.
+
+   One technique is to use the `eatmem.cpp
+   <https://github.com/mongodb/mongo-snippets/blob/master/cpp/eatmem.cpp>`_.
+   utility, which reserves a certain amount of system memory for itself.
+   You can run the utility with a certain amount specified and see if
+   the server continues to perform well. If not, the working set is
+   larger than the total RAM minus the consumed RAM. The test will eject
+   some data from the file system cache, which might take time to page
+   back in after the utility is terminated.
+
+   Running eatmem.cpp continuously with a small percentage of total RAM,
+   such as 20%, is a good technique to get an early warning if memory is
+   too low. If disk I/O activity increases significantly, terminate
+   eatmem.cpp to mitigate the problem for the moment until further steps
+   can be taken.
+
+   In :term:`replica sets <replica set>`, if one server is underpowered
+   the eatmem.cpp utility could help as an early warning mechanism for
+   server capacity. Of course, the server must be receiving
+   representative traffic to get an indication.
+
+How do I calculate how much RAM I need for my application?
+----------------------------------------------------------
+
+.. todo Improve this FAQ
+
+The amount of RAM you need depends on several factors, including but not
+limited to:
+
+- The relationship between :doc:`database storage </faq/storage>` and working set.
+
+- The operating system's cache strategy for LRU (Least Recently Used)
+
+- The impact of :doc:`journaling </administration/journaling>`
+
+- The number or rate of page faults and other MMS gauges to detect when
+  you need more RAM
+
+MongoDB defers to the operating system when loading data into memory
+from disk. It simply :ref:`memory maps <faq-storage-memory-mapped-files>` all
+its data files and relies on the operating system to cache data. The OS
+typically evicts the least-recently-used data from RAM when it runs low
+on memory. For example if clients access  indexes more frequently than
+documents, then indexes will more likely stay in RAM, but it depends on
+your particular usage.
+
+To calculate how much RAM you need, you must calculate your working set
+size, or the portion of your data that clients use most often. This
+depends on your access patterns, what indexes you have, and the size of
+your documents.
+
+If page faults are infrequent, your
+working set fits in RAM. If fault rates rise higher than that, you risk
+performance degradation. This is less critical with SSD drives than
+with spinning disks.
+
+How do I read memory statistics in the UNIX ``top`` command
+-----------------------------------------------------------
+
+Because :program:`mongod` uses :ref:`memory-mapped files
+<faq-storage-memory-mapped-files>`, the memory statistics in ``top``
+require interpretation in a special way. On a large database, ``VSIZE``
+(virtual bytes) tends to be the size of the entire database. If the
+:program:`mongod` doesn't have other processes running, ``RSIZE``
+(resident bytes) is the total memory of the machine, as this counts
+file system cache contents.
+
+For Linux systems, use the ``vmstat`` command to help determine how
+the system uses memory. On OS X systems use ``vm_stat``.
diff --git a/source/faq/fundamentals.txt b/source/faq/fundamentals.txt
@@ -4,7 +4,8 @@ FAQ: MongoDB Fundamentals
 
 .. default-domain:: mongodb
 
-This document answers basic questions about MongoDB.
+This document addresses basic high level questions about MongoDB and
+it's use.
 
 If you don't find the answer you're looking for, check
 the :doc:`complete list of FAQs </faq>` or post your question to the
@@ -17,7 +18,7 @@ the :doc:`complete list of FAQs </faq>` or post your question to the
 What kind of database is MongoDB?
 ---------------------------------
 
-MongoDB is :term:`document`-oriented DBMS. Think of MySQL but with
+MongoDB is :term:`document`\-oriented DBMS. Think of MySQL but with
 :term:`JSON`-like objects comprising the data model, rather than RDBMS
 tables. Significantly, MongoDB supports neither joins nor transactions.
 However, it features secondary indexes, an expressive query language,
@@ -145,123 +146,6 @@ as it can, swapping to disk as needed. Deployments with enough memory
 to fit the application's working data set in RAM will achieve the best
 performance.
 
-Do I need a swap space?
------------------------
-
-You should always have a swap space in case you run into extreme memory
-constraints, memory leaks, or another program stealing a lot of memory.
-Think of the swap space as something like a steam release valve which
-allows excess pressure to release without blowing the system up.
-
-But you *do not* need swap for routine use. Database files are
-:ref:`memory-mapped <faq-storage-memory-mapped-files>` and should
-constitute most of your MongoDB memory use. Therefore, it is unlikely
-that :program:`mongod` will ever use any swap space. The memory mapped
-files can simply be released from memory without going to swap or can be
-written back to the database files without needing to be swapped out to
-disk, as they are already backed by files.
-
-.. _faq-fundamentals-working-set:
-
-Must my working set size fit RAM?
----------------------------------
-
-Your working set should stay in memory to achieve good performance.
-Otherwise many random disk IO's will occur, and unless you are using
-SSD, this can be quite slow.
-
-One area to watch specifically in managing the size of your working set
-is index access patterns. If you are inserting into indexes at random
-locations (as would happen with id's that are randomly
-generated by hashes), you will continually be updating the whole index.
-If instead you are able to create your id's in approximately ascending
-order (for example, day concatenated with a random id), all the updates
-will occur at the right side of the b-tree and the working set size for
-index pages will be much smaller.
-
-It is fine if databases and thus virtual size are much larger than RAM.
-
-.. todo Commenting out for now:
-
-   .. _faq-fundamentals-working-set-size:
-
-   How can I measure working set size?
-   -----------------------------------
-
-   Measuring working set size can be difficult; even if it is much
-   smaller than total RAM. If the database is much larger than RAM in
-   total, all memory will be indicated as in use for the cache. Thus you
-   need a different way to estimate the working set size.
-
-   One technique is to use the `eatmem.cpp
-   <https://github.com/mongodb/mongo-snippets/blob/master/cpp/eatmem.cpp>`_.
-   utility, which reserves a certain amount of system memory for itself.
-   You can run the utility with a certain amount specified and see if
-   the server continues to perform well. If not, the working set is
-   larger than the total RAM minus the consumed RAM. The test will eject
-   some data from the file system cache, which might take time to page
-   back in after the utility is terminated.
-
-   Running eatmem.cpp continuously with a small percentage of total RAM,
-   such as 20%, is a good technique to get an early warning if memory is
-   too low. If disk I/O activity increases significantly, terminate
-   eatmem.cpp to mitigate the problem for the moment until further steps
-   can be taken.
-
-   In :term:`replica sets <replica set>`, if one server is underpowered
-   the eatmem.cpp utility could help as an early warning mechanism for
-   server capacity. Of course, the server must be receiving
-   representative traffic to get an indication.
-
-How do I calculate how much RAM I need for my application?
-----------------------------------------------------------
-
-.. todo Improve this FAQ
-
-The amount of RAM you need depends on several factors, including but not
-limited to:
-
-- The relationship between :doc:`database storage </faq/storage>` and working set.
-
-- The operating system's cache strategy for LRU (Least Recently Used)
-
-- The impact of :doc:`journaling </administration/journaling>`
-
-- The number or rate of page faults and other MMS gauges to detect when
-  you need more RAM
-
-MongoDB makes no choices regarding what data is loaded into memory from
-disk. It simply :ref:`memory maps <faq-storage-memory-mapped-files>` all
-its data files and relies on the operating system to cache data. The OS
-typically evicts the least-recently-used data from RAM when it runs low
-on memory. For example if indexes are accessed more frequently than
-documents then indexes will more likely stay in RAM, but it depends on
-your particular usage.
-
-To calculate how much RAM you need, you must calculate your working set
-size, i.e., the portion of your data that is frequently accessed. This
-depends on your access patterns, what indexes you have, and the size of
-your documents. To calculate working set size, see :ref:`faq-fundamentals-working-set`.
-
-If page faults are infrequent, your
-working set fits in RAM. If fault rates rise higher than that, you risk
-performance degradation. This is less critical with SSD drives than
-with spinning disks.
-
-How do I read memory statistics in the UNIX ``top`` command
------------------------------------------------------------
-
-Because :program:`mongod` uses :ref:`memory-mapped files
-<faq-storage-memory-mapped-files>`, the memory statistics in ``top``
-require interpretation in a special way. On a large database, ``VSIZE``
-(virtual bytes) tends to be the size of the entire database. If the
-:program:`mongod` doesn't have other processes running, ``RSIZE``
-(resident bytes) is the total memory of the machine, as this counts
-file system cache contents.
-
-The ``vmstat`` command is also useful for determining
-memory use. On Macintosh computers, the command is ``vm_stat``.
-
 How do I configure the cache size?
 ----------------------------------
 
