]> git.apps.os.sepia.ceph.com Git - ceph-ci.git/commitdiff
doc: document new --output-file switch
authorPatrick Donnelly <pdonnell@redhat.com>
Wed, 8 May 2024 15:27:11 +0000 (11:27 -0400)
committerPatrick Donnelly <pdonnell@redhat.com>
Sat, 11 May 2024 00:59:38 +0000 (20:59 -0400)
Signed-off-by: Patrick Donnelly <pdonnell@redhat.com>
PendingReleaseNotes
doc/man/8/ceph.rst
doc/rados/configuration/common.rst

index fa4c73fe5dae15cef7b5fb437fc4f55d4ab183ee..bab80c65428bb9219121ebd0ac63f7844b54bdfb 100644 (file)
@@ -1,5 +1,12 @@
 >=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.
index 478d3c6b3ce9cb91fe1cd5bcf013f199f3ddeb29..bcc63b871e0b1d5c5b45f58ac68f75192ebc7722 100644 (file)
@@ -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
 
index c397f4e52acce56e80b0065c7de24943ead40c82..0c8350efb529d686f6e7423192a136a9fb7b58ef 100644 (file)
@@ -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
 ========