Bei fehlgeschlagenen Jobs Bescheid bekommen

Job-Reports sind Teil von Vaicoa Pro und Vaicoa Team. Jeder Job gehört zu einem Server, auf dem der Agent läuft.

Ein Job-Report ist das Ergebnis eines deiner eigenen regelmäßigen Jobs, etwa eines Backups, einer Zertifikatserneuerung oder einer Erreichbarkeitsprüfung, nach jedem Durchlauf an Vaicoa gesendet. Vaicoa alarmiert dich, wenn der Job fehlschlägt und wenn er länger als erlaubt nicht erfolgreich war. So fällt ein Backup auf, das ohne Fehlermeldung aufgehört hat zu laufen.

Zu jedem Job gehören zwei Alarme. Sie nutzen dieselben Push-Mitteilungen und dieselbe Alarmzustellung wie andere Alarme:

• Fehlgeschlagen: Der letzte Durchlauf endete mit einem Exit-Code ungleich 0.
• Veraltet: kein erfolgreicher Durchlauf innerhalb der Zeit, die der Job angegeben hat. Ein Job ohne Zeitangabe bekommt nur den Alarm bei Fehlern. Ein Job, der nie erfolgreich war, ist nie veraltet; er erscheint als fehlgeschlagen.

Ein Job-Report nimmt denselben Weg wie die Metriken und Logs des Agents. Deshalb ist nichts zusätzlich zu installieren oder zu öffnen:

Den Wrapper vor den Job setzen

Der Agent installiert einen Wrapper, cloudviewer-report. Er führt deinen Befehl aus, misst, wie lange er gedauert hat, sendet den Report und gibt den Exit-Code des Befehls unverändert zurück. Deine Cron-Zeile verhält sich also wie vorher.

1. Such die Zeile, die den Job startet, in einer Crontab oder einem systemd-Service.

2. Setz den Wrapper vor den Befehl, mit einem Job-Namen und dem Alter, das der letzte Erfolg höchstens erreichen darf:

   cloudviewer-report --job backup-s3 --max-age 26h -- restic backup /data

3. Lass den Job laufen. Der erste Report legt den Job an; vorab musst du nichts registrieren.

Wähl --max-age etwas länger als den Zeitplan, damit ein Durchlauf, der später startet, nicht als veraltet gilt: 26h für einen täglichen Job. Der Wert sind Sekunden oder eine Zahl mit m, h oder d. Job-Namen bestehen aus Kleinbuchstaben, Ziffern, -, _ und ., bis 64 Zeichen, und beginnen mit einem Buchstaben oder einer Ziffer.

Der Wrapper liest das Token des Servers aus /etc/cloudviewer-agent/agent.env, das normale Nutzer nicht lesen können. Führ den Job als root aus, oder gib dem Wrapper eine Datei, die nur das Token enthält: --token-file /path/to/token. Fehlt das Token, ist es falsch oder ist Vaicoa nicht erreichbar, entfällt der Report; der Job selbst schlägt dadurch nie fehl und wird nicht verzögert.

Stattdessen mit curl melden

Wenn ein Skript sein Ergebnis selbst kennt oder der Wrapper nicht installiert ist, sende den Report mit einem HTTP-Aufruf und dem Agent-Token des Servers:

restic backup /data; ec=$?
curl -sS -X POST https://api.vaicoa.com/v1/ingest/job \
  -H "X-Agent-Token: $CV_AGENT_TOKEN" -H "Content-Type: application/json" \
  -d "{\"reports\":[{\"job_name\":\"backup-s3\",\"exit_code\":$ec,\"max_age_seconds\":93600}]}"

Auf einem Server mit installiertem Agent liegt das Token in /etc/cloudviewer-agent/agent.env. Alle Felder, Grenzen und Fehlercodes stehen in der Job-Reports-API.

Jobs, die woanders laufen

Ein Job, der nicht auf dem Server läuft, etwa in GitHub Actions, in einer Serverless-Funktion oder auf einer Maschine außerhalb von Hetzner, meldet sich mit dem Token des Servers, auf den er sich bezieht: der Datenbank, die er sichert, oder des Hosts hinter der API, die er prüft. Der Job erscheint dann in der Ansicht dieses Servers. Leg das Agent-Token des Servers in deinen CI-Secret-Store und nutze --token-file oder den curl-Aufruf.

Wo Jobs erscheinen

In der App hat die Detailansicht des Servers einen Abschnitt Jobs zwischen den Charts und Log-Kontext, sobald der Server einen Job gemeldet hat. Jede Zeile zeigt einen Statuspunkt, den Namen, bei einem Problem Veraltet, Exit mit dem Code oder Nie erfolgreich, dann wann der Job zuletzt erfolgreich war oder lief und wie lange er gedauert hat.

Tipp eine Zeile an, um die Ansicht des Jobs zu öffnen:

Status	Erfolgreich, Fehlgeschlagen oder Veraltet. „Veraltet“ hat Vorrang vor einem erfolgreichen Exit-Code, denn ein Job, der zuletzt vor einer Woche erfolgreich war, funktioniert gerade nicht
Letzte Ausführung	wie lange her, mit der genauen Zeit darunter
Letzter Erfolg	dasselbe, oder Nie
Exit-Code	die Zahl, rot, wenn sie nicht 0 ist
Dauer	sofern der Report eine enthielt
Erwartet	zum Beispiel „alle 24 Stunden“, aus der angegebenen Zeit, oder Kein Zeitplan angegeben

Darunter führt Warum er fehlgeschlagen ist → Log-Kontext öffnen zum Log des Servers. Ein Job-Report enthält keine Nachricht. Die Einzelheiten stehen daher im Log des Servers rund um die Zeit des Durchlaufs. Lass den Job sie mit Priorität Warning oder höher nach journald schreiben, dann erscheinen sie dort:

logger -p user.warning -t backup "s3 sync failed: bucket not reachable"

Job-Reports-APIEndpunkt, Felder, Wrapper-Flags, Grenzen und Fehlercodes.

Wenn etwas Aufmerksamkeit brauchtVom Alarm zu den Log-Zeilen, die ihn erklären.