diff --git a/doc/110-Installation/40-Grafana-Integration.md b/doc/110-Installation/40-Grafana-Integration.md index e936a3e..8a05f95 100644 --- a/doc/110-Installation/40-Grafana-Integration.md +++ b/doc/110-Installation/40-Grafana-Integration.md @@ -11,8 +11,46 @@ To use Icinga for Windows Grafana Dashboards, you require the following componen * [Icinga Web Grafana Module](https://github.com/Mikesch-mp/icingaweb2-module-grafana) * [Icinga InfluxDB 2 Writer Feature enabled](https://icinga.com/docs/icinga-2/latest/doc/09-object-types/#influxdb2writer) +Please note that dashboards might also work with older Grafana versions (like version 8.x or 7.x), but wasn't tested with those versions. + ## Installation +### Install Grafana Dashboards + +Each plugin repository ships with a bunch of `.json` files, containing the configuration for the Grafana dashboards. These are located inside `config/grafana/dashboards/`. + +To `Import` these dashboards, you simply have to navigate to `Dashboards` -> `Import` inside Grafana + +![Import Dashboards](../images/05_installation/01_grafana/01_import_dashboard.png) + +On the section `Import via panel json`, copy the content of the `.json` file you wish to import or select the file to import. Repeat this process for each single file. There is currently no option to import multiple files at once. + +### Update Dashboard Configuration + +Last but not least, we require to update each Grafana dashboard to properly use your `InfluxDB 2` `Bucket` for the monitoring data collected by `Icinga`, unless your default Icinga monitoring bucket is called `icinga2`. + +To do so, open the dashboard you want to `edit` and hit the settings icon ![Import Dashboards](../images/05_installation/01_grafana/02_settings_icon.png) on the top right of the window. + +Now on the left side, click on `Variables` and search for the variable `influxbucket` on the right side. Click on the table entry with the name `influxbucket` and modify the `Constant options` `Value` with the name of the `InfluxDB 2` `Bucket`, your `Icinga` is writing monitoring metrics into. + +### Set InfluxDB Backend as default + +In case you are running multiple backends or require to save a certain backend as default, you can simply update each dashboard by selecting the correct InfluxDB backend for the variable `InfluxDB DataSource`. + +Once selected, head over to the save icon ![Save Icon](../images/05_installation/01_grafana/04_save_icon.png) on the top right side, click on it and afterwards select the checkbox `Save current variable values as dashboard default` and click on `Save`. + +![Save Dashboard](../images/05_installation/01_grafana/05_save_dashboard.png) + +Once done, this backend will be used whenever you load the dashboard. This is especially required for the below Icinga Web integration, ensuring that information can be fetched. + +### Updating Dashboards + +We do not recommend to manually modify or change on how the dashboards display metrics or extend them. You can use our dashboards as templates or provide pull requests/feature request on the component repositories. + +Icinga will provide frequent updates for the dashboards, which will overwrite your manual changes. + +To update new provided dashboards, you will have to delete the dashboard and import it again as described above. + ### Install Icinga Web Module By default, you have to install the [Icinga Web Grafana Module](https://github.com/Mikesch-mp/icingaweb2-module-grafana) into @@ -37,13 +75,13 @@ You can either edit the configuration for the module within Icinga Web or edit t ``` [grafana] host = "grafana.example.com:3000" -protocol = "https" +protocol = "http" timerangeAll = "1w/w" defaultdashboarduid = "QsPVl5W4z" defaultdashboardpanelid = "1" shadows = "0" theme = "dark" -datasource = "" +datasource = "influxdb" accessmode = "iframe" debug = "0" defaultdashboard = "windows-plugins-web" @@ -51,10 +89,10 @@ defaultorgid = "1" ssl_verifypeer = "0" ssl_verifyhost = "0" custvardisable = "" -timerange = "3h" +timerange = "1h" ``` -Please update the fields `host`, `datasource` and possibly `custvardisable` accordingly. The `defaultdashboarduid` with value `QsPVl5W4z` is the Icinga for Windows Base-Template, while the `defaultdashboard` with `windows-plugins-web` is the name. +Please update the field `host` accordingly. The `defaultdashboarduid` with value `QsPVl5W4z` is the Icinga for Windows `Windows-Plugins-Web`-Template id, while the `defaultdashboard` with `windows-plugins-web` is the name. ### Install Icinga for Windows Graphs @@ -68,24 +106,6 @@ The default location is /etc/icingaweb2/modules/grafana/graphs.ini ``` -### Install Grafana Dashboards - -Each plugin repository ships with a bunch of `.json` files, containing the configuration for the Grafana dashboards. These are located inside `config/grafana/dashboards/`. - -To `Import` these dashboards, you simply have to navigate to `Dashboards` -> `Import` inside Grafana - -![Import Dashboards](../images/05_installation/01_grafana/01_import_dashboard.png) - -On the section `Import via panel json`, copy the content of the `.json` file you wish to import. Repeat this process for each single file. There is currently no option to import multiple files at onces. - -### Update Dashboard Configuration - -Last but not least, we require to update each Grafana dashboard to properly use your `InfluxDB 2` `Bucket` for the monitoring data collected by `Icinga`. - -To do so, open the dashboard you want to `edit` and hit the settings icon ![Import Dashboards](../images/05_installation/01_grafana/02_settings_icon.png) on the top right of the window. - -Now on the left side, click on `Variables` and search for the variable `influxbucket` on the right side. Click on the table entry with the name `influxbucket` and modify the `Constant options` `Value` with the name of the `InfluxDB 2` `Bucket`, your `Icinga` is writing monitoring metrics into. - ### Overview Once all above steps are successfully completed, you can have a look on your Grafana dashboards diff --git a/doc/images/05_installation/01_grafana/03_example_overview.png b/doc/images/05_installation/01_grafana/03_example_overview.png index 357ad4f..0be3f31 100644 Binary files a/doc/images/05_installation/01_grafana/03_example_overview.png and b/doc/images/05_installation/01_grafana/03_example_overview.png differ diff --git a/doc/images/05_installation/01_grafana/04_save_icon.png b/doc/images/05_installation/01_grafana/04_save_icon.png new file mode 100644 index 0000000..217228b Binary files /dev/null and b/doc/images/05_installation/01_grafana/04_save_icon.png differ diff --git a/doc/images/05_installation/01_grafana/05_save_dashboard.png b/doc/images/05_installation/01_grafana/05_save_dashboard.png new file mode 100644 index 0000000..c34cc19 Binary files /dev/null and b/doc/images/05_installation/01_grafana/05_save_dashboard.png differ