ceph/doc/mgr/telemetry.rst

   1 .. _telemetry:
   2
   3 Telemetry Module
   4 ================
   5
   6 The telemetry module sends anonymous data about the cluster back to the Ceph
   7 developers to help understand how Ceph is used and what problems users may
   8 be experiencing.
   9
  10 This data is visualized on `public dashboards <https://telemetry-public.ceph.com/>`_
  11 that allow the community to quickly see summary statistics on how many clusters
  12 are reporting, their total capacity and OSD count, and version distribution
  13 trends.
  14
  15 Channels
  16 --------
  17
  18 The telemetry report is broken down into several "channels", each with
  19 a different type of information.  Assuming telemetry has been enabled,
  20 individual channels can be turned on and off.  (If telemetry is off,
  21 the per-channel setting has no effect.)
  22
  23 * **basic** (default: on): Basic information about the cluster
  24
  25     - capacity of the cluster
  26     - number of monitors, managers, OSDs, MDSs, object gateways, or other daemons
  27     - software version currently being used
  28     - number and types of RADOS pools and CephFS file systems
  29     - names of configuration options that have been changed from their
  30       default (but *not* their values)
  31
  32 * **crash** (default: on): Information about daemon crashes, including
  33
  34     - type of daemon
  35     - version of the daemon
  36     - operating system (OS distribution, kernel version)
  37     - stack trace identifying where in the Ceph code the crash occurred
  38
  39 * **device** (default: on): Information about device metrics, including
  40
  41     - anonymized SMART metrics
  42
  43 * **ident** (default: off): User-provided identifying information about
  44   the cluster
  45
  46     - cluster description
  47     - contact email address
  48
  49 The data being reported does *not* contain any sensitive
  50 data like pool names, object names, object contents, hostnames, or device
  51 serial numbers.
  52
  53 It contains counters and statistics on how the cluster has been
  54 deployed, the version of Ceph, the distribution of the hosts and other
  55 parameters which help the project to gain a better understanding of
  56 the way Ceph is used.
  57
  58 Data is sent secured to *https://telemetry.ceph.com*.
  59
  60 Sample report
  61 -------------
  62
  63 You can look at what data is reported at any time with the command::
  64
  65   ceph telemetry show
  66
  67 To protect your privacy, device reports are generated separately, and data such
  68 as hostname and device serial number is anonymized. The device telemetry is
  69 sent to a different endpoint and does not associate the device data with a
  70 particular cluster. To see a preview of the device report use the command::
  71
  72   ceph telemetry show-device
  73
  74 Please note: In order to generate the device report we use Smartmontools
  75 version 7.0 and up, which supports JSON output.
  76 If you have any concerns about privacy with regard to the information included in
  77 this report, please contact the Ceph developers.
  78
  79 Channels
  80 --------
  81
  82 Individual channels can be enabled or disabled with::
  83
  84   ceph config set mgr mgr/telemetry/channel_ident false
  85   ceph config set mgr mgr/telemetry/channel_basic false
  86   ceph config set mgr mgr/telemetry/channel_crash false
  87   ceph config set mgr mgr/telemetry/channel_device false
  88   ceph telemetry show
  89   ceph telemetry show-device
  90
  91 Enabling Telemetry
  92 ------------------
  93
  94 To allow the *telemetry* module to start sharing data::
  95
  96   ceph telemetry on
  97
  98 Please note: Telemetry data is licensed under the Community Data License
  99 Agreement - Sharing - Version 1.0 (https://cdla.io/sharing-1-0/). Hence,
 100 telemetry module can be enabled only after you add '--license sharing-1-0' to
 101 the 'ceph telemetry on' command.
 102
 103 Telemetry can be disabled at any time with::
 104
 105   ceph telemetry off
 106
 107 Interval
 108 --------
 109
 110 The module compiles and sends a new report every 24 hours by default.
 111 You can adjust this interval with::
 112
 113   ceph config set mgr mgr/telemetry/interval 72    # report every three days
 114
 115 Status
 116 --------
 117
 118 The see the current configuration::
 119
 120   ceph telemetry status
 121
 122 Manually sending telemetry
 123 --------------------------
 124
 125 To ad hoc send telemetry data::
 126
 127   ceph telemetry send
 128
 129 In case telemetry is not enabled (with 'ceph telemetry on'), you need to add
 130 '--license sharing-1-0' to 'ceph telemetry send' command.
 131
 132 Sending telemetry through a proxy
 133 ---------------------------------
 134
 135 If the cluster cannot directly connect to the configured telemetry
 136 endpoint (default *telemetry.ceph.com*), you can configure a HTTP/HTTPS
 137 proxy server with::
 138
 139   ceph config set mgr mgr/telemetry/proxy https://10.0.0.1:8080
 140
 141 You can also include a *user:pass* if needed::
 142
 143   ceph config set mgr mgr/telemetry/proxy https://ceph:telemetry@10.0.0.1:8080
 144
 145
 146 Contact and Description
 147 -----------------------
 148
 149 A contact and description can be added to the report.  This is
 150 completely optional, and disabled by default.::
 151
 152   ceph config set mgr mgr/telemetry/contact 'John Doe <john.doe@example.com>'
 153   ceph config set mgr mgr/telemetry/description 'My first Ceph cluster'
 154   ceph config set mgr mgr/telemetry/channel_ident true
 155