doc/mgr/telemetry: document new commands

New commands:

  ceph telemetry enable channel <channel_name>
  ceph telemetry disable channel <channel_name>
  ceph telemetry channel ls
  ceph telemetry collection ls
  ceph telemetry collection diff
  ceph telemetry preview
  ceph telemetry preview-device
  ceph telemetry preview-all

Signed-off-by: Yaarit Hatuka <yaarit@redhat.com>

diff --git a/doc/mgr/telemetry.rst b/doc/mgr/telemetry.rst
index f334df9af1d767cd733fc14fd838d1cf90548af2..12beff8f861d54d3f9bf1dd09070cf7e7db699aa 100644 (file)
--- a/doc/mgr/telemetry.rst
+++ b/doc/mgr/telemetry.rst
@@ -64,6 +64,58 @@ the way Ceph is used.
 
 Data is sent secured to *https://telemetry.ceph.com*.
 
+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
+
+  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::
+
+  ceph telemetry enable channel basic crash device ident perf
+  ceph telemetry disable channel basic crash device ident perf
+
+Please note that telemetry should be on for these commands to take effect.
+
+List all channels with::
+
+  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)
+  device    ON         ON         Share device health metrics (e.g., SMART data, minus potentially identifying info like serial numbers)
+  ident     OFF        OFF        Share a user-provided description and/or contact email for the cluster
+  perf      ON         OFF        Share various performance metrics of a cluster
+
+
+Enabling Telemetry
+------------------
+
+To allow the *telemetry* module to start sharing data::
+
+  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 can be disabled at any time with::
+
+  ceph telemetry off
+
 Sample report
 -------------
 
@@ -71,6 +123,13 @@ You can look at what data is reported at any time with the command::
 
   ceph telemetry show
 
+If telemetry is off, you can preview a sample report with::
+
+  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
@@ -78,39 +137,85 @@ particular cluster. To see a preview of the device report use the command::
 
   ceph telemetry show-device
 
+If telemetry is off, you can preview a sample device report with::
+
+  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.
 
-Channels
---------
+In case you prefer to have a single output of both reports, and telemetry is on, use::
 
-Individual channels can be enabled or disabled with::
+  ceph telemetry show-all
 
-  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 config set mgr mgr/telemetry/channel_device false
-  ceph config set mgr mgr/telemetry/channel_perf false
-  ceph telemetry show
-  ceph telemetry show-device
+If you would like to view a single output of both reports, and telemetry is off, use::
 
-Enabling Telemetry
-------------------
+  ceph telemetry preview-all
 
-To allow the *telemetry* module to start sharing data::
+**Sample report by channel**
 
-  ceph telemetry on
+When telemetry is on you can see what data is reported by channel with::
 
-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.
+  ceph telemetry show <channel_name>
 
-Telemetry can be disabled at any time with::
+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.
 
-  ceph telemetry off
+If telemetry is off you can preview a sample report by channel with::
+
+  ceph telemetry preview <channel_name>
+
+Collections
+-----------
+
+Collections represent different aspects of data that we collect within a channel.
+
+List all collections with::
+
+  ceph telemetry collection ls
+
+  NAME                  ENROLLED    STATUS    DEFAULT    DESC
+  basic_base            FALSE       OFF       ON         Basic information about the cluster (capacity, number and type of daemons, version, etc.)
+  basic_mds_metadata    FALSE       OFF       ON         MDS metadata
+  crash_base            FALSE       OFF       ON         Information about daemon crashes (daemon type and version, backtrace, etc.)
+  device_base           FALSE       OFF       ON         Information about device health metrics
+  ident_base            FALSE       OFF       OFF        User-provided identifying information about the cluster
+  perf_perf             FALSE       OFF       OFF        Information about performance of the cluster
+
+Where:
+
+**NAME**: Collection name; prefix indicates the channel the collection belongs to.
+
+**ENROLLED**: Signifies the collections that were available in the module when
+the user last opted-in to telemetry. Please note: Even if a collection is
+'enrolled', its metrics will be reported only if its channel is enabled.
+The STATUS column indicates whether the collection is being reported.
+
+**STATUS**: Indicates whether the collection metrics are reported; this is
+determined by the status (enabled / disabled) of the channel the collection
+belongs to, along with the enrollment status of the collection.
+
+**DEFAULT**: The default status (enabled / disabled) of the channel the
+collection belongs to.
+
+**DESC**: General description of the collection.
+
+See the diff between the collections you are enrolled to, and the new,
+available collections with::
+
+  ceph telemetry diff
+
+Enroll to the most recent collections with::
+
+  ceph telemetry on
+
+Then enable new channels that are off with::
+
+  ceph telemetry enable channel <channel_name>
 
 Interval
 --------

diff --git a/src/pybind/mgr/telemetry/module.py b/src/pybind/mgr/telemetry/module.py
index 2a00dea157749d7d708a6a8b9e6a252911c3af7b..b55e2964245a299afb86a31d78f79444d21f78af 100644 (file)
--- a/src/pybind/mgr/telemetry/module.py
+++ b/src/pybind/mgr/telemetry/module.py
@@ -169,7 +169,7 @@ class Module(MgrModule):
         Option(name='channel_perf',
                type='bool',
                default=False,
-               desc='Share perf counter metrics summed across the whole cluster'),
+               desc='Share various performance metrics of a cluster'),
     ]
 
     @property