Fetch-Log

Jeder automatische Abruf, den Pulsaria ausführt, landet zuerst in einem Protokoll — Erfolge, Fehler und bewusst übersprungene Versuche gleichermaßen. Wenn ein KPI nicht mehr aktualisiert wird oder eine Zahl seltsam aussieht, ist das der Bildschirm, der dir sagt, warum.

Wo er liegt

Fetch-Log ist der fünfte der sechs Haupteinträge in der Seitenleiste, zwischen Berichte und App-Einstellungen, auf der Route /logs. In einem schmalen Fenster ist es einer der sechs Tabs in der unteren Leiste. Zwei Stellen verlinken direkt hierher: der rote Toast, den ein fehlgeschlagener geplanter Abruf auslöst („Auto-KPI fehlgeschlagen“ mit der Aktion Details ansehen), und der Fehler-Toast eines manuellen Jetzt ausführen (ebenfalls „Auto-KPI fehlgeschlagen“, ebenfalls mit Details ansehen).

Die Überschrift lautet Fetch-Log, darunter steht der Untertitel „Jüngste Auto-KPI-Abrufe (Bash & HTTP). Maximal 500 Einträge.“

Der Untertitel nennt Bash und HTTP, aber Connector-Abrufe werden hier ebenfalls protokolliert. Der Text ist veraltet, nicht das Verhalten.

Was im Protokoll landet

Nur automatische Quellen schreiben hinein — Bash-, HTTP- und Connector-KPIs. Manuelle KPIs tauchen nie auf, und auch nichts, was du auf der Täglichen Erfassung eingibst.

Jeder Versuch aus diesen drei Pfaden wird aufgezeichnet:

• Der Hintergrund-Scheduler, wenn der Cron-Ausdruck eines KPI feuert.
• Jetzt ausführen auf einer KPI-Karte oder auf der KPI-Detailseite.
• Aktualisieren im Dashboard-Kopf, das alle automatischen KPIs auf einmal abruft.

Test ausführen im KPI-Dialog und Test ausführen im Connector-Assistenten werden nicht protokolliert. Sie schicken dieselbe Anfrage und zeigen dieselben Informationen im Ergebnis-Panel unter dem Button, schreiben aber nichts auf die Platte.

Was eine Zeile zeigt

Die neuesten Zeilen stehen oben. Eine eingeklappte Zeile liest sich von links nach rechts so:

Element	Was es zeigt
Pfeil	Zeigt eingeklappt nach rechts, dreht sich beim Öffnen nach unten
Status-Icon	Grüner Haken, wenn ein Wert gespeichert wurde, sonst ein rotes Kreuz
KPI-Name	Der Name des KPI zum Zeitpunkt des Abrufs
Zweite Zeile	Bei Erfolg Wert: 1234. Bei Fehler die Fehlermeldung, rot und in Monospace
Quellen-Badge	BASH, HTTP oder CONNECTOR
Dauer	Zum Beispiel 412 ms — wie lange der gesamte Versuch gedauert hat
Zeit	Relativ: „gerade eben“, „vor 5 Minuten“, „vor 3 Stunden“, „vor 2 Tagen“. Nach sieben Tagen wechselt die Anzeige auf ein Datum

Der Name ist eine Momentaufnahme. Benennst du einen KPI um, behalten alte Zeilen den alten Namen; löschst du einen KPI, bleiben seine Zeilen im Protokoll stehen.

Erfolg, Fehler und übersprungen

Eine Zeile ist nur dann grün, wenn eine Zahl gelesen und in die Historie des KPI für heute geschrieben wurde. Ein Teilergebnis gibt es nicht: Ein fehlgeschlagener Abruf speichert keinen Wert, lässt die Zahl von gestern stehen und rührt den Status des KPI nicht an.

Rot wird eine Zeile in zwei Situationen, die der Bildschirm nicht auseinanderhält:

Fehler — der Befehl endete mit einem Exit-Code ungleich 0, die API antwortete mit einem Fehlerstatus, die Antwort war kein JSON, der JSONPath hat nichts getroffen, die Ausgabe war keine Zahl. Irgendetwas ist schiefgegangen.

Übersprungen — Pulsaria hat den Abruf bewusst nicht ausgeführt. Dafür gibt es genau zwei Gründe, beide betreffen die Freigabe:

• Befehl nicht freigegeben — in den KPI-Einstellungen testen und freigeben für einen Bash-KPI, der nie freigegeben wurde.
• HTTP-Konfiguration nicht freigegeben — in den KPI-Einstellungen testen und freigeben für einen eigenen HTTP-KPI im selben Zustand.

Übersprungene Versuche werden mit einer eigenen Markierung gespeichert, aber das Fetch-Log zeichnet sie mit demselben roten Kreuz und derselben roten Schrift wie einen echten Fehler, und der Status-Filter zählt sie unter Fehler. Die einzige Stelle mit eigener Behandlung ist der Sammel-Toast nach Aktualisieren: „3 erfolgreich · 1 fehlgeschlagen · 2 übersprungen“, mit einer Aktion Freigeben. Übersprungene Läufe lösen außerdem keinen „Auto-KPI fehlgeschlagen“-Toast aus — das tun nur echte Fehler.

Wenn du eine dieser beiden Meldungen siehst, ist nichts kaputt. Öffne den KPI, drücke Test ausführen, dann Freigeben. Das Freigabe-Modell steht auf den Seiten Shell-Befehle und Eigene HTTP-Quellen.

Eine Zeile aufklappen

Ein Klick irgendwo auf die Zeile öffnet sie. Der Detailbereich zeigt, in dieser Reihenfolge:

1. Datum und Uhrzeit des Versuchs, in deiner Sprache formatiert.
2. HTTP Status: 200 — nur bei HTTP- und Connector-Abrufen.
3. Einen umrahmten stdout-Block in Monospace — nur bei Bash, und nur wenn der Befehl etwas ausgegeben hat.
4. Einen umrahmten stderr-Block in Rot — nur bei Bash, nur wenn er nicht leer ist.
5. Einen umrahmten body-Block — der Antwortkörper eines HTTP- oder Connector-Abrufs.

Jeder Block scrollt für sich, sobald er hoch wird, und lange Zeilen brechen um. Mehrere Zeilen können gleichzeitig offen sein; der Zustand geht verloren, wenn du den Bildschirm verlässt.

Was jede Quelle aufzeichnet

Quelle	In der Datei gespeichert
Bash	stdout, stderr, Exit-Code, der ausgeführte Befehl, der Shell-Aufruf
HTTP	Statuscode, Antwortkörper (erste 4096 Zeichen), die abgeschickte URL, die Methode
Connector	Statuscode, Antwortkörper (erste 4096 Zeichen), die aufgelöste URL, die Methode

Das aufgeklappte Panel zeigt nur Zeitstempel, HTTP-Status, stdout, stderr und den Body. Exit-Code, ausgeführter Befehl, Shell, effektive URL und HTTP-Methode landen zwar in der Datei, werden aber nirgends in der App angezeigt. Wer sie braucht, öffnet fetch-log.json selbst oder zieht einen JSON-Export.

Bei einem Bash-Fehler ist der Exit-Code wenigstens indirekt sichtbar: Die Fehlermeldung in der Zeile lautet Exit-Code 1. Und solange du einen KPI noch baust, zeigt das Ergebnis-Panel von Test ausführen im KPI-Dialog Befehl und Shell im Klartext.

Der Body wird auf dem Weg hinein zweimal gekürzt: Die native HTTP-Schicht deckelt jede Antwort bei 64 KB und bricht nach 10 Sekunden ab, danach speichert Pulsaria die ersten 4096 Zeichen. Eine große JSON-Antwort ist im Protokoll also mitten in der Struktur abgeschnitten. Das ist so gewollt.

Filter

Über der Liste sitzen drei Dropdowns, die mit UND kombiniert werden. Die Zahl der passenden Zeilen steht rechts in derselben Zeile, zum Beispiel 37 Einträge.

Filter	Optionen
KPI	Alle KPIs, dazu jeder nicht-manuelle KPI mit Namen
Quelle	Alle Quellen, Bash, HTTP
Status	Alle, Erfolg, Fehler

Zwei Lücken, die du kennen solltest:

• Der Quellenfilter hat keine Option Connector. Connector-Zeilen tragen zwar ein CONNECTOR-Badge, sind aber nur sichtbar, solange der Filter auf Alle Quellen steht — mit Bash oder HTTP verschwinden sie.
• Der Statusfilter hat keine Option Übersprungen. Übersprungene Läufe fallen unter Fehler.

Das KPI-Dropdown wird aus deinen aktuellen KPIs gebaut. Ein gelöschter KPI hat also Zeilen im Protokoll, aber keinen Filtereintrag — du findest sie unter Alle KPIs.

Ist noch nichts protokolliert, steht dort „Noch keine Fetches protokolliert.“ Schließen die Filter alles aus, steht dort „Keine Einträge für diesen Filter.“

Es gibt keine Volltextsuche, keinen Zeitraumfilter, keine Seitenblätterung und keine Sortieroption.

Wie viele Einträge bleiben

Das Protokoll ist ein Ringpuffer mit 500 Einträgen. Ein neuer Eintrag kommt vorne dazu, der älteste fällt hinten heraus. Sonst räumt nichts auf — es gibt kein Höchstalter. 500 Einträge decken also je nach Anzahl und Takt deiner automatischen KPIs eine Woche oder ein Jahr ab.

Grobe Rechnung: Fünf automatische KPIs im Stundentakt erzeugen 120 Zeilen pro Tag und füllen den Puffer in rund vier Tagen. Dieselben fünf im Tagestakt brauchen drei Monate.

Das Protokoll leeren

Leeren sitzt oben rechts und erscheint nur, wenn mindestens ein Eintrag vorhanden ist. Der Button öffnet einen nativen macOS-Dialog mit dem Titel „Log leeren“ und der Frage „Das gesamte Fetch-Log leeren?“. Bestätigst du, wird die Datei geleert.

Das Leeren lässt sich nicht rückgängig machen, und das Protokoll ist in keinem Einzel-Backup enthalten. Wenn du die Spuren eines Fehlers behalten willst, zieh vorher einen JSON-Export — siehe Backup, Export & Umzug.

Das Leeren hat einen Nebeneffekt, den man kennen sollte. Der Scheduler entscheidet anhand des neuesten Protokolleintrags, ob ein KPI fällig ist; bei leerem Protokoll fällt er auf das Anlegedatum des KPI zurück. Bei einem KPI, den es schon eine Weile gibt, liegt dieses Datum weit in der Vergangenheit — der nächste Scheduler-Tick hält ihn also für überfällig und ruft ihn einmal ab. Rechne damit, dass innerhalb einer Minute nach dem Leeren ein Schwung frischer Zeilen erscheint. Siehe Zeitpläne & Aktualisierung.

Wo die Datei liegt

Das Protokoll ist eine einzelne Datei, fetch-log.json, in deinem Datenordner. Standardmäßig:

~/Library/Application Support/com.onepixelahead.pulsaria/pulsaria/fetch-log.json

Hast du Pulsaria auf einen anderen Datenordner gezeigt, wandert das Protokoll mit. Es ist ein schlichtes JSON-Array, neueste Einträge zuerst, und enthält alle oben genannten Felder — auch die, die der Bildschirm nicht anzeigt.

Im JSON-Export ist das Protokoll enthalten, beim Import wird es aber bewusst nie eingelesen. Ein Export auf einem neuen Mac bringt dir also KPIs, Einträge, Projekte und Verbindungen — und ein leeres Fetch-Log.

stdout, stderr und Antwortkörper werden wortgetreu gespeichert. Ein Befehl oder eine API, die im Fehlerfall ein Token oder einen Kundennamen ausgibt, schreibt diesen Text in eine Datei, die auch in deinen Exporten landet. Halte Geheimnisse aus der Ausgabe heraus.

Einer kaputten Quelle auf den Grund gehen

Die Reihenfolge, die am schnellsten zur Antwort führt:

1. Statusfilter auf Fehler stellen, KPI-Filter auf den betroffenen KPI.
2. Die neueste Zeile ansehen. Die Meldung in der Zeile ist meistens schon die ganze Geschichte — Exit-Code 1, HTTP 401, Ausgabe ist keine Zahl.
3. Die Zeile aufklappen. Bei Bash sagt stderr, worüber sich der Befehl beschwert hat. Bei HTTP und Connectoren steht im body-Block die Fehlerantwort der API selbst — fast immer konkreter als der Statuscode.
4. Die Ursache beheben — Befehl neu freigeben, Zugangsdaten erneuern, JSONPath korrigieren.
5. Am KPI Jetzt ausführen drücken und zurückkommen. Eine frische grüne Zeile oben heißt: erledigt.

Es gibt keinen automatischen Wiederholungsversuch und kein Backoff. Ein fehlgeschlagener Abruf wartet auf das nächste Feuern seines Cron-Ausdrucks — und genau dieser fehlgeschlagene Versuch ist es, an dem der Scheduler festmacht, wann „das nächste Mal“ ist. Ein kaputter KPI wird also planmäßig wiederholt, nicht jede Minute.

Connector-Fehlermeldungen

Connector-Fehler bekommen übersetzte, lesbare Meldungen. Nach Details: folgen die ersten 200 Zeichen des Antwortkörpers der API.

Meldung	Was zu tun ist
Nicht autorisiert (401). Das Access-Token wurde abgelehnt. Details: …	Die Zugangsdaten sind falsch, abgelaufen oder zurückgezogen. Verbindung unter App-Einstellungen → Verbindungen neu autorisieren
Zugriff verweigert (403). Stelle sicher, dass die Service-Account-E-Mail Zugriff auf die Property hat. Details: …	Die Zugangsdaten sind gültig, haben aber keinen Zugriff auf diese Property oder Site. Zugriff in der Search Console oder in GA4 vergeben
API im Google-Cloud-Projekt nicht aktiviert (403). Aktiviere sie und versuche es erneut. Details: …	Search-Console- oder Analytics-Data-API im Cloud-Projekt des Keys aktivieren
Ungültige Anfrage (400). Prüfe die Parameter (Site-URL / Property-ID). Details: …	Ein Verbindungsparameter stimmt nicht — eine Site-URL, die nicht zur verifizierten Property passt, oder eine vertippte Property-ID
Rate-Limit erreicht (429). Warte eine Minute und versuche es erneut.	Nichts zu reparieren. Das ist die einzige Meldung ohne Detail-Ausschnitt
Serverfehler (503). Versuche es später erneut. Details: …	Problem des Anbieters. Der nächste geplante Lauf holt es nach
Verbindung nicht gefunden (gelöscht?)	Der KPI zeigt auf eine Verbindung, die es nicht mehr gibt. KPI bearbeiten und eine andere wählen
Zugangsdaten fehlen im Schlüsselbund. Bitte die Verbindung erneut autorisieren.	Der Schlüsselbund-Eintrag ist weg. Verbindung neu autorisieren
Connector-KPI referenziert keine Metrik/Verbindung	Der KPI wurde ohne Metrik oder Verbindung gespeichert. KPI bearbeiten und das Setup abschließen
JSONPath "…" returned nothing	Die API hat geantwortet, aber nicht in der erwarteten Struktur. body-Block lesen

Hintergrund zu den einzelnen Connectoren steht auf der Seite Connectoren.

Bash- und HTTP-Fehlermeldungen

Meldung	Bedeutung
Befehl nicht freigegeben — in den KPI-Einstellungen testen und freigeben	Übersprungen, nicht fehlgeschlagen. Befehl freigeben
HTTP-Konfiguration nicht freigegeben — in den KPI-Einstellungen testen und freigeben	Übersprungen, nicht fehlgeschlagen. HTTP-Konfiguration freigeben
Befehl wurde geändert — bitte erneut freigeben	Der Befehl wurde nach der Freigabe bearbeitet. Testen und erneut freigeben
HTTP-Konfiguration wurde geändert — bitte erneut freigeben	URL, Header oder JSONPath haben sich nach der Freigabe geändert
Exit-Code 1	Der Befehl ist fehlgeschlagen. stderr lesen
Ausgabe ist keine Zahl	Der Befehl lief, hat aber etwas ausgegeben, das Pulsaria nicht lesen kann. stdout lesen
Kein Befehl konfiguriert	Das Befehlsfeld des Bash-KPI ist leer
Shell-Befehle sind nur unter macOS verfügbar	Bash-KPIs laufen auf anderen Plattformen nicht
HTTP 404	Ein eigener HTTP-KPI hat einen Status außerhalb von 2xx bekommen. body-Block lesen
Antwort ist kein gültiges JSON	Der Endpunkt hat etwas anderes als JSON geliefert
JSONPath-Ergebnis ist keine Zahl	Der Pfad hat getroffen, der Wert ist aber keine Zahl
URL oder JSONPath fehlt	Der HTTP-KPI ist unvollständig

Eigene HTTP-KPIs bekommen nur das nackte HTTP <status> — die freundlichen 401/403/400/429-Texte von oben gibt es ausschließlich auf dem Connector-Pfad. Bei eigenen Endpunkten steht die Erklärung im body-Block der aufgeklappten Zeile.

Was dieser Bildschirm nicht kann

• Kein Export des Protokolls von hier aus. Es reist nur im vollständigen JSON-Export mit.
• Keine Suche, kein Zeitraumfilter, keine Seitenblätterung.
• Kein mitlaufendes Protokoll — die Liste aktualisiert sich bei Datenänderungen, nicht laufend.
• Keine Aufbewahrung oder Löschung pro KPI; Leeren ist alles oder nichts.
• Nichts aus dem Protokoll wird irgendwohin geschickt. Es ist eine Datei auf deinem Mac wie der Rest deiner Daten — siehe Datenschutz: Was den Mac verlässt.