doc/mgr: edit insights.rst

Edit doc/mgr/insights.rst. Improve the English where necessary.

This is part of a project to separate out the twenty-five files that
were committed to https://github.com/ceph/ceph/pull/62782.

Signed-off-by: Zac Dover <zac.dover@proton.me>
(cherry picked from commit 31d7dac8ff62ca31ffe86d8ef07a6f16047f2a64)

diff --git a/doc/mgr/insights.rst b/doc/mgr/insights.rst
index 37b8903f165a1d4e3cdd3484c2b92499d215053d..60c32ba6ea62161a118fb26636a85f3b0fa3ce63 100644 (file)
--- a/doc/mgr/insights.rst
+++ b/doc/mgr/insights.rst
@@ -1,52 +1,55 @@
 Insights Module
 ===============
 
-The insights module collects and exposes system information to the Insights Core
-data analysis framework. It is intended to replace explicit interrogation of
-Ceph CLIs and daemon admin sockets, reducing the API surface that Insights
-depends on. The insights reports contains the following:
+The ``insights`` module collects and exposes system information to the
+Insights Core data analysis framework. It is intended to replace explicit
+interrogation of Ceph CLIs and daemon admin sockets, reducing the API surface
+that Insights depends on. The insights reports contain the following:
 
 * **Health reports**. In addition to reporting the current health of the
-  cluster, the insights module reports a summary of the last 24 hours of health
-  checks. This feature is important for catching cluster health issues that are
-  transient and may not be present at the moment the report is generated. Health
-  checks are deduplicated to avoid unbounded data growth.
+  cluster, the insights module reports a summary of the last 24 hours of
+  health checks. This feature is important for catching cluster health issues
+  that are transient and may not be present at the moment the report is
+  generated. Health checks are deduplicated to avoid unbounded data growth.
 
 * **Crash reports**. A summary of any daemon crashes in the past 24 hours is
-  included in the insights report. Crashes are reported as the number of crashes
-  per daemon type (e.g. `ceph-osd`) within the time window. Full details of a
-  crash may be obtained using the `crash module`_.
+  included in the insights report. Crashes are reported as the number of
+  crashes per daemon type (e.g. ``ceph-osd``) within the time window. Full
+  details of a crash may be obtained using the `crash module`_.
 
-* Software version, storage utilization, cluster maps, placement group summary,
-  monitor status, cluster configuration, and OSD metadata.
+* Software version, storage utilization, cluster maps, placement group
+  summary, monitor status, cluster configuration, and OSD metadata.
 
 Enabling
 --------
 
-The *insights* module is enabled with::
+To enable the *insights* module, run the following command:
 
-  ceph mgr module enable insights
+.. prompt:: bash #
+
+   ceph mgr module enable insights
 
 Commands
 --------
-::
 
-  ceph insights
+To generate a full report, run the following command:
+
+.. prompt:: bash #
 
-Generate the full report.
+   ceph insights
 
-::
+To remove historical health data older than ``<hours>``, run a command of the
+following form. Passing ``0`` for ``<hours>`` will clear all health data.
 
-  ceph insights prune-health <hours>
+.. prompt:: bash #
 
-Remove historical health data older than <hours>. Passing `0` for <hours> will
-clear all health data.
+   ceph insights prune-health <hours>
 
-This command is useful for cleaning the health history before automated nightly
-reports are generated, which may contain spurious health checks accumulated
-while performing system maintenance, or other health checks that have been
-resolved. There is no need to prune health data to reclaim storage space;
-garbage collection is performed regularly to remove old health data from
-persistent storage.
+The ``prune-health`` subcommand is useful for cleaning the health history
+before automated nightly reports are generated. Unpruned health histories may
+contain spurious health checks accumulated while performing system maintenance
+and other health checks that have been resolved. There is no need to prune
+health data to reclaim storage space; garbage collection is performed
+regularly to remove old health data from persistent storage.
 
 .. _crash module: ../crash