doc: add insights module documentation

Signed-off-by: Noah Watkins <nwatkins@redhat.com>

diff --git a/doc/mgr/index.rst b/doc/mgr/index.rst
index e00c0381a052b7a651f33ad70a47ec0f7d4c3073..ed107595444d708c69f2337b50a2a5dfdd98e06c 100644 (file)
--- a/doc/mgr/index.rst
+++ b/doc/mgr/index.rst
@@ -43,3 +43,4 @@ sensible.
     Devicehealth plugin <devicehealth>
     Orchestrator CLI plugin <orchestrator_cli>
     Rook plugin <rook>
+    Insights plugin <insights>

diff --git a/doc/mgr/insights.rst b/doc/mgr/insights.rst
new file mode 100644 (file)
index 0000000..74617b9
--- /dev/null
+++ b/doc/mgr/insights.rst
@@ -0,0 +1,48 @@
+Insights plugin
+===============
+
+The insights plugin 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:
+
+* **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.
+
+* **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`_.
+
+* Software version, storage utilization, cluster maps, placement group summary,
+  monitor status, cluster configuration, and OSD metadata.
+
+Enabling
+--------
+
+The *insights* module is enabled with::
+
+  ceph mgr module enable insights
+
+Commands
+--------
+::
+
+  ceph insights
+
+Generate the full report.
+
+::
+
+  ceph insights prune-health <hours>
+
+Remove historical health data collected within the last <hours>. Passing in `0`
+for <hours> will clear all health data. This command is useful for removing
+health checks that have been recently resolved but which remain in the report.
+There is no need to prune health data to reclaim space; pruning occurs
+automatically each hour removing old health data from persistent storage.
+
+.. _crash module: ../crash