From ee0313afe1a484c5b9ef16664cafe7b1eb641ebb Mon Sep 17 00:00:00 2001 From: "Alexander A. Klimov" Date: Thu, 22 Sep 2022 11:09:24 +0200 Subject: [PATCH 1/4] Docs: s/Icinga Web 2/Icinga Web/ --- doc/01-About.md | 2 +- doc/02-Installation.md | 6 +++--- doc/03-Configuration.md | 4 ++-- module.info | 2 +- 4 files changed, 7 insertions(+), 7 deletions(-) diff --git a/doc/01-About.md b/doc/01-About.md index 36e250b..23f44bb 100644 --- a/doc/01-About.md +++ b/doc/01-About.md @@ -1,7 +1,7 @@ # Icinga Module for Graphite This module integrates an existing [Graphite](https://graphite.readthedocs.io/en/latest/) -installation in your [Icinga Web 2](https://icinga.com/products/infrastructure-monitoring/) +installation in your [Icinga Web](https://icinga.com/products/infrastructure-monitoring/) frontend. ![Service List](img/service-list.png) | ![Detail View](img/service-detail-view.png) diff --git a/doc/02-Installation.md b/doc/02-Installation.md index f8ab9bf..53ed288 100644 --- a/doc/02-Installation.md +++ b/doc/02-Installation.md @@ -3,11 +3,11 @@ ## Requirements * PHP (>= 7.2) -* Icinga Web 2 (>= 2.9) -* Icinga Web 2 libraries: +* Icinga Web (>= 2.9) +* Icinga Web libraries: * [Icinga PHP Library (ipl)](https://github.com/Icinga/icinga-php-library) (>= 0.9) * [Icinga PHP Thirdparty](https://github.com/Icinga/icinga-php-thirdparty) (>= 0.11) -* Icinga Web 2 modules: +* Icinga Web modules: * The `monitoring` or `icingadb` module needs to be configured and enabled. * Graphite and Graphite Web diff --git a/doc/03-Configuration.md b/doc/03-Configuration.md index fc8dcf9..0b2a38d 100644 --- a/doc/03-Configuration.md +++ b/doc/03-Configuration.md @@ -2,7 +2,7 @@ ## Basics -Open up the Icinga Web 2 frontend and navigate to: +Open up the Icinga Web frontend and navigate to: `Configuration > Modules > graphite > Backend` @@ -13,7 +13,7 @@ if your Graphite Web is protected by such a mechanism. ## Advanced -Open up the Icinga Web 2 frontend and navigate to: +Open up the Icinga Web frontend and navigate to: `Configuration > Modules > graphite > Advanced` diff --git a/module.info b/module.info index 94cd8a6..51dfee0 100644 --- a/module.info +++ b/module.info @@ -4,5 +4,5 @@ Requires: Libraries: icinga-php-library (>=0.9.0), icinga-php-thirdparty (>=0.10.0) Modules: monitoring (>=2.9.0), icingadb (>=1.0.0) Description: Icinga Graphite module - This module integrates an existing Graphite installation in your Icinga Web 2 + This module integrates an existing Graphite installation in your Icinga Web frontend. From c916738ab1bed789809d2d54b863e069fadb6bd4 Mon Sep 17 00:00:00 2001 From: "Alexander A. Klimov" Date: Thu, 22 Sep 2022 12:40:12 +0200 Subject: [PATCH 2/4] Docs: s/Graphite Module/Icinga Web Graphite Integration/ --- README.md | 2 +- doc/01-About.md | 2 +- doc/02-Installation.md | 2 +- doc/04-Templates.md | 14 +++++++------- doc/05-Troubleshooting.md | 11 ++++++----- doc/06-Development.md | 6 +++--- module.info | 2 +- 7 files changed, 20 insertions(+), 19 deletions(-) diff --git a/README.md b/README.md index 8b3b529..707733e 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -# Icinga Module for Graphite +# Icinga Web Graphite Integration [![PHP Support](https://img.shields.io/badge/php-%3E%3D%207.2-777BB4?logo=PHP)](https://php.net/) ![Build Status](https://github.com/icinga/icingaweb2-module-graphite/workflows/PHP%20Tests/badge.svg?branch=master) diff --git a/doc/01-About.md b/doc/01-About.md index 23f44bb..01e012f 100644 --- a/doc/01-About.md +++ b/doc/01-About.md @@ -1,4 +1,4 @@ -# Icinga Module for Graphite +# Icinga Web Graphite Integration This module integrates an existing [Graphite](https://graphite.readthedocs.io/en/latest/) installation in your [Icinga Web](https://icinga.com/products/infrastructure-monitoring/) diff --git a/doc/02-Installation.md b/doc/02-Installation.md index 53ed288..75d7f40 100644 --- a/doc/02-Installation.md +++ b/doc/02-Installation.md @@ -34,7 +34,7 @@ However, some templates look better if they are able to render a max value or similar. -## Install the Graphite Module +## Install the Icinga Web Graphite Integration Install it [like any other module](https://icinga.com/docs/icinga-web-2/latest/doc/08-Modules/#installation). Use `graphite` as name. diff --git a/doc/04-Templates.md b/doc/04-Templates.md index bccd45b..5acbae1 100644 --- a/doc/04-Templates.md +++ b/doc/04-Templates.md @@ -1,8 +1,8 @@ # Templates A template defines what kind of data a graph visualizes, which kind of graph to -use and its style. Essentially this module is using templates to tell Graphite -how to render which graphs. +use and its style. Essentially the Icinga Web Graphite Integration is using +templates to tell Graphite how to render which graphs. * [Location](04-Templates.md#templates-location) * [Structure](04-Templates.md#templates-structure) @@ -15,8 +15,8 @@ how to render which graphs. ## Template Location -There are a bunch of templates already shipped with this module, located in -its installation path. (e.g. `/usr/share/icingaweb2/modules/graphite`) +There are a bunch of templates already included, located in +the installation path. (e.g. `/usr/share/icingaweb2/modules/graphite`) To add additional/customized templates, place them in its configuration path. (e.g. `/etc/icingaweb2/modules/graphite/templates`) These will either extend @@ -26,7 +26,7 @@ templates of its parent folders. > **Note:** > -> Hidden files and directories (with a leading dot) are ignored by this module. +> Hidden files and directories (with a leading dot) are ignored. ## Template Structure @@ -115,8 +115,8 @@ here as well: title = "Disk usage on $disk$" -You may also define URL parameters once for all templates (including the ones -shipped with this module) in the `default_url_params` section in +You may also define URL parameters once for all templates +(including the shipped ones) in the `default_url_params` section in `/etc/icingaweb2/modules/graphite/config.ini`: [default_url_params] diff --git a/doc/05-Troubleshooting.md b/doc/05-Troubleshooting.md index df03d0d..11ef711 100644 --- a/doc/05-Troubleshooting.md +++ b/doc/05-Troubleshooting.md @@ -36,11 +36,12 @@ Example debug log for the host "icinga.com": ++ Not applying template 'default-service' ``` -The log describes how the Graphite module assembled the displayed graphs (or why -no graphs could be assembled). The plus signs indent the performed actions to -visualize their hierarchy, e.g. all actions below `Applying templates for check -command 'hostalive'` indented with more than one plus sign (until `Applying -default templates, (...)`) are sub-actions of the above one. +The log describes how the Icinga Web Graphite Integration assembled the +displayed graphs (or why no graphs could be assembled). The plus signs indent +the performed actions to visualize their hierarchy, e.g. all actions below +`Applying templates for check command 'hostalive'` indented with more than one +plus sign (until `Applying default templates, (...)`) are sub-actions of the +above one. #### Details diff --git a/doc/06-Development.md b/doc/06-Development.md index 103e0c9..bfa2a57 100644 --- a/doc/06-Development.md +++ b/doc/06-Development.md @@ -1,6 +1,6 @@ # Development -This module provides a CLI command for demonstrating +There is a CLI command for demonstrating graph templates (useful for developing them): ```bash @@ -11,5 +11,5 @@ It generates Icinga 2 config based on the present graph templates. With this config Icinga will (also) "monitor" dummy services yielding random perfdata as expected by the graph templates. -I. e.: If that Icinga is also writing to the Graphite that is -read by this module, you'll get dummy graphs for all templates. +I. e.: If that Icinga is also writing to the Graphite that is read by your +Icinga Web Graphite Integration, you'll get dummy graphs for all templates. diff --git a/module.info b/module.info index 51dfee0..9d406ec 100644 --- a/module.info +++ b/module.info @@ -3,6 +3,6 @@ Version: 1.2.1 Requires: Libraries: icinga-php-library (>=0.9.0), icinga-php-thirdparty (>=0.10.0) Modules: monitoring (>=2.9.0), icingadb (>=1.0.0) -Description: Icinga Graphite module +Description: Icinga Web Graphite Integration This module integrates an existing Graphite installation in your Icinga Web frontend. From bb7deb03aaf17afc912cfe4a6f3733454473ae52 Mon Sep 17 00:00:00 2001 From: "Alexander A. Klimov" Date: Thu, 22 Sep 2022 14:57:54 +0200 Subject: [PATCH 3/4] Docs: recommend to install from packages --- README.md | 2 +- doc/02-Installation.md | 43 +++++++++++++------------ doc/02-Installation.md.d/From-Source.md | 14 ++++++++ 3 files changed, 37 insertions(+), 22 deletions(-) create mode 100644 doc/02-Installation.md.d/From-Source.md diff --git a/README.md b/README.md index 707733e..75f7273 100644 --- a/README.md +++ b/README.md @@ -19,7 +19,7 @@ the monitoring module. ## Documentation -* [Installation](doc/02-Installation.md) +* [Installation](https://icinga.com/docs/icinga-web-graphite-integration/latest/doc/02-Installation/) * [Configuration](doc/03-Configuration.md) * [Templates](doc/04-Templates.md) * [Development](doc/06-Development.md) diff --git a/doc/02-Installation.md b/doc/02-Installation.md index 75d7f40..6850ecd 100644 --- a/doc/02-Installation.md +++ b/doc/02-Installation.md @@ -1,15 +1,24 @@ -# Installation + +# Installing Icinga Web Graphite Integration -## Requirements +It is recommended to use prebuilt packages +for all supported platforms from our official release repository. +Of course [Icinga Web](https://icinga.com/docs/icinga-web) itself +is required to run its Graphite integration. +The latter uses Graphite Web, so that is required as well. +If they are not already set up, it is best to do this first. -* PHP (>= 7.2) -* Icinga Web (>= 2.9) -* Icinga Web libraries: - * [Icinga PHP Library (ipl)](https://github.com/Icinga/icinga-php-library) (>= 0.9) - * [Icinga PHP Thirdparty](https://github.com/Icinga/icinga-php-thirdparty) (>= 0.11) -* Icinga Web modules: - * The `monitoring` or `icingadb` module needs to be configured and enabled. -* Graphite and Graphite Web +The following steps will guide you through installing +and setting up Icinga Web Graphite Integration. + + + +## Installing the Package + +If the [repository](https://packages.icinga.com) is not configured yet, please add it first. +Then use your distribution's package manager to install the `icinga-graphite` package +or install [from source](02-Installation.md.d/From-Source.md). + ## Prepare Icinga 2 @@ -33,15 +42,7 @@ And then restart Icinga2. Enabling thresholds is not a hard requirement. However, some templates look better if they are able to render a max value or similar. +## Configuring the Icinga Web Graphite Integration -## Install the Icinga Web Graphite Integration - -Install it [like any other module](https://icinga.com/docs/icinga-web-2/latest/doc/08-Modules/#installation). -Use `graphite` as name. - - -## Further reading - -* [Configuration](03-Configuration.md) -* [Templates](04-Templates.md) -* [Troubleshooting](05-Troubleshooting.md) +For required additional steps see the [Configuration](03-Configuration.md) chapter. + diff --git a/doc/02-Installation.md.d/From-Source.md b/doc/02-Installation.md.d/From-Source.md new file mode 100644 index 0000000..1433743 --- /dev/null +++ b/doc/02-Installation.md.d/From-Source.md @@ -0,0 +1,14 @@ +# Installing Icinga Web Graphite Integration from Source + +Please see the Icinga Web documentation on +[how to install modules](https://icinga.com/docs/icinga-web-2/latest/doc/08-Modules/#installation) from source. +Make sure you use `graphite` as the module name. The following requirements must also be met. + +## Requirements + +* PHP (≥7.2) +* [Icinga Web](https://github.com/Icinga/icingaweb2) (≥2.9) +* [Icinga DB Web](https://github.com/Icinga/icingadb-web) (≥1.0) +* [Icinga PHP Library (ipl)](https://github.com/Icinga/icinga-php-library) (≥0.9) +* [Icinga PHP Thirdparty](https://github.com/Icinga/icinga-php-thirdparty) (≥0.11) + From 7bf9e6fec5b8ba7454aef1ef8e328a5a99b5e15e Mon Sep 17 00:00:00 2001 From: "Alexander A. Klimov" Date: Thu, 27 Oct 2022 12:23:35 +0200 Subject: [PATCH 4/4] README.md: unify links --- README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 75f7273..54a1206 100644 --- a/README.md +++ b/README.md @@ -20,6 +20,6 @@ the monitoring module. ## Documentation * [Installation](https://icinga.com/docs/icinga-web-graphite-integration/latest/doc/02-Installation/) -* [Configuration](doc/03-Configuration.md) -* [Templates](doc/04-Templates.md) -* [Development](doc/06-Development.md) +* [Configuration](https://icinga.com/docs/icinga-web-graphite-integration/latest/doc/03-Configuration/) +* [Templates](https://icinga.com/docs/icinga-web-graphite-integration/latest/doc/04-Templates/) +* [Development](https://icinga.com/docs/icinga-web-graphite-integration/latest/doc/06-Development/)