Deploymentcenter/src/Modules/Supervisor/Catalog.php

<?php

declare(strict_types=1);

namespace Deploymentcenter\Modules\Supervisor;

/**
 * Der Detektor-Katalog.
 *
 * Legt fest, wonach der Supervisor sucht - unter Namen, die in jedem Projekt
 * dieselben sind. Das ist der eigentliche Zweck: Befunde aus verschiedenen
 * Anwendungen muessen vergleichbar bleiben, sonst ist die Sammlung nur ein
 * Haufen Text.
 *
 * Ein Name hat die Form "familie.sache" und wandert nie mehr. Aendert sich,
 * wonach gesucht wird, bekommt es einen neuen Namen - ein umbenannter Detektor
 * zerreisst jede Auswertung, die ueber den Zeitpunkt der Umbenennung
 * hinausgeht.
 *
 * Zur Einordnung, warum das mehr ist als "Unit-Tests zur Laufzeit": Ein Test
 * prueft bekannte Logik gegen bekannte Eingaben in einer kontrollierten
 * Umgebung. Die Detektoren hier pruefen gegen unbekannte Eingaben in einer
 * unbekannten Umgebung, ueber Zeitraeume, die ein Testlauf nicht herstellen
 * kann, und - die Gruppe NOVEL/SILENCE/DEVIATION - ohne den gesuchten Fehler
 * vorher zu kennen.
 */
final class Catalog
{
    /**
     * Woher kommt ein Befund?
     *
     * SERVER - hier ermittelt, aus Daten, die ohnehin hereinkommen
     *          (Fehlerberichte, Heartbeats, Kennzahlen). Laeuft von selbst.
     *
     * CLIENT - von aussen ueber POST /api/supervisor/v1/observe eingeliefert.
     *          Der Name ist historisch: Gedacht war urspruenglich ein
     *          Beobachter im ausgelieferten Programm. Den gibt es nicht mehr -
     *          er haette zu viele Baustellen aufgemacht, und Error-Reporting
     *          und Bugtracker decken den Zweck ohnehin ab. Wer heute
     *          einliefert, sind Pruefwerkzeuge und Testlaeufe.
     *
     * Der Wert "client" bleibt, weil er so in supervisor_findings.origin
     * steht; eine Umbenennung waere eine Migration ohne Gegenwert.
     */
    public const ORIGIN_CLIENT = 'client';
    public const ORIGIN_SERVER = 'server';

    /**
     * Der Katalog.
     *
     * origin  - wer den Befund erzeugt
     * needs   - was der Detektor braucht, damit er ueberhaupt etwas sagen kann
     * finds   - wonach er sucht, in einem Satz
     *
     * @var array<string,array{origin:string,finds:string,needs:string}>
     */
    public const DETECTORS = [

        // ------------------------------------------------------------------
        // Findet Dinge, an die niemand gedacht hat
        // ------------------------------------------------------------------
        // Diese Gruppe braucht kein Vorwissen ueber den konkreten Fehler. Der
        // Massstab kommt nicht aus einem Kopf, sondern aus der Wirklichkeit:
        // aus dem eigenen Verlauf, aus der Vorversion, aus den anderen
        // Installationen derselben Fassung.

        'novel.error_signature' => [
            'origin' => self::ORIGIN_SERVER,
            'finds'  => 'Fehlersignatur, die es in dieser Fassung noch nie gab',
            'needs'  => 'Fehler-Stream (bugtracker_items mit error_level)',
        ],
        'novel.log_template' => [
            'origin' => self::ORIGIN_SERVER,
            'finds'  => 'Logzeilen-Schablone, die noch nie auftrat',
            'needs'  => 'Logauszuege im Fehler-Stream',
        ],
        'silence.periodic' => [
            'origin' => self::ORIGIN_CLIENT,
            'finds'  => 'Bekanntes wiederkehrendes Ereignis bleibt aus - der still gestorbene Hintergrundjob',
            'needs'  => 'Ein Melder, der das Ereignis bestaetigt, solange es stattfindet',
        ],
        'silence.heartbeat' => [
            'origin' => self::ORIGIN_SERVER,
            'finds'  => 'Instanz meldet sich nicht mehr',
            'needs'  => 'Watchdog-Monitor',
        ],
        'deviation.self' => [
            'origin' => self::ORIGIN_SERVER,
            'finds'  => 'Abweichung vom eigenen Verlauf der letzten Tage',
            'needs'  => 'Kennzahlen im MetricStore, mindestens 30 Messpunkte aelter als zwei Stunden',
        ],
        'deviation.fleet' => [
            'origin' => self::ORIGIN_SERVER,
            'finds'  => 'Ausreisser gegenueber anderen Installationen derselben Fassung',
            'needs'  => 'mehrere Installationen mit derselben app_version',
        ],
        'regression.build' => [
            'origin' => self::ORIGIN_SERVER,
            'finds'  => 'Kennzahl verschiebt sich nach einem Update gegenueber der Vorgaengerfassung',
            'needs'  => 'app_version am Monitor und Kennzahlen ueber den Rollout hinweg',
        ],

        // ------------------------------------------------------------------
        // Die Zeitachse
        // ------------------------------------------------------------------
        // Ein Test laeuft Millisekunden auf frischem Zustand, ein
        // Kundenprozess Wochen. Alles, was sich ansammelt, ist fuer Tests
        // strukturell unsichtbar.

        'trend.monotonic' => [
            'origin' => self::ORIGIN_CLIENT,
            'finds'  => 'Kennzahl waechst ueber mehrere Fenster nur nach oben - Speicher-, Handle-, Cache-Leck',
            'needs'  => 'Eine Messreihe ueber Stunden, von wem auch immer gemeldet',
        ],
        'trend.saturation' => [
            'origin' => self::ORIGIN_CLIENT,
            'finds'  => 'Kennzahl naehert sich einer harten Grenze - Platte, Verbindungspool, Dateihandles',
            'needs'  => 'bekannte Obergrenze',
        ],
        'trend.latency' => [
            'origin' => self::ORIGIN_CLIENT,
            'finds'  => 'Antwortzeiten driften ueber Tage nach oben - etwa Index-Degradation',
            'needs'  => 'Zeitmessung an einer wiederkehrenden Operation, regelmaessig gemeldet',
        ],

        // ------------------------------------------------------------------
        // Stellen, an denen still verziehen wird
        // ------------------------------------------------------------------
        // Der ergiebigste und billigste Fang: Zaehler auf die Stellen, an
        // denen die Software heute schon still verzeiht. Dort sitzen die
        // Fehler, die niemand meldet.

        'swallowed.exception' => [
            'origin' => self::ORIGIN_CLIENT,
            'finds'  => 'catch-Bloecke, die einen Fehler schlucken und weitermachen',
            'needs'  => 'Ein Melder an den catch-Bloecken, die einen Fehler schlucken',
        ],
        'fallback.usage' => [
            'origin' => self::ORIGIN_CLIENT,
            'finds'  => 'Rueckfall auf den degradierten Pfad haeuft sich',
            'needs'  => 'Ein Melder im Ausweichzweig',
        ],
        'retry.storm' => [
            'origin' => self::ORIGIN_CLIENT,
            'finds'  => 'Wiederholungsversuche haeufen sich',
            'needs'  => 'Ein Melder an der Wiederholung',
        ],
        'probe.failed' => [
            'origin' => self::ORIGIN_CLIENT,
            'finds'  => 'Registrierte Probe schlaegt fehl',
            'needs'  => 'Ein Pruefwerkzeug, das die Pruefung ausfuehrt und das Ergebnis meldet',
        ],
        'probe.slow' => [
            'origin' => self::ORIGIN_CLIENT,
            'finds'  => 'Probe antwortet, aber deutlich langsamer als ueblich',
            'needs'  => 'Wie probe.failed, zusaetzlich mit Zeitmessung',
        ],

        // ------------------------------------------------------------------
        // Fachliche Zusicherungen
        // ------------------------------------------------------------------
        // Die einzige Gruppe, die tatsaechlich "Unit-Test zur Laufzeit" ist -
        // und fuer ihren Zweck ist genau das richtig. Sie deckt die Klasse ab,
        // die sonst komplett durchfaellt: semantisch falsche, aber
        // unauffaellige Ergebnisse. Der Bericht zeigt eine falsche Zahl, die
        // Rundung stimmt seit Monaten nicht, ein Mandant sieht Daten eines
        // anderen. Nichts stuerzt ab, keine Kennzahl weicht ab, keine Signatur
        // ist neu - kein anderer Detektor sieht das.

        'invariant.violated' => [
            'origin' => self::ORIGIN_CLIENT,
            'finds'  => 'Vom Projekt formulierte Zusicherung gegen echte Daten verletzt',
            'needs'  => 'Ein Melder, der die Zusicherung gegen echte Daten prueft',
        ],
    ];

    /** @return list<string> */
    public static function names(): array
    {
        return array_keys(self::DETECTORS);
    }

    public static function isKnown(string $detector): bool
    {
        return isset(self::DETECTORS[$detector]);
    }

    /**
     * Wo entsteht dieser Befund normalerweise?
     *
     * Unbekannte Detektoren gelten als clientseitig - ein Projekt darf einen
     * eigenen Namen melden, ohne dass der Katalog dafuer erweitert werden
     * muss. Es taucht dann in der Auswertung als eigene Reihe auf und faellt
     * beim Durchsehen auf, statt still verworfen zu werden.
     */
    public static function originOf(string $detector): string
    {
        return self::DETECTORS[$detector]['origin'] ?? self::ORIGIN_CLIENT;
    }

    /**
     * Nur die Detektoren einer Herkunft.
     *
     * @return array<string,array{origin:string,finds:string,needs:string}>
     */
    public static function byOrigin(string $origin): array
    {
        return array_filter(
            self::DETECTORS,
            static fn(array $meta): bool => $meta['origin'] === $origin
        );
    }
}