From 8664fe9c06411f60c7314e5b1b13e69a92fbf37a Mon Sep 17 00:00:00 2001 From: Patrick Donnelly Date: Wed, 8 May 2024 11:27:11 -0400 Subject: [PATCH] doc: document new --output-file switch Signed-off-by: Patrick Donnelly --- PendingReleaseNotes | 7 +++++++ doc/man/8/ceph.rst | 20 +++++++++++++++++++- doc/rados/configuration/common.rst | 21 +++++++++++++++++++++ 3 files changed, 47 insertions(+), 1 deletion(-) diff --git a/PendingReleaseNotes b/PendingReleaseNotes index fa4c73fe5da..bab80c65428 100644 --- a/PendingReleaseNotes +++ b/PendingReleaseNotes @@ -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. diff --git a/doc/man/8/ceph.rst b/doc/man/8/ceph.rst index 478d3c6b3ce..bcc63b871e0 100644 --- 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 c397f4e52ac..0c8350efb52 100644 --- 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 ======== -- 2.39.5