summaryrefslogtreecommitdiffstats
path: root/modules/monitoring/doc/20-Hooks.md
diff options
context:
space:
mode:
Diffstat (limited to '')
-rw-r--r--modules/monitoring/doc/20-Hooks.md161
1 files changed, 161 insertions, 0 deletions
diff --git a/modules/monitoring/doc/20-Hooks.md b/modules/monitoring/doc/20-Hooks.md
new file mode 100644
index 0000000..5d38843
--- /dev/null
+++ b/modules/monitoring/doc/20-Hooks.md
@@ -0,0 +1,161 @@
+# Monitoring Module Hooks <a id="monitoring-module-hooks"></a>
+
+## Detail View Extension Hook <a id="monitoring-module-hooks-detailviewextension"></a>
+
+This hook can be used to easily extend the detail view of monitored objects (hosts and services).
+
+### How it works <a id="monitoring-module-hooks-detailviewextension-how-it-works"></a>
+
+#### Directory structure <a id="monitoring-module-hooks-detailviewextension-directory-structure"></a>
+
+* `icingaweb2/modules/example`
+ * `library/Example/ProvidedHook/Monitoring/DetailviewExtension/Simple.php`
+ * `run.php`
+
+#### Files <a id="monitoring-module-hooks-detailviewextension-files"></a>
+
+##### run.php <a id="monitoring-module-hooks-detailviewextension-files-run-php"></a>
+
+```php
+<?php
+/** @var \Icinga\Application\Modules\Module $this */
+
+$this->provideHook(
+ 'monitoring/DetailviewExtension',
+ 'Icinga\Module\Example\ProvidedHook\Monitoring\DetailviewExtension\Simple'
+);
+```
+
+##### Simple.php <a id="monitoring-module-hooks-detailviewextension-files-simple-php"></a>
+
+```php
+<?php
+namespace Icinga\Module\Example\ProvidedHook\Monitoring\DetailviewExtension;
+
+use Icinga\Module\Monitoring\Hook\DetailviewExtensionHook;
+use Icinga\Module\Monitoring\Object\MonitoredObject;
+
+class Simple extends DetailviewExtensionHook
+{
+ public function getHtmlForObject(MonitoredObject $object)
+ {
+ $stats = array();
+ foreach (str_split($object->name) as $c) {
+ if (isset($stats[$c])) {
+ ++$stats[$c];
+ } else {
+ $stats[$c] = 1;
+ }
+ }
+
+ ksort($stats);
+
+ $view = $this->getView();
+
+ $thead = '';
+ $tbody = '';
+ foreach ($stats as $c => $amount) {
+ $thead .= '<th>' . $view->escape($c) . '</th>';
+ $tbody .= '<td>' . $amount . '</td>';
+ }
+
+ return '<h2>'
+ . $view->escape(sprintf($view->translate('A %s named "%s"'), $object->getType(), $object->name))
+ . '</h2>'
+ . '<h3>Character stats</h3>'
+ . '<table>'
+ . '<thead>' . $thead . '</thead>'
+ . '<tbody>' . $tbody . '</tbody>'
+ . '</table>';
+ }
+}
+```
+
+### How it looks <a id="monitoring-module-hooks-detailviewextension-how-it-looks"></a>
+
+![Screenshot](img/hooks-detailviewextension-01.png)
+
+## Plugin Output Hook <a id="monitoring-module-hooks-pluginoutput"></a>
+
+The Plugin Output Hook allows you to rewrite the plugin output based on check commands. You have to implement the
+following methods:
+
+* `getCommands()`
+* and `render()`
+
+With `getCommands()` you specify for which commands the provided hook is responsible for. You may return a single
+command as string or a list of commands as array. If you want your hook to be responsible for every command, you have to
+specify the `*`.
+
+In `render()` you rewrite the plugin output based on check commands. The parameter `$command` specifies the check
+command of the host or service and `$output` specifies the plugin output. The parameter `$detail` tells you
+whether the output is requested from the detail area of the host or service.
+
+Do not use complex logic for rewriting plugin output in list views because of the performance impact!
+
+You have to return the rewritten plugin output as string. It is also possible to return a HTML string here.
+Please refer to `\Icinga\Module\Monitoring\Web\Helper\PluginOutputPurifier` for a list of allowed tags.
+
+Please also have a look at the following examples.
+
+**Example hook which is responsible for disk checks:**
+
+```php
+<?php
+
+namespace Icinga\Module\Example\ProvidedHook\Monitoring;
+
+use Icinga\Module\Monitoring\Hook\PluginOutputHook;
+
+class PluginOutput extends PluginOutputHook
+{
+ public function getCommands()
+ {
+ return ['disk'];
+ }
+
+ public function render($command, $output, $detail)
+ {
+ if (! $detail) {
+ // Don't rewrite plugin output in list views
+ return $output;
+ }
+ return implode('<br>', explode(';', $output));
+ }
+}
+```
+
+**Example hook which is responsible for disk and procs checks:**
+
+```php
+<?php
+
+namespace Icinga\Module\Example\ProvidedHook\Monitoring;
+
+use Icinga\Module\Monitoring\Hook\PluginOutputHook;
+
+class PluginOutput extends PluginOutputHook
+{
+ public function getCommands()
+ {
+ return ['disk', 'procs'];
+ }
+
+ public function render($command, $output, $detail)
+ {
+ switch ($command) {
+ case 'disk':
+ if ($detail) {
+ // Only rewrite plugin output in the detail area
+ $output = implode('<br>', explode(';', $output));
+ }
+ break;
+ case 'procs':
+ $output = preg_replace('/(\d)+/', '<b>$1</b>', $output);
+ break;
+ }
+
+ return $output;
+ }
+}
+```