doc: document new --output-file switch

Signed-off-by: Patrick Donnelly <pdonnell@redhat.com>
(cherry picked from commit 8664fe9c06411f60c7314e5b1b13e69a92fbf37a)

diff --git a/PendingReleaseNotes b/PendingReleaseNotes
index 66bf643cd5f6d895a50a03718e3ef3ec3ff18c3c..a12c6264d1b5ff935046f60e6d8b668f22fd740c 100644 (file)
--- a/PendingReleaseNotes
+++ b/PendingReleaseNotes
@@ -50,6 +50,13 @@
 
 >=19.0.0
 
+* ceph: a new --daemon-output-file switch is available for `ceph tell` commands
+  to dump output to a file local to the daemon. For commands which produce
+  large amounts of output, this avoids a potential spike in memory usage on the
+  daemon, allows for faster streaming writes to a file local to the daemon, and
+  reduces time holding any locks required to execute the command. For analysis,
+  it is necessary to retrieve the file from the host running the daemon
+  manually. Currently, only --format=json|json-pretty are supported.
 * RGW: GetObject and HeadObject requests now return a x-rgw-replicated-at
   header for replicated objects. This timestamp can be compared against the
   Last-Modified header to determine how long the object took to replicate.

diff --git a/doc/man/8/ceph.rst b/doc/man/8/ceph.rst
index 02c83bfe02a43ccf2271a7b9f61480d4777109ae..44f5a923e962674fad1893e020412d64f23b9564 100644 (file)
--- a/doc/man/8/ceph.rst
+++ b/doc/man/8/ceph.rst
@@ -1724,7 +1724,25 @@ Options
 
 .. option:: -f {json,json-pretty,xml,xml-pretty,plain,yaml}, --format
 
-       Format of output. Note: yaml is only valid for orch commands. 
+       Format of output.
+
+    Note: yaml is only valid for orch commands.
+
+.. option:: --daemon-output-file OUTPUT_FILE
+
+    When using --format=json|json-pretty, you may specify a file name on the
+    host running the daemon to stream output to. Be mindful this is probably
+    not the same machine running the ceph command. So to analyze the output, it
+    will be necessary to fetch the file once the command completes.
+
+    OUTPUT_FILE may also be ``:tmp:``, indicating that the daemon should create
+    a temporary file (subject to configurations tmp_dir and tmp_file_template).
+
+    The ``tell`` command will output json with the path to the output file
+    written to, the size of the file, the result code of the command, and any
+    output produced by the command.
+
+    Note: this option is only used for ``ceph tell`` commands.
 
 .. option:: --connect-timeout CLUSTER_TIMEOUT
 

diff --git a/doc/rados/configuration/common.rst b/doc/rados/configuration/common.rst
index 69072164dd9638bf929ea7e18b5f5667dc2c9a70..319fce9ab47c431cfd4592eb50628285c5f3bc25 100644 (file)
--- a/doc/rados/configuration/common.rst
+++ b/doc/rados/configuration/common.rst
@@ -44,6 +44,27 @@ For more about configuring a network for use with Ceph, see the `Network
 Configuration Reference`_ .
 
 
+Temporary Directory
+===================
+
+Some operations will cause a daemon to write to a temporary file. These files
+are located according to the ``tmp_dir`` config.
+
+.. confval:: tmp_dir
+
+The ``$TMPDIR`` environment variable is used to initialize the config, if
+present, but may be overriden on the command-line. A default may also
+be set for the cluster using the usual ``ceph config`` API.
+
+The template for the temporary files created by daemons is controlled
+by the ``tmp_file_template`` config.
+
+.. confval:: tmp_file_template
+
+One example where temporary files are created by daemons is the use of the
+``--daemon-output-file=:tmp:`` argument to the ``ceph tell`` command.
+
+
 Monitors
 ========