icingaweb2/modules/monitoring/doc/20-Hooks.md

Monitoring Module Hooks

Detail View Extension Hook

This hook can be used to easily extend the detail view of monitored objects (hosts and services).

How it works

Directory structure

• icingaweb2/modules/example
  • library/Example/ProvidedHook/Monitoring/DetailviewExtension/Simple.php
  • run.php

Files

run.php

<?php
/** @var \Icinga\Application\Modules\Module $this */

$this->provideHook(
    'monitoring/DetailviewExtension',
    'Icinga\Module\Example\ProvidedHook\Monitoring\DetailviewExtension\Simple'
);

Simple.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

Plugin Output Hook

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

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

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;
    }
}