DOCS-162 first draft of current op docs

Author: Sam Kleinman

draft/reference/current-op.txt

@@ -0,0 +1,219 @@
+===========================
+Current Operation Reporting
+===========================
+
+.. default-domain:: mongodb
+
+.. versionchanged:: 2.2
+
+The :method:`db.currentOp()` helper in the :program:`mongo` shell
+reports on the current operations running on the :program:`mongod`
+instance. The command returns the ``inprog`` array which contains a
+document for each in progress operation. Consider the following
+example output:
+
+.. code-block::
+
+   {
+     "inprog": [
+                {
+                        "opid" : 3434473,
+                        "active" : <boolean>,
+                        "secs_running" : 0,
+                        "op" : "<operation>",
+                        "ns" : "<database>.<collection>",
+                        "query" : {
+                        },
+                        "client" : "<host>:<outgoing>",
+                        "desc" : "conn57683",
+                        "threadId" : "0x7f04a637b700",
+                        "connectionId" : 57683,
+                        "locks" : {
+                                "^" : "w",
+                                "^local" : "W",
+                                "^<database>" : "W"
+                        },
+                        "waitingForLock" : false,
+                        "msg": "<string>"
+                        "numYields" : 0,
+                        "progress" : {
+                                "done" : <number>,
+                                "total" : <number>
+                        }
+                        "lockStats" : {
+                                "timeLockedMicros" : {
+                                        "r" : NumberLong(),
+                                        "w" : NumberLong()
+                                },
+                                "timeAcquiringMicros" : {
+                                        "r" : NumberLong(),
+                                        "w" : NumberLong()
+                                }
+                        }
+                },
+               ]
+   }
+
+.. optional::
+
+   You may specify the ``true`` argument to :method:`db.currentOp()`
+   to return full output. For example:
+
+   .. code-block:: javascript
+
+      db.currentOp(true)
+
+   Furthermore, active operations (i.e. where :data:`active` are
+   ``true``) will return additional fields.
+
+Continue reading for full documentation of the entire output of
+:method:`db.currentOp()`.
+
+Output Reference
+----------------
+
+.. data:: opid
+
+   Holds an identifier for the operation. You can pass this value to
+   :method:`db.killOp()` in the :program:`mongo` shell to terminate an
+   operation.
+
+.. data:: active
+
+   A boolean value, that reports if the option is currently running,
+   with the ``true`` value, or queued and waiting for a lock to run,
+   with the ``false`` value.
+
+.. data:: secs_running
+
+   The duration of this operation in seconds.
+
+.. data:: op
+
+   A string that identifies the type of operation. The possible values
+   are:
+
+   - ``insert``
+   - ``query``
+   - ``update``
+   - ``delete``
+   - ``getmore``
+   - ``command``
+
+.. data:: ns
+
+   The :term:`namespace` that this operation targets. Namespaces are
+   formed using the name of the :term:`database` and the name of the
+   :term:`collection`.
+
+.. data:: query
+
+   A document containing the current operation's query. This document
+   is empty for operations that do not have queries: ``getmore``,
+   ``insert``, ``delete``, and ``command``.
+
+.. data:: client
+
+   The IP address (or hostname) and the ephemeral port of the client
+   connection where this operation originates. If your ``inprog``
+   array has operations from many different clients, use this string
+   to relate operations to clients.
+
+.. data:: desc
+
+   A description of the client. This string includes the
+   :data:`connectionId`.
+
+.. data:: threadId
+
+   An identifier for the thread that services this operations and its
+   connection.
+
+.. data:: connectionId
+
+   An identifier for the connection where this operation originated.
+
+.. data:: locks
+
+   The :data:`locks` document reports on the kinds of locks that this
+   operation currently holds. The following lock types are possible:
+
+   .. data:: locks.^
+
+      :data:`locks.^` reports on the global lock state for the
+      :program:`mongod` instance. The operation must hold this for
+      some global phases of an operation.
+
+   .. data:: locks.^local
+
+      :data:`locks.^` reports on the lock for the ``local``
+      database. MongoDB uses the ``local`` database for a number of
+      operations, but the most frequent use of the ``local`` database
+      is for the :term:`oplog` used in replication.
+
+   .. data:: locks.^<database>
+
+      :data:`locks.^<database>` reports on the lock state for the
+      database that this operation targets.
+
+.. data:: waitingForLock
+
+   Returns a boolean value. :data:`waitingForLock` is ``true`` if the
+   operation is waiting for a lock and ``false`` if the operation has
+   the locks that it needs to complete.
+
+.. data:: msg
+
+   The :data:`msg` provides a message that describes the status and
+   progress of the operation. In the case of indexing operations, this
+   field reports the completion percentage.
+
+.. data:: numYields
+
+   :data:`numYields` is a counter that reports the number of time that
+   this operation has yielded to allow other operations to complete.
+
+   Typically, operations will yield when they need to access that that
+   is not yet in memory while MongoDB pages in that data. This allows
+   other operations that are already in memory, to complete quickly
+   while MongoDB reads the data for the first operation into memory.
+
+.. data:: lockStats
+
+   The :data:`lockStats` document reflects the amount of time that a
+   this operation has spent both acquiring and holding
+   locks. :data:`lockStats` reports data on a per-lock type, with the
+   following possible lock types:
+
+   - ``r`` represents the database specific read lock and
+   - ``w`` represents the database specific write lock.
+
+    .. data:: timeLockedMicros
+
+       The :data:`timeLockedMicros` document reports the amount of
+       time this operation has spent holding specific locks.
+
+       .. data:: timeLockedMicros.r
+
+          Reports the amount of time that this operation has held the
+          database specific read lock in microseconds.
+
+       .. data:: timeLockedMicros.w
+
+          Reports the amount of time that this operation has held the
+          database specific write lock in microseconds.
+
+   .. data:: timeAquiringMicros
+
+      The :data:`timeLockedMicros` document reports the amount of time
+      this operation has spent *waiting* to acquire a specific lock.
+
+      .. data:: timeAcquiringMicros.r
+
+         Reports the mount of time the operation has waited for the
+         database specific read lock in microseconds.
+
+      .. data:: timeAcquiringMicros.w
+
+         Reports the mount of time the operation has waited for the
+         database specific write lock in microseconds.