ceph/monitoring/ceph-mixin/README.md

   1 ## Prometheus Monitoring Mixin for Ceph
   2 A set of Grafana dashboards and Prometheus alerts for Ceph.
   3
   4 All the Grafana dashboards are already generated in the `dashboards_out`
   5 directory and alerts in the `prometheus_alerts.yml` file.
   6
   7 You can use the Grafana dashboards and alerts with Jsonnet like any other
   8 prometheus mixin. You can find more resources about mixins in general on
   9 [monitoring.mixins.dev](https://monitoring.mixins.dev/).
  10
  11 ### Grafana dashboards for Ceph
  12 In `dashboards_out` you can find a collection of
  13 [Grafana](https://grafana.com/grafana) dashboards for Ceph Monitoring.
  14
  15 These dashboards are based on metrics collected
  16 from [prometheus](https://prometheus.io/) scraping the [prometheus mgr
  17 plugin](http://docs.ceph.com/en/latest/mgr/prometheus/) and the
  18 [node_exporter (0.17.0)](https://github.com/prometheus/node_exporter).
  19
  20
  21 ##### Recommended versions:
  22 -grafana 8.3.5
  23     -grafana-piechart-panel 1.6.2
  24     -grafana-status-panel 1.0.11
  25
  26 #### Requirements
  27
  28 - [Status Panel](https://grafana.com/plugins/vonage-status-panel) installed on
  29  your Grafana instance
  30 - [Pie Chart Panel](https://grafana.com/grafana/plugins/grafana-piechart-panel/)
  31  installed on your Grafana instance
  32
  33
  34 ### Prometheus alerts
  35 In `prometheus_alerts.libsonnet` you'll find a set of Prometheus
  36 alert rules that should provide a decent set of default alerts for a
  37 Ceph cluster. After building them with jsonnet put this file in place according to your Prometheus
  38 configuration (wherever the `rules` configuration stanza points).
  39
  40 ### Multi-cluster support
  41 Ceph-mixin supports dashboards and alerts across multiple clusters.
  42 To enable this feature you need to configure the following in `config.libsonnnet`:
  43
  44 ```
  45 showMultiCluster: true,
  46 clusterLabel: '<your cluster label>',
  47 ```
  48
  49 ##### Recommended versions:
  50 -prometheus v2.33.4
  51
  52 #### SNMP
  53 Ceph provides a MIB (CEPH-PROMETHEUS-ALERT-MIB.txt) to support sending
  54 Prometheus alerts to an SNMP management platform. The translation from
  55 Prometheus alert to SNMP trap requires the Prometheus alert to contain an OID
  56 that maps to a definition within the MIB. When making changes to the Prometheus
  57 alert rules file, developers should include any necessary changes to the MIB.
  58
  59
  60 ##### Recommended:
  61 -alertmanager 0.16.2
  62
  63 ### Building from Jsonnet
  64
  65 - Install [jsonnet](https://jsonnet.org/) (at least v0.18.0)
  66     - By installing the package `jsonnet` in most of the distro and
  67       `golang-github-google-jsonnet` in fedora
  68 - Install [jsonnet-bundler](https://github.com/jsonnet-bundler/jsonnet-bundler)
  69
  70 To rebuild all the generated files, you can run `tox -egrafonnet-fix`.
  71
  72 The jsonnet code located in this directory depends on some Jsonnet third party
  73 libraries. To update those libraries you can run `jb update` and then update
  74 the generated files using `tox -egrafonnet-fix`.
  75
  76 ##### Any upgrade or downgrade to different major versions of the recommended tools mentioned above is not supported.