diff --git a/README.md b/README.md index 8b3b529..54a1206 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) @@ -19,7 +19,7 @@ the monitoring module. ## Documentation -* [Installation](doc/02-Installation.md) -* [Configuration](doc/03-Configuration.md) -* [Templates](doc/04-Templates.md) -* [Development](doc/06-Development.md) +* [Installation](https://icinga.com/docs/icinga-web-graphite-integration/latest/doc/02-Installation/) +* [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/) diff --git a/doc/01-About.md b/doc/01-About.md index 36e250b..01e012f 100644 --- a/doc/01-About.md +++ b/doc/01-About.md @@ -1,7 +1,7 @@ -# 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 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..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 (>= 2.9) -* Icinga Web 2 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: - * 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 Graphite Module - -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) + 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/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 94cd8a6..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 - This module integrates an existing Graphite installation in your Icinga Web 2 +Description: Icinga Web Graphite Integration + This module integrates an existing Graphite installation in your Icinga Web frontend.