Host-Agent

Prüfpunkte prüfen Ihre Dienste von außen. Der Agent prüft die Maschine selbst und zeigt, was nur von innen sichtbar ist: eine volle Platte, einen toten Prozess oder einen Host, der läuft, aber seine Aufgabe nicht mehr erfüllt. Er misst und meldet, und er führt nichts aus. So setzen Sie ihn auf Produktionshosts ein, ohne prüfen zu müssen, welche Befehle er erhalten könnte.

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

Die Tabelle ist vollständig: Der Agent erhebt diese Messwerte über den Host und sonst nichts.

Installation

Erzeugen Sie in der App unter Host-Agenten, dann 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. Übergeben Sie das Token aus Ihrem Secret Manager oder per verdeckter Eingabe, und entfernen Sie die Variable danach.

Der Agent läuft unter Linux (x86_64 und aarch64, statische musl-Builds ohne Laufzeitabhängigkeiten) und unter macOS als Universal Binary. Ein Windows-Agent ist geplant.

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. Auf Systemen ohne diese Fähigkeit, etwa mit dem üblichen LibreSSL von macOS oder älteren Distributionen, warnt er und prüft über TLS-Transport plus SHA-256. Installer und Schlüssel kommen vom selben Ursprung, die Erstinstallation vertraut also diesem Ursprung. Jede spätere Selbstaktualisierung prüft gegen einen in den Agenten kompilierten Schlüssel und ist fail-closed, wie unten beschrieben.

Unter Linux richtet der Installer eine systemd-Unit ein, unter macOS einen LaunchDaemon. 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 als Hash gespeichert. Einmalig passt für eine Maschine, wiederverwendbar für ein Flotten-Rollout. Ein Token gilt bis zu seinem Ablauf, wählen Sie also eine kurze Laufzeit.

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, und 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 (ein Hinweis in der App). notify_push schaltet die Push-Nachricht.

Ein Platten-Monitor deckt jeden Mountpunkt ab, weil der Schwellwert für das vollste Dateisystem gilt. Er beobachtet volllaufende Dateisysteme: Eine Logdatei, die 700 MB auf einer 25-GB-Platte belegt, verschiebt den Wert um drei Punkte, eine 90-Prozent-Schwelle bleibt also ruhig. Um auf eine einzelne wachsende Datei oder ein Verzeichnis zu alarmieren, nehmen Sie einen Heartbeat-Monitor.

Perstat wertet Agent-Monitore etwa alle 30 Sekunden aus. Sie melden direkt, ohne Prüfregionen und ohne 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.

Gut zu wissen, bevor Sie es einrichten: Ein Dienst, der als Skript startet, erscheint in der Prozessliste als python3, sh oder node, zwei solche Dienste teilen sich also einen Namen. Kompilierte Dienste und alles, was seinen Prozessnamen selbst setzt, erkennt der Agent eindeutig.

Um die echten Namen zu sehen, führen Sie entweder ps -eo comm= | sort -u auf dem Host aus, oder Sie schalten 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, Ihre Aufzeichnung bleibt bei einer kurzen Störung also vollständig. Die Sammlung liegt im Arbeitsspeicher und beginnt nach einem Neustart des Agenten von vorn.

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 schließt deren offene Incidents. Archivierte Monitore geben ihre Tarifplätze frei, und ihre historischen Aufzeichnungen folgen den geltenden Aufbewahrungsregeln.

Die Software entfernen Sie 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 setzen ihre Auswertung aus, 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. Diese Kacheln zeigen weiter ihren letzten Wert, meist grün, lesen Sie bei einem stillen Host also den Verfügbarkeits-Monitor.

Um einen toten Host von einem gesunden zu unterscheiden, der Perstat nicht erreicht, stellen Sie dem Verfügbarkeits-Monitor eine externe Prüfung derselben Maschine zur Seite. Das Signal des Agenten ist der Eingang seiner Meldung, aus seiner Sicht sehen beide Fälle also gleich aus.

Datensparsamkeit

Kommandozeilen, Umgebungsvariablen und Benutzernamen erhebt der Agent nie. Das Prozess-Inventar ist ausdrücklich einzuschalten und auf Namen beschränkt. Der Agent misst den Host und meldet das Ergebnis, und sein ganzer Umfang passt in die Tabelle unter Was er misst.

Er führt außerdem nichts aus. Es gibt keinen Kanal für Fernbefehle, keinen Skript-Haken und für niemanden bei Perstat einen Weg, etwas auf Ihrer Maschine laufen zu lassen.

Gut zu wissen

• Dienst-Monitore prüfen Prozesse. Die Prüfung beantwortet “läuft ein Prozess dieses Namens”. Eine fehlgeschlagene Unit mit einem übrigen Prozess, ein hängender Prozess oder Neustart-Flattern innerhalb der Karenzzeit sehen daher gesund aus. Ergänzen Sie kritische Dienste um eine externe Prüfung oder einen Heartbeat, der prüft, was der Dienst liefert.
• Eigene Messwerte laufen über Heartbeats. Um auf eine Zahl zu alarmieren, die nur der Host kennt, nehmen Sie einen Heartbeat-Monitor: 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.

Nächste Schritte

• Agenten auf einer Flotte: den Agenten auf viele Maschinen gleichzeitig ausrollen.
• API: Agenten und ihre Monitore mit einem API-Schlüssel verwalten.