ceph/doc/mgr/zabbix.rst

   1 Zabbix Module
   2 =============
   3
   4 The Zabbix module actively sends information to a Zabbix server like:
   5
   6 - Ceph status
   7 - I/O operations
   8 - I/O bandwidth
   9 - OSD status
  10 - Storage utilization
  11
  12 Requirements
  13 ------------
  14
  15 The module requires that the *zabbix_sender* executable is present on *all*
  16 machines running ceph-mgr. It can be installed on most distributions using
  17 the package manager.
  18
  19 Dependencies
  20 ^^^^^^^^^^^^
  21 Installing zabbix_sender can be done under Ubuntu or CentOS using either apt
  22 or dnf.
  23
  24 On Ubuntu Xenial:
  25
  26 ::
  27
  28     apt install zabbix-agent
  29
  30 On Fedora:
  31
  32 ::
  33
  34     dnf install zabbix-sender
  35
  36
  37 Enabling
  38 --------
  39 You can enable the *zabbix* module with:
  40
  41 ::
  42
  43     ceph mgr module enable zabbix
  44
  45 Configuration
  46 -------------
  47
  48 Two configuration keys are vital for the module to work:
  49
  50 - zabbix_host
  51 - identifier (optional)
  52
  53 The parameter *zabbix_host* controls the hostname of the Zabbix server to which
  54 *zabbix_sender* will send the items. This can be a IP-Address if required by
  55 your installation.
  56
  57 The *identifier* parameter controls the identifier/hostname to use as source
  58 when sending items to Zabbix. This should match the name of the *Host* in
  59 your Zabbix server.
  60
  61 When the *identifier* parameter is not configured the ceph-<fsid> of the cluster
  62 will be used when sending data to Zabbix.
  63
  64 This would for example be *ceph-c4d32a99-9e80-490f-bd3a-1d22d8a7d354*
  65
  66 Additional configuration keys which can be configured and their default values:
  67
  68 - zabbix_port: 10051
  69 - zabbix_sender: /usr/bin/zabbix_sender
  70 - interval: 60
  71
  72 Configuration keys
  73 ^^^^^^^^^^^^^^^^^^^
  74
  75 Configuration keys can be set on any machine with the proper cephx credentials,
  76 these are usually Monitors where the *client.admin* key is present.
  77
  78 ::
  79
  80     ceph zabbix config-set <key> <value>
  81
  82 For example:
  83
  84 ::
  85
  86     ceph zabbix config-set zabbix_host zabbix.localdomain
  87     ceph zabbix config-set identifier ceph.eu-ams02.local
  88
  89 The current configuration of the module can also be shown:
  90
  91 ::
  92
  93    ceph zabbix config-show
  94
  95
  96 Template
  97 ^^^^^^^^
  98 A `template <https://raw.githubusercontent.com/ceph/ceph/9c54334b615362e0a60442c2f41849ed630598ab/src/pybind/mgr/zabbix/zabbix_template.xml>`_.
  99 (XML) to be used on the Zabbix server can be found in the source directory of the module.
 100
 101 This template contains all items and a few triggers. You can customize the triggers afterwards to fit your needs.
 102
 103
 104 Multiple Zabbix servers
 105 ^^^^^^^^^^^^^^^^^^^^^^^
 106 It is possible to instruct zabbix module to send data to multiple Zabbix servers.
 107
 108 Parameter *zabbix_host* can be set with multiple hostnames separated by commas.
 109 Hosnames (or IP adderesses) can be followed by colon and port number. If a port
 110 number is not present module will use the port number defined in *zabbix_port*.
 111
 112 For example:
 113
 114 ::
 115
 116     ceph zabbix config-set zabbix_host "zabbix1,zabbix2:2222,zabbix3:3333"
 117
 118
 119 Manually sending data
 120 ---------------------
 121 If needed the module can be asked to send data immediately instead of waiting for
 122 the interval.
 123
 124 This can be done with this command:
 125
 126 ::
 127
 128     ceph zabbix send
 129
 130 The module will now send its latest data to the Zabbix server.
 131
 132 Debugging
 133 ---------
 134
 135 Should you want to debug the Zabbix module increase the logging level for
 136 ceph-mgr and check the logs.
 137
 138 ::
 139
 140     [mgr]
 141         debug mgr = 20
 142
 143 With logging set to debug for the manager the module will print various logging
 144 lines prefixed with *mgr[zabbix]* for easy filtering.