Merge pull request ceph#63691 from zdover23/wip-doc-2025-06-04-backport-63476-to-tentacle

tentacle: doc/mgr: edit telemetry.rst

Author: anthonyeleven

doc/mgr/telemetry.rst

@@ -64,36 +64,46 @@ the way Ceph is used.
 
 Data is sent secured to *https://telemetry.ceph.com*.
 
-Individual channels can be enabled or disabled with::
+Individual channels can be enabled or disabled with:
 
-  ceph telemetry enable channel basic
-  ceph telemetry enable channel crash
-  ceph telemetry enable channel device
-  ceph telemetry enable channel ident
-  ceph telemetry enable channel perf
+.. prompt:: bash #
 
-  ceph telemetry disable channel basic
-  ceph telemetry disable channel crash
-  ceph telemetry disable channel device
-  ceph telemetry disable channel ident
-  ceph telemetry disable channel perf
+   ceph telemetry enable channel basic
+   ceph telemetry enable channel crash
+   ceph telemetry enable channel device
+   ceph telemetry enable channel ident
+   ceph telemetry enable channel perf
+  
+   ceph telemetry disable channel basic
+   ceph telemetry disable channel crash
+   ceph telemetry disable channel device
+   ceph telemetry disable channel ident
+   ceph telemetry disable channel perf
 
-Multiple channels can be enabled or disabled with::
+Multiple channels can be enabled or disabled with:
 
-  ceph telemetry enable channel basic crash device ident perf
-  ceph telemetry disable channel basic crash device ident perf
+.. prompt:: bash #
 
-Channels can be enabled or disabled all at once with::
+   ceph telemetry enable channel basic crash device ident perf
+   ceph telemetry disable channel basic crash device ident perf
 
-  ceph telemetry enable channel all
-  ceph telemetry disable channel all
+Channels can be enabled or disabled all at once with:
+
+.. prompt:: bash #
+
+   ceph telemetry enable channel all
+   ceph telemetry disable channel all
 
 Please note that telemetry should be on for these commands to take effect.
 
-List all channels with::
+List all channels with:
+
+.. prompt:: bash #
 
   ceph telemetry channel ls
 
+::
+
   NAME      ENABLED    DEFAULT    DESC
   basic     ON         ON         Share basic cluster information (size, version)
   crash     ON         ON         Share metadata about Ceph daemon crashes (version, stack straces, etc)
@@ -105,83 +115,110 @@ List all channels with::
 Enabling Telemetry
 ------------------
 
-To allow the *telemetry* module to start sharing data::
+To allow the *telemetry* module to start sharing data:
 
-  ceph telemetry on
+.. prompt:: bash #
+
+   ceph telemetry on
 
 Please note: Telemetry data is licensed under the Community Data License
 Agreement - Sharing - Version 1.0 (https://cdla.io/sharing-1-0/). Hence,
-telemetry module can be enabled only after you add '--license sharing-1-0' to
-the 'ceph telemetry on' command.
-Once telemetry is on, please consider enabling channels which are off by
-default, such as the 'perf' channel. 'ceph telemetry on' output will list the
-exact command to enable these channels.
+telemetry module can be enabled only after you add ``--license sharing-1-0`` to
+the ``ceph telemetry on`` command.  Once telemetry is on, please consider
+enabling channels which are off by default, such as the ``perf`` channel.
+``ceph telemetry on`` output will list the exact command to enable these
+channels.
+
+Telemetry can be disabled at any time with:
 
-Telemetry can be disabled at any time with::
+.. prompt:: bash #
 
-  ceph telemetry off
+   ceph telemetry off
 
 Sample report
 -------------
 
-You can look at what data is reported at any time with the command::
+You can look at what data is reported at any time with the command:
+
+.. prompt:: bash #
 
-  ceph telemetry show
+   ceph telemetry show
 
-If telemetry is off, you can preview a sample report with::
+If telemetry is off, you can preview a sample report with:
 
-  ceph telemetry preview
+.. prompt:: bash #
+
+   ceph telemetry preview
 
 Generating a sample report might take a few moments in big clusters (clusters
 with hundreds of OSDs or more).
 
 To protect your privacy, device reports are generated separately, and data such
 as hostname and device serial number is anonymized. The device telemetry is
 sent to a different endpoint and does not associate the device data with a
-particular cluster. To see a preview of the device report use the command::
+particular cluster. To see a preview of the device report use the command:
+
+.. prompt:: bash #
+
+   ceph telemetry show-device
 
-  ceph telemetry show-device
+If telemetry is off, you can preview a sample device report with:
 
-If telemetry is off, you can preview a sample device report with::
+.. prompt:: bash #
 
-  ceph telemetry preview-device
+   ceph telemetry preview-device
 
 Please note: In order to generate the device report we use Smartmontools
-version 7.0 and up, which supports JSON output. 
-If you have any concerns about privacy with regard to the information included in
-this report, please contact the Ceph developers.
+version 7.0 and up, which supports JSON output.  If you have any concerns about
+privacy with regard to the information included in this report, please contact
+the Ceph developers.
 
-In case you prefer to have a single output of both reports, and telemetry is on, use::
+In case you prefer to have a single output of both reports, and telemetry is
+on, use:
 
-  ceph telemetry show-all
+.. prompt:: bash #
 
-If you would like to view a single output of both reports, and telemetry is off, use::
+   ceph telemetry show-all
 
-  ceph telemetry preview-all
+If you would like to view a single output of both reports, and telemetry is
+off, use:
+
+.. prompt:: bash #
+
+   ceph telemetry preview-all
 
 **Sample report by channel**
 
-When telemetry is on you can see what data is reported by channel with::
+When telemetry is on you can see what data is reported by channel with:
+
+.. prompt:: bash #
 
-  ceph telemetry show <channel_name>
+   ceph telemetry show <channel_name>
 
-Please note: If telemetry is on, and <channel_name> is disabled, the command
-above will output a sample report by that channel, according to the collections
-the user is enrolled to. However this data is not reported, since the channel
-is disabled.
+Please note: If telemetry is on, and ``<channel_name>`` is disabled, the
+command above will output a sample report by that channel, according to the
+collections the user is enrolled to. However this data is not reported, since
+the channel is disabled.
 
-If telemetry is off you can preview a sample report by channel with::
+If telemetry is off you can preview a sample report by channel with:
+
+.. prompt:: bash #
 
   ceph telemetry preview <channel_name>
 
 Collections
 -----------
 
-Collections represent different aspects of data that we collect within a channel.
+Collections represent different aspects of data that we collect within a
+channel.
+
+List all collections with:
+
+.. prompt:: bash #
 
-List all collections with::
+   ceph telemetry collection ls
 
-  ceph telemetry collection ls
+::
 
   NAME                            STATUS                                               DESC
   basic_base                      NOT REPORTING: NOT OPTED-IN                          Basic information about the cluster (capacity, number and type of daemons, version, etc.)
@@ -210,82 +247,100 @@ is opted-in to this collection).
 **DESC**: General description of the collection.
 
 See the diff between the collections you are enrolled to, and the new,
-available collections with::
+available collections with:
+
+.. prompt:: bash #
+
+   ceph telemetry diff
+
+Enroll to the most recent collections with:
 
-  ceph telemetry diff
+.. prompt:: bash #
 
-Enroll to the most recent collections with::
+   ceph telemetry on
 
-  ceph telemetry on
+Then enable new channels that are off with:
 
-Then enable new channels that are off with::
+.. prompt:: bash #
 
-  ceph telemetry enable channel <channel_name>
+   ceph telemetry enable channel <channel_name>
 
 Interval
 --------
 
 The module compiles and sends a new report every 24 hours by default.
-You can adjust this interval with::
+You can adjust this interval with:
 
-  ceph config set mgr mgr/telemetry/interval 72    # report every three days
+.. prompt:: bash #
+
+   ceph config set mgr mgr/telemetry/interval 72    # report every three days
 
 Status
 --------
 
-The see the current configuration::
+The see the current configuration:
+
+.. prompt:: bash #
 
-  ceph telemetry status
+   ceph telemetry status
 
 Manually sending telemetry
 --------------------------
 
-To ad hoc send telemetry data::
+To ad hoc send telemetry data:
+
+.. prompt:: bash #
 
-  ceph telemetry send
+   ceph telemetry send
 
-In case telemetry is not enabled (with 'ceph telemetry on'), you need to add
-'--license sharing-1-0' to 'ceph telemetry send' command.
+In case telemetry is not enabled (with ``ceph telemetry on``), you need to add
+``--license sharing-1-0`` to the ``ceph telemetry send`` command.
 
 Sending telemetry through a proxy
 ---------------------------------
 
 If the cluster cannot directly connect to the configured telemetry
-endpoint (default *telemetry.ceph.com*), you can configure a HTTP/HTTPS
-proxy server with::
+endpoint (default ``telemetry.ceph.com``), you can configure a HTTP/HTTPS
+proxy server with:
 
-  ceph config set mgr mgr/telemetry/proxy https://10.0.0.1:8080
+.. prompt:: bash #
 
-You can also include a *user:pass* if needed::
+   ceph config set mgr mgr/telemetry/proxy https://10.0.0.1:8080
 
-  ceph config set mgr mgr/telemetry/proxy https://ceph:[email protected]:8080
+You can also include a ``user:pass`` if needed:
+
+.. prompt:: bash #
+
+   ceph config set mgr mgr/telemetry/proxy https://ceph:[email protected]:8080
 
 
 Contact and Description
 -----------------------
 
 A contact and description can be added to the report.  This is
-completely optional, and disabled by default.::
+completely optional, and disabled by default:
+
+.. prompt:: bash #
 
-  ceph config set mgr mgr/telemetry/contact 'John Doe <[email protected]>'
-  ceph config set mgr mgr/telemetry/description 'My first Ceph cluster'
-  ceph config set mgr mgr/telemetry/channel_ident true
+   ceph config set mgr mgr/telemetry/contact 'John Doe <[email protected]>'
+   ceph config set mgr mgr/telemetry/description 'My first Ceph cluster'
+   ceph config set mgr mgr/telemetry/channel_ident true
 
 Leaderboard
 -----------
 
 To participate in a leaderboard in the `public dashboards
 <https://telemetry-public.ceph.com/>`_, run the following command:
 
-.. prompt:: bash $
+.. prompt:: bash #
 
    ceph config set mgr mgr/telemetry/leaderboard true
 
 The leaderboard displays basic information about the cluster. This includes the
 total storage capacity and the number of OSDs. To add a description of the
 cluster, run a command of the following form: 
 
-.. prompt:: bash $
+.. prompt:: bash #
 
    ceph config set mgr mgr/telemetry/leaderboard_description 'Ceph cluster for Computational Biology at the University of XYZ'