Configuration, Maintenance, and Analysis

This section describe routine management operations, including configuration and performance analysis.

Use Database Commands – The MongoDB command interface provides access to all non CRUD database operations. Fetching server stats, initializing a replica set, and running a map-reduce job are all accomplished with commands.

Database Command Form – You specify a command first by constructing a standard BSON document whose first key is the name of the command. For example, specify the isMaster command using the following BSON document:

{ isMaster: 1 }

Issue Commands – The mongo shell provides a helper method for running commands called db.runCommand(). The following operation in mongo runs the above command

db.runCommand( { isMaster: 1 } )

Many drivers provide an equivalent for the db.runCommand() method. Internally, running commands with db.runCommand() is equivalent to a special query against the $cmd collection.

Many common commands have their own shell helpers or wrappers in the mongo shell and drivers, such as the db.isMaster() method in the mongo JavaScript shell.

Admin Database Commands – You must run some commands on the admin database. Normally, these operations resemble the followings

use admin

db.runCommand( {buildInfo: 1} )

However, there’s also a command helper that automatically runs the command in the context of the admin database:

db._adminCommand( {buildInfo: 1} )

Command Responses – All commands return, at minimum, a document with an ok field indicating whether the command has succeeded:

{ ‘ok’: 1 }

Failed commands return the ok field with a value of 0.

Manage mongod Processes – MongoDB runs as a standard program. You can start MongoDB from a command line by issuing the mongod command and specifying options. MongoDB can also run as a Windows service.

The following examples assume the directory containing the mongod process is in your system paths. The mongod process is the primary database process that runs on an individual server. mongos provides a coherent MongoDB interface equivalent to a mongod from the perspective of a client. The mongo binary provides the administrative shell.

Start mongod Processes – By default, MongoDB stores data in the /data/db directory. On Windows, MongoDB stores data in C:\data\db. On all platforms, MongoDB listens for connections from clients on port 27017. To start MongoDB using all defaults, issue the following command at the system shell

mongod

Specify a Data Directory – If you want mongod to store data files at a path other than /data/db you can specify a dbPath. The dbPath must exist before you start mongod. If it does not exist, create the directory and the permissions so that mongod can read and write data to this path. To specify a dbPath for mongod to use as a data directory, use the –dbpath option. The following invocation will start a mongod instance and store data in the /srv/mongodb path

mongod –dbpath /srv/mongodb/

Specify a TCP Port – Only a single process can listen for connections on a network interface at a time. If you run multiple mongod processes on a single machine, or have other processes that must use this port, you must assign each a different port to listen on for client connections. To specify a port to mongod, use the –port option on the command line. The following command starts mongod listening on port 12345

mongod –port 12345

Use the default port number when possible, to avoid confusion.

Start mongod as a Daemon – To run a mongod process as a daemon (i.e. fork), and write its output to a log file, use the –fork and –logpath options. You must create the log directory; however, mongod will create the log file if it does not exist. The following command starts mongod as a daemon and records log output to /var/log/mongodb.log.

mongod –fork –logpath /var/log/mongodb.log

Stop mongod Processes – In a clean shutdown a mongod completes all pending operations, flushes all data to data files, and closes all data files. Other shutdowns are unclean and can compromise the validity the data files. To ensure a clean shutdown, always shutdown mongod instances using one of the following methods

Use shutdownServer() – Shut down the mongod from the mongo shell using the db.shutdownServer() method as follows:

use admin

db.shutdownServer()

Calling the same method from a control script accomplishes the same result.

For systems with authorization enabled, users may only issue db.shutdownServer() when authenticated to the admin database or via the localhost interface on systems without authentication enabled.

Use –shutdown – From the Linux command line, shut down the mongod using the –shutdown option in the following command:

mongod –shutdown

Use CTRL-C – When running the mongod instance in interactive mode (i.e. without –fork), issue Control-C to perform a clean shutdown.

Use kill – From the Linux command line, shut down a specific mongod instance using the following command:

kill <mongod process ID>

Never use kill -9 (i.e. SIGKILL) to terminate a mongod instance.

Stop a Replica Set

Procedure – If the mongod is the primary in a replica set, the shutdown process for these mongod instances has the following steps:

Check how up-to-date the secondaries are.
If no secondary is within 10 seconds of the primary, mongod will return a message that it will not shut down. You can pass the shutdown command a timeoutSecs argument to wait for a secondary to catch up.
If there is a secondary within 10 seconds of the primary, the primary will step down and wait for the secondary to catch up.
After 60 seconds or once the secondary has caught up, the primary will shut down.

Force Replica Set Shutdown – If there is no up-to-date secondary and you want the primary to shut down, issue the shutdown command with the force argument, as in the following mongo shell operation

db.adminCommand({shutdown : 1, force : true})

To keep checking the secondaries for a specified number of seconds if none are immediately up-to-date, issue shutdown with the timeoutSecs argument. MongoDB will keep checking the secondaries for the specified number of seconds if none are immediately up-to-date. If any of the secondaries catch up within the allotted time, the primary will shut down. If no secondaries catch up, it will not shut down. The following command issues shutdown with timeoutSecs set to 5

db.adminCommand({shutdown : 1, timeoutSecs : 5})

Alternately you can use the timeoutSecs argument with the db.shutdownServer() method:

db.shutdownServer({timeoutSecs : 5})

Terminate Running Operations – MongoDB provides two facilitates to terminate running operations: maxTimeMS() and db.killOp(). Use these operations as needed to control the behavior of operations in a MongoDB deployment.

Available Procedures

maxTimeMS – It is new in version 2.6. The maxTimeMS() method sets a time limit for an operation. When the operation reaches the specified time limit, MongoDB interrupts the operation at the next interrupt point.

Terminate a Query – From the mongo shell, use the following method to set a time limit of 30 milliseconds for this query

db.location.find( { “town”: { “$regex”: “(Pine Lumber)”,

“$options”: ‘i’ } } ).maxTimeMS(30)

Terminate a Command – Consider a potentially long running operation using distinct to return each distinct“collection“ field that has a city key

db.runCommand( { distinct: “collection”,

key: “city” } )

You can add the maxTimeMS field to the command document to set a time limit of 30 milliseconds for the operation

db.runCommand( { distinct: “collection”,

key: “city”,

maxTimeMS: 45 } )

db.getLastError() and db.getLastErrorObj() will return errors for interrupted options:

{ “n” : 0,

“connectionId” : 1,

“err” : “operation exceeded time limit”,

“ok” : 1 }

killOp – The db.killOp() method interrupts a running operation at the next interrupt point. db.killOp() identifies the target operation by operation ID.

db.killOp(<opId>)

Analyze Performance of Database Operations – The database profiler collects fine grained data about MongoDB write operations, cursors, database commands on a running mongod instance. You can enable profiling on a per-database or per-instance basis. The profiling level is also configurable when enabling profiling. The database profiler writes all the data it collects to the system.profile collection, which is a capped collection.

Profiling Levels – The following profiling levels are available:

0 – the profiler is off, does not collect any data. mongod always writes operations longer than the slowOpThresholdMs threshold to its log.

1 – collects profiling data for slow operations only. By default slow operations are those slower than 100 milliseconds. You can modify the threshold for “slow” operations with the slowOpThresholdMs runtime option or the setParameter command.
2 – collects profiling data for all database operations.

Enable Database Profiling and Set the Profiling Level – You can enable database profiling from the mongo shell or through a driver using the profile command. This section will describe how to do so from the mongo shell. See your driver documentation if you want to control the profiler from within your application.

When you enable profiling, you also set the profiling level. The profiler records data in the system.profile collection. MongoDB creates the system.profile collection in a database after you enable profiling for that database.

To enable profiling and set the profiling level, use the db.setProfilingLevel() helper in the mongo shell, passing the profiling level as a parameter. For example, to enable profiling for all database operations, consider the following operation in the mongo shell:

db.setProfilingLevel(2)

The shell returns a document showing the previous level of profiling. The “ok” : 1 key-value pair indicates the operation succeeded:

{ “was” : 0, “slowms” : 100, “ok” : 1 }

Specify the Threshold for Slow Operations – The threshold for slow operations applies to the entire mongod instance. When you change the threshold, you change it for all databases on the instance. Changing the slow operation threshold for the database profiler also affects the profiling subsystem’s slow operation threshold for the entire mongod instance. Always set the threshold to the highest useful value.

By default the slow operation threshold is 100 milliseconds. Databases with a profiling level of 1 will log operations slower than 100 milliseconds. To change the threshold, pass two parameters to the db.setProfilingLevel() helper in the mongo shell. The first parameter sets the profiling level for the current database, and the second sets the default slow operation threshold for the entire mongod instance.

For example, the following command sets the profiling level for the current database to 0, which disables profiling, and sets the slow-operation threshold for the mongod instance to 20 milliseconds. Any database on the instance with a profiling level of 1 will use this threshold

db.setProfilingLevel(0,20)

Check Profiling Level – To view the profiling level, issue the following from the mongo shell:

db.getProfilingStatus()

The shell returns a document similar to the following:

{ “was” : 0, “slowms” : 100 }

The was field indicates the current level of profiling. The slowms field indicates how long an operation must exist in milliseconds for an operation to pass the “slow” threshold. MongoDB will log operations that take longer than the threshold if the profiling level is 1. This document returns the profiling level in the was field. To return only the profiling level, use the db.getProfilingLevel() helper in the mongo as in the following:

db.getProfilingLevel()

Disable Profiling – To disable profiling, use the following helper in the mongo shell:

db.setProfilingLevel(0)

Enable Profiling for an Entire mongod Instance – For development purposes in testing environments, you can enable database profiling for an entire mongod instance. The profiling level applies to all databases provided by the mongod instance. To enable profiling for a mongod instance, pass the following parameters to mongod at startup or within the configuration file:

mongod –profile=1 –slowms=15

This sets the profiling level to 1, which collects profiling data for slow operations only, and defines slow operations as those that last longer than 15 milliseconds.

Database Profiling and Sharding – You cannot enable profiling on a mongos instance. To enable profiling in a shard cluster, you must enable profiling for each mongod instance in the cluster.

View Profiler Data – The database profiler logs information about database operations in the system.profile collection. To view profiling information, query the system.profile collection.

Example Profiler Data Queries – This section displays example queries to the system.profile collection. To return the most recent 10 log entries in the system.profile collection, run a query similar to the following:

db.system.profile.find().limit(10).sort( { ts : -1 } ).pretty()

To return all operations except command operations ($cmd), run a query similar to the following:

db.system.profile.find( { op: { $ne : ‘command’ } } ).pretty()

To return operations for a particular collection, run a query similar to the following. This example returns operations in the mydb database’s test collection:

db.system.profile.find( { ns : ‘mydb.test’ } ).pretty()

To return operations slower than 5 milliseconds, run a query similar to the following:

db.system.profile.find( { millis : { $gt : 5 } } ).pretty()

To return information from a certain time range, run a query similar to the following:

db.system.profile.find(

{

ts : {

$gt : new ISODate(“2012-12-09T03:00:00Z”) ,

$lt : new ISODate(“2012-12-09T03:40:00Z”)

}

).pretty()

The following example looks at the time range, suppresses the user field from the output to make it easier to read, and sorts the results by how long each operation took to run:

db.system.profile.find(

{

ts : {

$gt : new ISODate(“2011-07-12T03:00:00Z”) ,

$lt : new ISODate(“2011-07-12T03:40:00Z”)

}

{ user : 0 }

).sort( { millis : -1 } )

Show the Five Most Recent Events – On a database that has profiling enabled, the show profile helper in the mongo shell displays the 5 most recent operations that took at least 1 millisecond to execute. Issue show profile from the mongo shell, as follows:

show profile

Profiler Overhead – When enabled, profiling has a minor effect on performance. The system.profile collection is a capped collection with a default size of 1 megabyte. A collection of this size can typically store several thousand profile documents, but some application may use more or less profiling data per operation. To change the size of the system.profile collection, you must:

Disable profiling.
Drop the system.profile collection.
Create a new system.profile collection.
Re-enable profiling.

For example, to create a new system.profile collections that’s 4000000 bytes, use the following sequence of operations in the mongo shell:

db.setProfilingLevel(0)

db.system.profile.drop()

db.createCollection( “system.profile”, { capped: true, size:4000000 } )

db.setProfilingLevel(1)

Change Size of system.profile Collection – To change the size of the system.profile collection on a secondary, you must stop the secondary, run it as a standalone, and then perform the steps above. When done, restart the standalone as a member of the replica set.

Rotate Log Files – Log rotation using MongoDB’s standard approach archives the current log file and starts a new one. To do this, the mongod or mongos instance renames the current log file by appending a UTC (GMT) timestamp to the filename, in ISODate format. It then opens a new log file, closes the old log file, and sends all new log entries to the new log file.

MongoDB’s standard approach to log rotation only rotates logs in response to the logRotate command, or when the mongod or mongos process receives a SIGUSR1 signal from the operating system. Alternately, you may configure mongod to send log data to syslog. In this case, you can take advantage of alternate logrotation tools.

Log Rotation With MongoDB – The following steps create and rotate a log file:

Start a mongod with verbose logging, with appending enabled, and with the following log file:

mongod -v –logpath /var/log/mongodb/server1.log –logappend

In a separate terminal, list the matching files:

ls /var/log/mongodb/server1.log*

For results, you get:

server1.log

Rotate the log file using one of the following methods.

From the mongo shell, issue the logRotate command from the admin database:

use admin

db.runCommand( { logRotate : 1 } )

This is the only available method to rotate log files on Windows systems.

For Linux systems, rotate logs for a single process by issuing the following command:

kill -SIGUSR1 <mongod process id>

List the matching files again:

ls /var/log/mongodb/server1.log*

For results you get something similar to the following. The timestamps will be different.

server1.log server1.log.2011-11-24T23-30-00

The example results indicate a log rotation performed at exactly 11:30 pm on November 24th, 2011 UTC, which is the local time offset by the local time zone. The original log file is the one with the timestamp. The new log is server1.log file. If you issue a second logRotate command an hour later, then an additional file would appear when listing matching files, as in the following example:

server1.log server1.log.2011-11-24T23-30-00 server1.log.2011-11-25T00-30-00

This operation does not modify the server1.log.2011-11-24T23-30-00 file created earlier, while server1.log.2011-11-25T00-30-00 is the previous server1.log file, renamed. server1.log is a new, empty file that receives all new log output.

Syslog Log Rotation – It is new in version 2.2. To configure mongod to send log data to syslog rather than writing log data to a file, use the following procedure.

Start a mongod with the syslog option.
Store and rotate the log output using your system’s default log rotation mechanism.

You cannot use syslog with systemLog.path.

Manage Journaling – MongoDB uses write ahead logging to an on-disk journal to guarantee write operation durability and to provide crash resiliency. Before applying a change to the data files, MongoDB writes the change operation to the journal. If MongoDB should terminate or encounter an error before it can write the changes from the journal to the data files, MongoDB can re-apply the write operation and maintain a consistent state. Without a journal, if mongod exits unexpectedly, you must assume your data is in an inconsistent state, and you must run either repair or, preferably, resync from a clean member of the replica set.

With journaling enabled, if mongod stops unexpectedly, the program can recover everything written to the journal, and the data remains in a consistent state. By default, the greatest extent of lost writes, i.e., those not made to the journal, are those made in the last 100 milliseconds. See commitIntervalMs for more information on the default. With journaling, if you want a data set to reside entirely in RAM, you need enough RAM to hold the data set plus the “write working set.” The “write working set” is the amount of unique data you expect to see written between re-mappings of the private view.

Changed in version 2.0: For 64-bit builds of mongod, journaling is enabled by default.

Enable Journaling – Changed in version 2.0: For 64-bit builds of mongod, journaling is enabled by default. To enable journaling, start mongod with the –journal command line option. If no journal files exist, when mongod starts, it must preallocate new journal files. During this operation, the mongod is not listening for connections until preallocation completes: for some systems this may take a several minutes. During this period your applications and the mongo shell are not available.

Disable Journaling – Do not disable journaling on production systems. If your mongod instance stops without shutting down cleanly unexpectedly for any reason, (e.g. power failure) and you are not running with journaling, then you must recover from an unaffected replica set member or backup, as described in repair. To disable journaling, start mongod with the –nojournal command line option.

Get Commit Acknowledgment – You can get commit acknowledgment with the getLastError command and the j option.

Avoid Preallocation Lag – To avoid preallocation lag, you can preallocate files in the journal directory by copying them from another instance of mongod. Preallocated files do not contain data. It is safe to later remove them. But if you restart mongod with journaling, mongod will create them again. As an example, the following sequence preallocates journal files for an instance of mongod running on port 27017 with a database path of /data/db. For demonstration purposes, the sequence starts by creating a set of journal files in the usual way.

Create a temporary directory into which to create a set of journal files:

mkdir ~/tmpDbpath

Create a set of journal files by staring a mongod instance that uses the temporary directory:

mongod –port 10000 –dbpath ~/tmpDbpath –journal

When you see the following log output, indicating mongod has the files, press CONTROL+C to stop the mongod instance:

[initandlisten] waiting for connections on port 10000

Preallocate journal files for the new instance of mongod by moving the journal files from the data directory of the existing instance to the data directory of the new instance:

mv ~/tmpDbpath/journal /data/db/

Start the new mongod instance:

mongod –port 27017 –dbpath /data/db –journal

Monitor Journal Status – Use the following commands and methods to monitor journal status:

serverStatus – The serverStatus command returns database status information that is useful for assessing performance.
journalLatencyTest – Use journalLatencyTest to measure how long it takes on your volume to write to the disk in an append-only fashion. You can run this command on an idle system to get a baseline sync time for journaling. You can also run this command on a busy system to see the sync time on a busy system, which may be higher if the journal directory is on the same volume as the data files. The journalLatencyTest command also provides a way to check if your disk drive is buffering writes in its local cache. If the number is very low (i.e., less than 2 milliseconds) and the drive is non-SSD, the drive is probably buffering writes. In that case, enable cache write-through for the device in your operating system, unless you have a disk controller card with battery backed RAM.

Change the Group Commit Interval – Changed in version 2.0. You can set the group commit interval using the –journalCommitInterval command line option. The allowed range is 2 to 300 milliseconds. Lower values increase the durability of the journal at the expense of disk performance.

Recover Data After Unexpected Shutdown – On a restart after a crash, MongoDB replays all journal files in the journal directory before the server becomes available. If MongoDB must replay journal files, mongod notes these events in the log output. There is no reason to run repairDatabase in these situations.

Store a JavaScript Function on the Server – We do not recommend using server-side stored functions if possible. There is a special system collection named system.js that can store JavaScript functions for reuse. To store a function, you can use the db.collection.save(), as in the following example:

db.system.js.save(

{

_id : “myAddFunction” ,

value : function (x, y){ return x + y; }

}

);

The _id field holds the name of the function and is unique per database.
The value field holds the function definition

Once you save a function in the system.js collection, you can use the function from any JavaScript context (e.g. eval command or the mongo shell method db.eval(), $where operator, mapReduce or mongo shell method db.collection.mapReduce()). Consider the following example from the mongo shell that first saves a function named echoFunction to the system.js collection and calls the function using db.eval() method:

db.system.js.save(

{ _id: “echoFunction”,

value : function(x) { return x; }

}

)

db.eval( “echoFunction( ‘test’ )” )

New in version 2.1: In the mongo shell, you can use db.loadServerScripts() to load all the scripts saved in the system.js collection for the current database. Once loaded, you can invoke the functions directly in the shell, as in the following example:

db.loadServerScripts();

echoFunction(3);

myAddFunction(3, 5);