Host-Agent

Sonden prüfen Ihre Dienste von außen. Der Agent prüft die Maschine selbst, und das ist der einzige Weg, eine volle Platte, einen toten Prozess oder einen Host zu sehen, der läuft, aber seine Aufgabe nicht mehr erfüllt. Er ist bewusst eng zugeschnitten: er misst und meldet, und er führt nichts für Sie aus.

Was er misst

Alle 15 Sekunden, auf dem Host:

Messwert	Im Einzelnen
CPU	Gesamtauslastung, 0 bis 100
Load Average	1, 5 und 15 Minuten (nur Unix)
Arbeitsspeicher und Swap	belegt, gesamt, Prozent
Platte	jedes gemountete Dateisystem, belegt und gesamt und Prozent
Laufzeit	Sekunden seit dem Start
Dienste	je beobachtetem Prozess: läuft, Anzahl Prozesse, CPU, belegter Speicher

Keine Netzwerkzähler, keine Aufschlüsselung je Kern, keine Temperaturen. Nichts über den Host, was nicht in dieser Tabelle steht.

Installation

Erzeugen Sie in der App unter Host-Agenten, Neuer Agent ein Enrollment-Token. Sie bekommen einen fertigen Befehl:

PERSTAT_TOKEN=psag_… sh -c "$(curl -fsSL https://agent.perstat.io/install.sh)"

Die Umgebungszuweisung hält das Token aus gewöhnlichen Prozessargumenten und der Prozessliste. Ein wörtlich in eine interaktive Shell eingefügter Befehl kann trotzdem in ihrer Historie landen; verwenden Sie Ihren Secret Manager oder eine Shell-spezifische verdeckte Eingabe bzw. History-Regel und entfernen Sie die Variable danach.

Unterstützt sind heute Linux auf x86_64 und aarch64 (statische musl-Builds, ohne Laufzeitabhängigkeiten) und macOS als Universal Binary. Windows gibt es noch nicht.

Der Installer erkennt Betriebssystem und Architektur, lädt die passende Binärdatei und prüft SHA-256. Mit einem Ed25519-fähigen OpenSSL 3 prüft er zusätzlich die Release-Signatur gegen den Schlüssel im Skript. Ohne diese Fähigkeit, darunter übliches macOS LibreSSL und ältere Distributionen, warnt er und fällt auf TLS-Transport plus SHA-256 zurück. Weil Installer und Schlüssel vom selben Ursprung kommen, hängt die Erstinstallation weiterhin vom Vertrauen in diesen Ursprung ab. Die spätere Selbstaktualisierung nutzt einen kompilierten Schlüssel und schlägt bei fehlender Prüfung geschlossen fehl, wie unten beschrieben.

Unter macOS wird stattdessen ein LaunchDaemon eingerichtet. Mit PERSTAT_NO_SERVICE=1 bekommen Sie die Binärdatei ohne Dienst.

Ein erneuter Lauf ist unbedenklich. Ist der Host bereits angemeldet, schaltet der Installer in den Upgrade-Modus: er erneuert Binärdatei und Dienst, behält die bestehende Identität und braucht kein Token. Dieselbe Zeile bei jedem Durchlauf aus dem Konfigurationsmanagement auf jedem Host auszuführen, ist der vorgesehene Weg. Für mehr als eine Handvoll Maschinen siehe Agenten auf einer Flotte.

Enrollment-Token

Eigenschaft	Vorgabe	Bereich
Laufzeit	24 Stunden	1 bis 720 Stunden
Einmalig verwendbar	ja	umstellbar auf wiederverwendbar

Das Token wird genau einmal angezeigt und nur als Hash gespeichert. Einmalig ist richtig für eine Maschine, wiederverwendbar für ein Flotten-Rollout. Zurücknehmen lassen sich Token vor Ablauf nicht, wählen Sie also lieber eine kurze Laufzeit als eine lange.

Das Token selbst ist undurchsichtig. Zu welcher Organisation und welchem Projekt es gehört, wird auf dem Server aufgelöst und vom Agenten nie ausgewertet.

Monitore, die darauf aufsetzen

Ein Agent meldet; ein Monitor entscheidet, was einen Incident wert ist. Legen Sie Monitore vom Typ agent an und binden Sie sie an den Agenten. Ein Monitor beobachtet einen Messwert:

metric	Felder	Schlägt an, wenn
availability	grace_seconds (Vorgabe 180, Bereich 60 bis 3600)	Der Host länger als die Karenzzeit nichts mehr gemeldet hat
cpu	threshold (Vorgabe 90)	CPU über dem Schwellwert
mem	threshold (Vorgabe 90)	Speicher über dem Schwellwert
disk	threshold (Vorgabe 90)	Das vollste Dateisystem über dem Schwellwert
service	service_name, grace_seconds (Vorgabe 120, Bereich 60 bis 3600)	Der Prozess länger als die Karenzzeit fehlt

Zwei Einstellungen gelten für alle. breach_severity ist down (öffnet einen Incident, alarmiert die Bereitschaft, erscheint auf Statusseiten) oder degraded (nur ein Hinweis in der App). notify_push schaltet die Push-Nachricht.

Ein Platten-Monitor deckt jeden Mountpunkt ab, weil der Schwellwert gegen das vollste Dateisystem geprüft wird. Beachten Sie, was er damit fängt und was nicht: er sieht ein volllaufendes Dateisystem, nicht eine einzelne wachsende Datei. Eine Logdatei, die 700 MB auf einer 25-GB-Platte belegt, verschiebt den Wert um drei Punkte und reißt keine 90-Prozent-Schwelle.

Agent-Monitore werden bei uns etwa alle 30 Sekunden ausgewertet. Sie tragen keine Prüfregionen und kein Quorum, eine einzige überschrittene Auswertung öffnet den Incident also, sobald die Karenzzeit vorbei ist.

Dienste beobachten

service_name ist ein Prozessname, keine systemd-Unit. Der Agent durchsucht die Prozessliste und trifft auf drei Wegen: über den exakten Prozessnamen, über den exakten Dateinamen des Programms (das ist es, was postgres und postmaster beide funktionieren lässt), und über die 15-Zeichen-Kürzung von Linux. Unter Linux wird Groß- und Kleinschreibung unterschieden.

Das hat eine Folge, die Sie vor dem Einrichten kennen sollten. Ein Dienst, der als Skript startet, erscheint in der Prozessliste als python3, sh oder node, zwei solche Dienste lassen sich am Namen also nicht unterscheiden. Kompilierte Dienste und alles, was seinen Prozessnamen selbst setzt, sind unproblematisch.

Um die echten Namen zu sehen, führen Sie entweder ps -eo comm= | sort -u auf dem Host aus, oder schalten Sie für diesen Agenten das Prozess-Inventar ein. Es ist ausdrücklich einzuschalten, standardmäßig aus, und überträgt nur Prozess- und Programmdateinamen, dedupliziert und gedeckelt, nie Kommandozeilen, Pfade, Benutzer oder PIDs. Mit eingeschaltetem Inventar schlägt das Monitor-Formular Namen vor, statt Sie tippen zu lassen.

Der Agent durchsucht die Prozessliste nur, wenn für ihn mindestens ein Dienst-Monitor existiert.

Netzwerk und Firewall

Nur ausgehend. Der Agent öffnet nie einen lauschenden Socket. Es gibt keine eingehende Regel zu schreiben und keinen Port freizugeben, und die systemd-Unit schränkt Adressfamilien und Systemaufrufe passend dazu ein.

Ausgehend über HTTPS auf Port 443, zu zwei Namen:

Host	Wofür
api.perstat.io	Anmeldung, Messwerte, Konfigurations-Abruf
agent.perstat.io	Installer, Binärdateien, Selbstaktualisierung

Beide müssen auflösbar sein. Auf einer Maschine, die einen autoritativen Nameserver betreibt und keinen Resolver, achten Sie darauf, dass ein brauchbarer Resolver eingetragen ist.

Zeitverhalten

Messung alle 15 Sekunden, gebündelter Versand alle 60 Sekunden, Abruf der Konfiguration etwa alle 5 Minuten. Die erste Messung geht sofort nach der Anmeldung raus, ein neuer Host erscheint also binnen Sekunden.

Scheitert ein Versand, sammeln sich die Messungen im Speicher (etwa sechs Stunden wert) und gehen raus, sobald die Verbindung zurück ist, eine kurze Störung reißt also kein Loch in Ihre Aufzeichnung. Die Sammlung übersteht einen Neustart des Agenten nicht.

Eine Folge des Fünf-Minuten-Abrufs: nachdem Sie einen Dienst-Monitor angelegt haben, kann es einige Minuten dauern, bis der Agent diesen Prozess beobachtet. Bis echte Daten da sind, bleibt der Monitor ausstehend statt anzuschlagen, ein frisch angelegter Monitor löst also nie einen Fehlalarm aus.

Selbstaktualisierung

Der Agent hält sich selbst aktuell. Releases sind ed25519-signiert, der Signaturschlüssel liegt offline, und der Agent prüft die Signatur gegen einen in seine eigene Binärdatei kompilierten Schlüssel, bevor er irgendetwas tauscht. Er ist fail-closed: Was sich nicht prüfen lässt, wird nicht installiert, und eine niedrigere Version kommt nie in Frage. Der Tausch geschieht im eigenen Verzeichnis des Agenten und braucht keine Root-Rechte.

Setzen Sie DATARGO_AGENT_NO_SELFUPDATE=1 in der Dienst-Umgebung, wenn Sie Versionen lieber selbst steuern.

Einen Agenten entfernen

Die Identität entfernen Sie über das Papierkorb-Symbol am Agenten. Das widerruft sein Token, archiviert die mit dem Agenten verbundenen Monitore und löst deren offene Incidents. Archivierte Monitore geben ihre Tarifplätze frei; die historischen Aufzeichnungen bleiben.

Die Software entfernen auf dem Host:

curl -fsSL https://agent.perstat.io/uninstall.sh | sudo sh

Das stoppt und entfernt den Dienst, löscht Binärdatei, Zustand und Dienstbenutzer und meldet den Host ab. Ist die Maschine bereits verschwunden, genügt das Entfernen der Identität im Cockpit.

Wenn ein Agent verstummt

Das gehört genau verstanden, weil es bestimmt, was Sie sehen.

Der Verfügbarkeits-Monitor schlägt an: Stille über seine Karenzzeit hinaus öffnet einen Incident. Er ist der Monitor, der Ihnen sagt, dass ein Host weg ist, und der Grund, jedem Agenten einen zu geben.

Die übrigen Monitore werden gar nicht mehr ausgewertet, sobald die letzte Meldung älter als 180 Sekunden ist. Sie schreiben keine Prüfungen, öffnen und schließen also nichts, weshalb ein toter Host einen Incident erzeugt statt einen je Messwert. Die Kehrseite: diese Kacheln zeigen weiter ihren letzten Wert, und der ist meist grün. Lesen Sie bei einem stillen Host den Verfügbarkeits-Monitor, nicht die Kacheln.

Eine Unterscheidung treffen wir noch nicht: ein toter Host und ein gesunder Host, der uns nicht erreicht, erzeugen dasselbe Signal, weil der Zeitstempel, mit dem wir arbeiten, der des Eingangs ist. Wenn dieser Unterschied für Sie zählt, stellen Sie dem Verfügbarkeits-Monitor eine externe Prüfung derselben Maschine zur Seite.

Datensparsamkeit

Kommandozeilen, Umgebungsvariablen und Benutzernamen erhebt der Agent nie. Das Prozess-Inventar ist ausdrücklich einzuschalten und auf Namen beschränkt. Er misst den Host und meldet das Ergebnis; ein Werkzeug für Inventarisierung oder Forensik ist er nicht, und dieser enge Zuschnitt ist der Punkt.

Er führt außerdem nichts aus. Es gibt keinen Kanal für Fernbefehle, keinen Skript-Haken und keinen Weg für uns, etwas auf Ihrer Maschine laufen zu lassen. Das ist eine bewusste Grenze und keine Funktion, die wir noch nicht gebaut haben.

Grenzen heute

• Windows gibt es nicht. Es steht im Changelog, sobald es das wirklich gibt.
• Der Zustand einer systemd-Unit wird nicht gelesen. Die Prüfung beantwortet “läuft ein Prozess dieses Namens”, eine fehlgeschlagene Unit mit einem übrigen Prozess, ein hängender Prozess und Neustart-Flattern innerhalb der Karenzzeit sehen also alle gesund aus.
• Eigene Messwerte lassen sich über den Agenten nicht melden. Wenn Sie auf eine Zahl alarmieren wollen, die nur der Host kennt, deckt das ein Heartbeat-Monitor ab: jeder hat einen Endpunkt für den guten Fall (/ping/<token>) und einen für den Fehlschlag (/ping/<token>/fail), und ein Timer auf dem Host entscheidet, welchen er ruft. Der Fehlschlag-Endpunkt bricht bei der nächsten Auswertung, statt die Periode abzuwarten. Das deckt ab, was eine Prozentschwelle nicht ausdrücken kann, etwa eine gefallene Anzahl oder ein gewachsenes Verzeichnis.
• Ein Monitor je Messwert. Vier Prozesse auf einem Host zu beobachten heißt vier Monitore.