diff options
Diffstat (limited to '')
| -rw-r--r-- | modules/monitoring/doc/20-Hooks.md | 161 |
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> + + + +## 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; + } +} +``` |