DOCSP-32192 Add cursorTimeoutMillis Warning (#4355) (#5015)

* DOCSP-32192 Add cursorTimeoutMillis Warning

* *

* *

* *

* *

* IR

* *

* *

* *

* *

* *

* *

* IR feedback

* *

* *

* *

* XR1

* *

* *

* *

* *

* *

* *

* Apply suggestions from code review



* *

* *

* *

---------

Co-authored-by: Jeff Allen <[email protected]>

Author: ianf-mongodb

source/reference/glossary.txt

@@ -806,6 +806,11 @@ Glossary
       need to run :dbcommand:`cleanupOrphaned` to delete orphaned
       documents.
 
+   orphaned cursor
+      A cursor that is not properly closed or iterated over 
+      in your application code. Orphaned cursors can cause performance
+      issues in your MongoDB deployment.
+
    passive member
       A member of a :term:`replica set` that cannot become primary
       because its :rsconf:`members[n].priority` is

source/reference/method/cursor.noCursorTimeout.txt

@@ -2,7 +2,11 @@
 cursor.noCursorTimeout()
 ========================
 
-.. default-domain:: mongodb
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 1
+   :class: singlecol
 
 Definition
 ----------
@@ -43,6 +47,11 @@ cursor being configured with :method:`~cursor.noCursorTimeout`. When the
 application requests the next batch of documents, the server returns an
 error.
 
+.. _refresh-session-cursor-example:
+
+Refresh a Cursor with ``refreshSessions``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
 For operations that return a cursor, if the cursor may be idle for
 longer than 30 minutes, issue the operation within an explicit session
 using :method:`Mongo.startSession()` and periodically refresh the

source/reference/parameters.txt

@@ -1322,6 +1322,21 @@ General Parameters
    cursor modifier to analyze the average query time and select an appropriate
    timeout period.
 
+   .. warning::
+
+      Starting in MongoDB 4.4.8, MongoDB cleans up 
+      :term:`orphaned cursors <orphaned cursor>` linked to sessions as 
+      part of session management. This means that orphaned cursors with 
+      session ids do not use ``cursorTimeoutMillis`` to control the 
+      timeout.
+
+      For operations that return a cursor and have an idle period 
+      longer than :parameter:`localLogicalSessionTimeoutMinutes`, 
+      use :method:`Mongo.startSession()` to perform the operation 
+      within an explicit session. To refresh the session, run 
+      the :dbcommand:`refreshSessions` command. For details, see 
+      :ref:`<refresh-session-cursor-example>`.
+
 .. parameter:: failIndexKeyTooLong
 
    *Removed in 4.4*