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