doc/mgr/telemetry: update

Signed-off-by: Sage Weil <sage@redhat.com>

diff --git a/doc/mgr/telemetry.rst b/doc/mgr/telemetry.rst
index dafbb54435c1a72a7270584db6b56f2944e86d56..34b50ccc3fb91c557254e0c56ca54a2b6d69c1c4 100644 (file)
--- a/doc/mgr/telemetry.rst
+++ b/doc/mgr/telemetry.rst
@@ -7,19 +7,34 @@ The telemetry module sends anonymous data about the cluster back to the Ceph
 developers to help understand how Ceph is used and what problems users may
 be experiencing.
 
-Reported telemetry includes:
+Channels
+--------
+
+The telemetry report is broken down into several "channels," each with
+a different type of information.  Assuming telemetry has been enabled,
+individual channels can be turned on and off.  (If telemetry is off,
+the per-channel setting has no effect.)
+
+* **basic** (default: on): Basic information about the cluster
 
-  * capacity of the cluster 
-  * number of monitors, managers, OSDs, MDSs, radosgws, or other daemons
-  * software version currently being used
-  * number and types of RADOS pools and CephFS file systems
-  * information about daemon crashes, including
+    - capacity of the cluster
+    - number of monitors, managers, OSDs, MDSs, radosgws, or other daemons
+    - software version currently being used
+    - number and types of RADOS pools and CephFS file systems
+
+* **crash** (default: on): Information about daemon crashes, including
 
     - type of daemon
     - version of the daemon
     - operating system (OS distribution, kernel version)
     - stack trace identifying where in the Ceph code the crash occurred
 
+* **ident** (default: on): User-provided identifying information about
+  the cluster
+
+    - cluster description
+    - contact email address
+
 The data being reported does *not* contain any sensitive
 data like pool names, object names, object contents, or hostnames.
 
@@ -30,26 +45,43 @@ the way Ceph is used.
 
 Data is sent over HTTPS to *telemetry.ceph.com*.
 
+Enabling the module
+-------------------
+
+The module must first be enabled.  Note that even if the module is
+enabled, telemetry is still "off" by default, so simply enabling the
+module will *NOT* result in any data being shared.::
+
+  ceph mgr module enable telemetry
+
 Sample report
 -------------
 
 You can look at what data is reported at any time with the command::
 
-  ceph mgr module enable telemetry
   ceph telemetry show
 
 If you have any concerns about privacy with regard to the information included in
 this report, please contact the Ceph developers.
 
-Enabling
+Channels
 --------
 
-The *telemetry* module is enabled with::
+Individual channels can be enabled or disabled with::
+
+  ceph config set mgr mgr/telemetry/channel_ident false
+  ceph config set mgr mgr/telemetry/channel_basic false
+  ceph config set mgr mgr/telemetry/channel_crash false
+  ceph telemetry show
+
+Enabling Telemetry
+------------------
+
+To allow the *telemetry* module to start sharing data,::
 
-  ceph mgr module enable telemetry
   ceph telemetry on
 
-Telemetry can be disabled with::
+Telemetry can be disabled at any time with::
 
   ceph telemetry off
 
@@ -64,16 +96,10 @@ You can adjust this interval with::
 Contact and Description
 -----------------------
 
-A contact and description can be added to the report.  This is completely optional.::
+A contact and description can be added to the report.  This is
+completely optional, and disabled by default.::
 
   ceph config set mgr mgr/telemetry/contact 'John Doe <john.doe@example.com>'
   ceph config set mgr mgr/telemetry/description 'My first Ceph cluster'
+  ceph config set mgr mgr/telemetry/channel_ident true
 
-Show report
------------
-
-The report is sent in JSON format, and can be printed::
-
-  ceph telemetry show
-
-So you can inspect the content if you have privacy concerns.