feat(errors, watchdog): Fehler-Stream mit Ignore-Regeln, Metrik-Verlauf, Abhängigkeits-Alarme
Fehler-Schnittstelle - Neuer schlanker Eingang POST /api/errors/v1/report für den globalen Exception-Handler einer Anwendung. Titel und Dringlichkeit leitet der Server ab; gespeichert wird in derselben Tabelle wie der Bugtracker. Ein zweiter Speicher wäre nur ein zweiter Ort, an dem man suchen müsste. - error_level (fatal/error/warning) trennt die technische Art des Ereignisses von der geschäftlichen Dringlichkeit. Ein Duplicate-Entry ist technisch ein error, geschäftlich belanglos — beides zu vermischen war der Grund, warum solche Meldungen als Bug im Dashboard landeten. Ignore-Regeln gegen bekanntes Rauschen - bugtracker_ignore_rules mit contains/regex/exception_class, Pflichtfeld für die Begründung und optionaler Alarmschwelle. - Ein Treffer bedeutet nicht "wegwerfen": Der Fehler wird weiterhin erfasst und hochgezählt, bleibt aber aus der Übersicht heraus und löst keine Benachrichtigung aus. Der Zähler ist der eigentliche Zweck — dass ein bekannter Fehler auftritt, ist normal; dass er plötzlich hundertmal so oft auftritt, ist ein Signal. Dafür das rollende Stundenfenster und error.rate_exceeded. - Neue Regeln lassen sich rückwirkend auf bestehende Einträge anwenden. Gruppierung überarbeitet - Der Schlüssel nahm bisher 300 Zeichen Stacktrace auf. Derselbe Fehler zersplitterte dadurch, sobald ein Aufrufer den Stack einmal mitschickte und einmal nicht. Jetzt zählt der Ursprungsort: bevorzugt die Dateiangabe, sonst der erste Rahmen des Stacktrace. - Die Normalisierung ersetzte nur Zahlen ab vier Stellen, wodurch 'AA-1' und 'BB-2' getrennt blieben. Werte in Anführungszeichen, die Ziffern enthalten, gelten jetzt als veränderlich — der Schlüsselname bleibt erhalten, sodass verschiedene Unique-Keys unterscheidbar sind. Mit 9 Testfällen belegt. Metrik-Verlauf - watchdog_metrics speichert numerische Heartbeat-Werte mit Zeitstempel. Zuvor wurde metrics_json bei jedem Heartbeat überschrieben; damit ließ sich "die Platte läuft seit drei Tagen voll" nicht erkennen, nur "sie ist voll". - GET /api/watchdog/v1/metrics liefert den verdichteten Verlauf und die Abweichung vom eigenen Sieben-Tage-Durchschnitt. Dieser relative Ansatz braucht keine projektspezifischen Schwellwerte. - Aufbewahrung 14 Tage, Bereinigung stündlich durch den Evaluator. Health-Checks per Push statt Abruf - Der Heartbeat nimmt ein checks-Objekt entgegen, das die Anwendung selbst ermittelt. Das Deploymentcenter interpretiert die Namen nicht, es liest nur ok und message — was "gesund" bedeutet, entscheidet jede Anwendung selbst. Schlägt eine Prüfung fehl, wird ein als ok gemeldeter Heartbeat auf warning herabgestuft. - Bewusst ausgehend: auf den Zielmaschinen müssen keine Ports geöffnet werden. Abhängigkeitsbewusste Alarmierung - Fällt ein Monitor aus, dessen Parent selbst unten ist, wird der Alarm unterdrückt. Der Zustand bleibt sichtbar. Vorher erzeugte ein ausgefallener Hypervisor mit zwölf VMs dreizehn Meldungen für ein Problem. - Mehrere Ebenen und fehlerhafte Hierarchien (Zyklen, gelöschte Parents) sind abgesichert; mit 10 Testfällen belegt. WebUI - Neue Ansicht "Fehler-Stream" mit Filtern nach Projekt, Fehlerklasse, Umgebung, Zeitraum und Sichtbarkeit sowie Volltextsuche und Pagination. Stummgeschaltete Einträge sind standardmäßig ausgeblendet. - Verwaltung der Ignore-Regeln inklusive Trefferzähler. - Die Detailansicht zeigt Fehlerklasse, Stummschaltungsgrund und die Häufung im laufenden Stundenfenster. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
Deploymentcenter Bot
co-authored by
Claude Opus 5
Claude Opus 5
parent
a74c6fd990
commit
60e34b29f6
@@ -0,0 +1,162 @@
|
||||
<?php
|
||||
|
||||
/**
|
||||
* POST /api/errors/v1/report
|
||||
*
|
||||
* Schlanker Eingang fuer Laufzeitfehler. Gedacht fuer den globalen
|
||||
* Exception-Handler einer Anwendung: Es genuegen Ausnahmeklasse, Meldung und
|
||||
* Stacktrace - Titel, Typ und Dringlichkeit leitet der Server ab.
|
||||
*
|
||||
* Gespeichert wird in derselben Tabelle wie der Bugtracker. Ein zweiter
|
||||
* Speicher waere nur ein zweiter Ort, an dem man suchen muesste; die
|
||||
* Trennung von Rauschen und Signal leisten stattdessen die Ignore-Regeln.
|
||||
*
|
||||
* Beispiel:
|
||||
* curl -X POST https://dc.mhdf.de/api/errors/v1/report \
|
||||
* -H "Authorization: Bearer $DC_TOKEN" \
|
||||
* -H "Content-Type: application/json" \
|
||||
* -d '{"project_slug":"polytrader",
|
||||
* "exception":"PDOException",
|
||||
* "message":"SQLSTATE[23000]: Duplicate entry ...",
|
||||
* "stack_trace":"...",
|
||||
* "build":"v2.0.1",
|
||||
* "environment":"production"}'
|
||||
*/
|
||||
|
||||
declare(strict_types=1);
|
||||
|
||||
require_once __DIR__ . '/../../../../src/bootstrap.php';
|
||||
|
||||
use Deploymentcenter\Core\ApiAuth;
|
||||
use Deploymentcenter\Core\Config;
|
||||
use Deploymentcenter\Core\Db;
|
||||
use Deploymentcenter\Core\Http;
|
||||
use Deploymentcenter\Modules\Bugtracker\BugRepo;
|
||||
use Deploymentcenter\Modules\License\RateLimiter;
|
||||
|
||||
Http::beginJson(['POST', 'OPTIONS'], true);
|
||||
|
||||
if (Http::method() !== 'POST') {
|
||||
Http::fail(405, 'method_not_allowed', 'Dieser Endpunkt erwartet POST.');
|
||||
}
|
||||
|
||||
$db = Db::init();
|
||||
|
||||
// Fehler treten in Schueben auf. Das Limit liegt bewusst hoeher als beim
|
||||
// Bugtracker-Eingang, faengt aber eine Endlosschleife noch ab.
|
||||
$limiter = new RateLimiter($db, (int)Config::get('bugtracker.error_rate', 300), 60, 'error_report');
|
||||
if (!$limiter->check(Http::clientIp())) {
|
||||
Http::fail(429, 'rate_limited', 'Zu viele Fehlermeldungen. Bitte Sendefrequenz reduzieren.');
|
||||
}
|
||||
|
||||
$data = Http::body();
|
||||
if ($data === []) {
|
||||
Http::fail(400, 'empty_body', 'Der Request-Body ist leer.');
|
||||
}
|
||||
|
||||
$environment = is_string($data['environment'] ?? null) ? $data['environment'] : null;
|
||||
$context = ApiAuth::requireScope($db, 'bugtracker:report', $environment, false);
|
||||
|
||||
$projectSlug = is_string($data['project_slug'] ?? null) ? trim($data['project_slug']) : null;
|
||||
ApiAuth::enforceProject($context, $projectSlug);
|
||||
|
||||
$boundProject = ApiAuth::projectFilter($context);
|
||||
if ($boundProject !== null) {
|
||||
$projectSlug = $boundProject;
|
||||
}
|
||||
|
||||
// --- Eingaben normalisieren ---
|
||||
$exception = trimOrNull($data['exception'] ?? $data['exception_class'] ?? $data['type'] ?? null);
|
||||
$message = trimOrNull($data['message'] ?? $data['error_message'] ?? null);
|
||||
$stack = trimOrNull($data['stack_trace'] ?? $data['stacktrace'] ?? $data['trace'] ?? null);
|
||||
|
||||
if ($message === null && $exception === null) {
|
||||
Http::fail(400, 'missing_error', 'Es wird mindestens "message" oder "exception" benoetigt.');
|
||||
}
|
||||
|
||||
// fatal = Prozess beendet, error = Vorgang fehlgeschlagen, Programm laeuft weiter.
|
||||
$level = is_string($data['level'] ?? $data['error_level'] ?? null)
|
||||
? strtolower(trim($data['level'] ?? $data['error_level']))
|
||||
: 'error';
|
||||
if (!in_array($level, BugRepo::ERROR_LEVELS, true)) {
|
||||
$level = 'error';
|
||||
}
|
||||
|
||||
$repo = new BugRepo($db);
|
||||
|
||||
$result = $repo->reportItem([
|
||||
'project_slug' => $projectSlug ?? 'default',
|
||||
'type' => 'bug',
|
||||
'title' => buildTitle($exception, $message),
|
||||
'error_message' => $message,
|
||||
'stack_trace' => $stack,
|
||||
'exception' => $exception,
|
||||
'error_level' => $level,
|
||||
'severity' => $level === 'fatal' ? 'high' : 'medium',
|
||||
'environment' => $environment ?? 'production',
|
||||
'build_version' => trimOrNull($data['build'] ?? $data['build_version'] ?? null) ?? 'unknown',
|
||||
'created_by' => $context['actor'],
|
||||
'client_ref' => trimOrNull($data['client_ref'] ?? null) ?? Http::header('idempotency-key'),
|
||||
|
||||
// Optionaler Kontext - alles freiwillig
|
||||
'repo_url' => trimOrNull($data['repo_url'] ?? null),
|
||||
'git_branch' => trimOrNull($data['git_branch'] ?? null),
|
||||
'commit_sha' => trimOrNull($data['commit_sha'] ?? null),
|
||||
'file_path' => trimOrNull($data['file'] ?? $data['file_path'] ?? null),
|
||||
'line_no' => $data['line'] ?? $data['line_no'] ?? null,
|
||||
'tags' => trimOrNull($data['tags'] ?? null),
|
||||
'context' => isset($data['context']) && is_array($data['context']) ? $data['context'] : null,
|
||||
]);
|
||||
|
||||
$ignored = (bool)($result['ignored'] ?? false);
|
||||
|
||||
Http::ok([
|
||||
'item_id' => $result['id'],
|
||||
'is_new' => $result['is_new'],
|
||||
'ignored' => $ignored,
|
||||
'ignore_rule_id' => $result['ignore_rule_id'] ?? null,
|
||||
'occurrence_count' => $result['occurrence_count'],
|
||||
'error_level' => $level,
|
||||
'rate_alerted' => (bool)($result['rate_alerted'] ?? false),
|
||||
'message' => $ignored
|
||||
? 'Als bekannt eingestuft, gezaehlt, nicht gemeldet.'
|
||||
: ($result['is_new'] ? 'Fehler erfasst.' : 'Wiederkehrender Fehler, Zaehler erhoeht.'),
|
||||
], $result['is_new'] ? 201 : 200);
|
||||
|
||||
// ======================================================================
|
||||
|
||||
/** @param mixed $value */
|
||||
function trimOrNull($value): ?string
|
||||
{
|
||||
if ($value === null || is_array($value) || is_object($value)) {
|
||||
return null;
|
||||
}
|
||||
$value = trim((string)$value);
|
||||
return $value === '' ? null : $value;
|
||||
}
|
||||
|
||||
/**
|
||||
* Baut einen lesbaren Titel aus Ausnahmeklasse und Meldung.
|
||||
*
|
||||
* Die Meldung wird gekuerzt und von veraenderlichen Bestandteilen befreit,
|
||||
* damit der Titel bei wiederkehrenden Fehlern stabil bleibt.
|
||||
*/
|
||||
function buildTitle(?string $exception, ?string $message): string
|
||||
{
|
||||
$summary = $message ?? '';
|
||||
|
||||
// Anfuehrungszeichen mit wechselndem Inhalt entfernen, z. B. konkrete
|
||||
// Schluesselwerte in "Duplicate entry 'XY-123' for key ..."
|
||||
$summary = preg_replace("/'[^']{0,80}'/", "'…'", $summary) ?? $summary;
|
||||
$summary = trim(preg_replace('/\s+/', ' ', $summary) ?? $summary);
|
||||
|
||||
if ($summary === '') {
|
||||
return $exception ?? 'Unbehandelter Fehler';
|
||||
}
|
||||
|
||||
if (mb_strlen($summary) > 180) {
|
||||
$summary = mb_substr($summary, 0, 177) . '...';
|
||||
}
|
||||
|
||||
return $exception !== null ? $exception . ': ' . $summary : $summary;
|
||||
}
|
||||
@@ -147,6 +147,62 @@ $spec = [
|
||||
],
|
||||
],
|
||||
|
||||
'/api/errors/v1/report' => [
|
||||
'post' => [
|
||||
'tags' => ['Fehler'],
|
||||
'summary' => 'Laufzeitfehler melden',
|
||||
'description' =>
|
||||
"Schlanker Eingang fuer den globalen Exception-Handler. Titel und Dringlichkeit "
|
||||
. "leitet der Server ab.\n\n"
|
||||
. "Gleiche Fehler werden zu einer Gruppe zusammengefasst; veraenderliche Anteile "
|
||||
. "(Werte in Anfuehrungszeichen mit Ziffern, Adressen, GUIDs, Zeitstempel) werden "
|
||||
. "dabei ausgeblendet.\n\n"
|
||||
. "Greift eine Ignore-Regel, kommt `\"ignored\": true` zurueck: der Fehler wird "
|
||||
. "gezaehlt, aber nicht gemeldet. Ueberschreitet er die hinterlegte Alarmschwelle, "
|
||||
. "meldet die Antwort `\"rate_alerted\": true`.",
|
||||
'requestBody' => [
|
||||
'required' => true,
|
||||
'content' => ['application/json' => ['schema' => [
|
||||
'type' => 'object',
|
||||
'properties' => [
|
||||
'project_slug' => ['type' => 'string'],
|
||||
'exception' => ['type' => 'string', 'example' => 'PDOException'],
|
||||
'message' => ['type' => 'string'],
|
||||
'stack_trace' => ['type' => 'string'],
|
||||
'level' => ['type' => 'string', 'enum' => BugRepo::ERROR_LEVELS, 'default' => 'error'],
|
||||
'build' => ['type' => 'string'],
|
||||
'environment' => ['type' => 'string', 'enum' => BugRepo::ENVIRONMENTS],
|
||||
'file' => ['type' => 'string'],
|
||||
'line' => ['type' => 'integer'],
|
||||
'client_ref' => ['type' => 'string'],
|
||||
'context' => ['type' => 'object'],
|
||||
],
|
||||
]]],
|
||||
],
|
||||
'responses' => [
|
||||
'201' => ['description' => 'Neue Fehlergruppe angelegt'],
|
||||
'200' => ['description' => 'Bestehende Gruppe hochgezaehlt'],
|
||||
'401' => $errorResponse,
|
||||
'429' => $errorResponse,
|
||||
],
|
||||
],
|
||||
],
|
||||
|
||||
'/api/watchdog/v1/metrics' => [
|
||||
'get' => [
|
||||
'tags' => ['Watchdog'],
|
||||
'summary' => 'Metrik-Verlauf abrufen',
|
||||
'description' => 'Ohne "metric" die verfuegbaren Namen, mit "metric" den verdichteten Verlauf samt Abweichung vom eigenen Durchschnitt.',
|
||||
'parameters' => [
|
||||
['name' => 'source', 'in' => 'query', 'required' => true, 'schema' => ['type' => 'string']],
|
||||
['name' => 'metric', 'in' => 'query', 'schema' => ['type' => 'string']],
|
||||
['name' => 'hours', 'in' => 'query', 'schema' => ['type' => 'integer', 'default' => 24]],
|
||||
['name' => 'bucket', 'in' => 'query', 'schema' => ['type' => 'integer', 'default' => 15], 'description' => 'Fenstergroesse in Minuten'],
|
||||
],
|
||||
'responses' => ['200' => ['description' => 'Verlauf'], '401' => $errorResponse],
|
||||
],
|
||||
],
|
||||
|
||||
'/api/bugtracker/v1/projects' => [
|
||||
'get' => [
|
||||
'tags' => ['Bugtracker'],
|
||||
|
||||
@@ -32,6 +32,7 @@ use Deploymentcenter\Core\Db;
|
||||
use Deploymentcenter\Core\Http;
|
||||
use Deploymentcenter\Modules\Watchdog\Evaluator;
|
||||
use Deploymentcenter\Modules\Watchdog\EventLog;
|
||||
use Deploymentcenter\Modules\Watchdog\MetricStore;
|
||||
use Deploymentcenter\Modules\Watchdog\MonitorRepo;
|
||||
use Deploymentcenter\Modules\Watchdog\TokenManager as LegacyTokenManager;
|
||||
|
||||
@@ -56,18 +57,27 @@ switch ($action) {
|
||||
|
||||
authorizeSource($db, $source);
|
||||
|
||||
$instance = Http::str('instance') ?? 'default';
|
||||
$metrics = Http::input('metrics');
|
||||
|
||||
$monitor = $monitorRepo->upsertHeartbeat(
|
||||
$source,
|
||||
Http::str('instance') ?? 'default',
|
||||
$instance,
|
||||
Http::str('type') ?? 'heartbeat',
|
||||
Http::int('interval', 0) ?: Http::int('expected_interval_sec', 60),
|
||||
Http::input('metrics'),
|
||||
$metrics,
|
||||
strtolower(Http::str('status') ?? 'ok'),
|
||||
Http::str('message') ?? Http::str('reason'),
|
||||
Http::str('group') ?? Http::str('group_key'),
|
||||
Http::str('os')
|
||||
Http::str('os'),
|
||||
// Gesundheitszustand, den die Anwendung selbst ermittelt hat.
|
||||
Http::input('checks')
|
||||
);
|
||||
|
||||
// Numerische Werte in den Verlauf uebernehmen, damit sich Trends
|
||||
// erkennen lassen statt nur der letzte Moment.
|
||||
$recordedMetrics = (new MetricStore($db))->record($source, $instance, $metrics);
|
||||
|
||||
// Zustandswechsel im Ereignisprotokoll festhalten.
|
||||
if (!empty($monitor['_state_changed'])) {
|
||||
$previous = (string)$monitor['_previous_state'];
|
||||
@@ -87,13 +97,15 @@ switch ($action) {
|
||||
Http::ok([
|
||||
'message' => 'Heartbeat empfangen.',
|
||||
'monitor' => [
|
||||
'source' => $monitor['source'],
|
||||
'instance' => $monitor['instance'],
|
||||
'state' => $monitor['state'],
|
||||
'last_status' => $monitor['last_status'],
|
||||
'last_seen_utc' => $monitor['last_seen_utc'],
|
||||
'state_changed' => (bool)($monitor['_state_changed'] ?? false),
|
||||
'source' => $monitor['source'],
|
||||
'instance' => $monitor['instance'],
|
||||
'state' => $monitor['state'],
|
||||
'last_status' => $monitor['last_status'],
|
||||
'last_seen_utc' => $monitor['last_seen_utc'],
|
||||
'state_changed' => (bool)($monitor['_state_changed'] ?? false),
|
||||
'failing_checks' => $monitor['_failing_checks'] ?? [],
|
||||
],
|
||||
'metrics_recorded' => $recordedMetrics,
|
||||
]);
|
||||
|
||||
case 'event':
|
||||
@@ -135,6 +147,34 @@ switch ($action) {
|
||||
);
|
||||
Http::ok(['count' => count($events), 'events' => $events]);
|
||||
|
||||
case 'metrics':
|
||||
ApiAuth::requireScope($db, 'watchdog:read');
|
||||
|
||||
$source = Http::str('source');
|
||||
if ($source === null) {
|
||||
Http::fail(400, 'missing_source', 'Der Parameter "source" wird benoetigt.');
|
||||
}
|
||||
|
||||
$store = new MetricStore($db);
|
||||
$instance = Http::str('instance') ?? 'default';
|
||||
$metricKey = Http::str('metric');
|
||||
|
||||
if ($metricKey === null) {
|
||||
Http::ok([
|
||||
'source' => $source,
|
||||
'metrics' => $store->keysFor($source, $instance),
|
||||
'hint' => 'Mit &metric=<name> den Verlauf abrufen.',
|
||||
]);
|
||||
}
|
||||
|
||||
Http::ok([
|
||||
'source' => $source,
|
||||
'metric' => $metricKey,
|
||||
'hours' => Http::int('hours', 24),
|
||||
'history' => $store->history($source, $metricKey, Http::int('hours', 24), $instance, Http::int('bucket', 15)),
|
||||
'deviation' => $store->deviation($source, $metricKey, $instance),
|
||||
]);
|
||||
|
||||
case 'evaluate':
|
||||
// Bewusst nur fuer Shared Key oder eine angemeldete Sitzung -
|
||||
// ein Agenten-Token soll den Zustand aller Monitore nicht umschreiben.
|
||||
@@ -149,7 +189,7 @@ switch ($action) {
|
||||
|
||||
default:
|
||||
Http::fail(404, 'unknown_action', 'Endpunkt nicht gefunden.', null, [
|
||||
'available' => ['ping', 'event', 'status', 'events', 'evaluate'],
|
||||
'available' => ['ping', 'event', 'status', 'events', 'metrics', 'evaluate'],
|
||||
]);
|
||||
}
|
||||
|
||||
@@ -213,6 +253,7 @@ function resolveWatchdogAction(): string
|
||||
'events' => 'events',
|
||||
'status' => 'status',
|
||||
'evaluate' => 'evaluate',
|
||||
'metrics' => 'metrics',
|
||||
default => 'status',
|
||||
};
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user