Datenquellen im Überblick

Jeder KPI in Pulsaria hat genau eine Datenquelle. Sie entscheidet, wer die Zahl liefert: du selbst, ein fertiger Connector, ein HTTP-Endpunkt oder ein Shell-Befehl auf deinem Mac. Diese Seite stellt die vier nebeneinander, erklärt Testlauf und Freigabe-Modell und zeigt, wo ein fehlgeschlagener Abruf sichtbar wird.

Die vier Quellen nebeneinander

	Manuell	Connector	HTTP	Bash
Was du lieferst	die Zahl selbst	eine Metrik aus der Connector-Library plus eine Verbindung	eine URL, optionale Header, einen JSONPath	einen Shell-Befehl, der eine Zahl ausgibt
Aufwand vor dem ersten Lauf	keiner	Zugangsdaten des externen Dienstes und ein bis zwei Parameter, erfasst in einem dreistufigen Verbindungs-Assistenten	Endpunkt und Pfad in dessen JSON	der Befehl
Freigabe nötig	nein	nein	ja	ja
Wo das Geheimnis liegt	—	macOS-Schlüsselbund	im Klartext in kpi-definitions.json	im Klartext im Befehl
Wann sie läuft	wenn du einen Wert einträgst	nach Cron-Zeitplan oder auf Zuruf	nach Cron-Zeitplan oder auf Zuruf	nach Cron-Zeitplan oder auf Zuruf
Plattform	jede	automatischer Abruf nur macOS	automatischer Abruf nur macOS	immer nur macOS

Automatische Abrufe passieren, solange Pulsaria offen ist, unter macOS. Es gibt keinen Hintergrunddienst und kein Menüleisten-Icon: Wenn du die App beendest, wird nichts abgerufen. Auf jeder anderen Plattform bricht der Scheduler-Tick sofort ab — das betrifft auch Connector- und HTTP-KPIs, nicht nur Bash — und die Buttons Aktualisieren und Jetzt ausführen werden gar nicht erst angezeigt.

Manuell

Du trägst den Wert selbst ein, entweder auf der Seite Tägliche Erfassung oder auf der Detailseite eines KPI über Wert eintragen. Ein manueller KPI hat kein Zeitplan-Feld, und es kann nichts fehlschlagen. Das ist die richtige Wahl für Zahlen, die keine API hergibt: Anzahl geführter Verkaufsgespräche, eine subjektive Qualitätsnote, ein Wert, den du einmal pro Woche aus einem fremden Dashboard abliest.

Mehr dazu: Werte erfassen.

Connector

Sechs Connectoren sind eingebaut — Google Search Console, Google Analytics 4, Plausible, Polar, Stripe und Awin — mit zusammen 33 Metriken. Du wählst eine Metrik in der Connector-Library und danach eine Verbindung: Zugangsdaten plus die Parameter, die der Dienst braucht (Site-URL, Property-ID, Publisher-ID). Die Zugangsdaten landen im macOS-Schlüsselbund, nie in Pulsarias Datendateien, und eine Verbindung kann beliebig viele KPIs versorgen.

Die Metrik füllt außerdem Einheit, Richtung, KPI-Typ, Zeitraum und Cron-Zeitplan des KPI vor — ein Connector-KPI ist damit meist drei Klicks und ein Einfügen. Connector-KPIs brauchen keine Freigabe: Die Request-Vorlage ist fest in der App hinterlegt, mit festen Hosts und kodierten Parametern.

Mehr dazu: Connectoren.

HTTP

Für jede JSON-API, die kein Connector abdeckt. Du gibst eine URL an, optional Header-Zeilen und einen Punkt-/Bracket-Pfad in die Antwort, etwa data.items[0].value. Pulsaria schickt einen GET-Request aus der nativen Schicht, parst das JSON und speichert die Zahl, auf die der Pfad zeigt.

Ein Token, das du in eine Header-Zeile tippst, liegt im Klartext in kpi-definitions.json — und landet damit auch in einem JSON-Export. Nur Connector-Zugangsdaten gehen in den Schlüsselbund.

Mehr dazu: Eigene HTTP-Quellen.

Bash

Jeder Befehl, der eine einzelne Zahl auf stdout schreibt. Er läuft über /bin/sh -c in einer bewusst minimalen Umgebung (nur PATH, HOME und LANG werden durchgereicht — dein Shell-Profil wird nicht geladen) und wird nach 10 Sekunden abgebrochen. Der Befehl läuft mit deinen normalen Benutzerrechten, es gibt keine Sandbox.

Mehr dazu: Shell-Befehle.

Ein neuer KPI beginnt mit der Quelle

Der Dialog Neuer KPI startet mit der Entscheidung, die alles andere prägt. Er öffnet mit der Frage „Woher kommen die Daten dieser KPI? Du kannst das später ändern.“ und vier Karten: Manuell, Connector, Bash, HTTP.

1. Dashboard → + KPI in der Kopfzeile einer Gruppe (oder KPI anlegen bei einer frischen Installation).
2. Eine Quellen-Karte anklicken.
3. Das Formular öffnet sich mit dem Abschnitt Datenquelle oben und dem Abschnitt Ziel darunter.

Wählst du Connector, öffnet sich sofort die Connector-Library — denn die Metrik, die du dort aussuchst, füllt das halbe Formular. Links einen Connector wählen, rechts eine Metrik-Karte, dann Ausgewählte Metrik verwenden.

Die Reihenfolge ist kein Design-Gag. Die Quelle definiert, was gemessen wird, und eine Connector-Metrik überschreibt die Ziel-Felder darunter — so liest sich das Formular von oben nach unten, ohne dass sich hinter deinem Rücken etwas ändert.

Beim Bearbeiten eines bestehenden KPI entfällt die Auswahl. Der Dialog öffnet direkt das Formular, und die Quelle wird zu einem Vierfach-Schalter, den du an Ort und Stelle umlegen kannst.

Der Testlauf

Jede automatische Quelle lässt sich einmal ausführen, ohne dass etwas gespeichert wird. Im KPI-Dialog klickst du auf Test ausführen (die Beschriftung wechselt auf Läuft…). Ein Testlauf schreibt keinen KPI-Wert, keine Fetch-Log-Zeile und keine Warnung — er zeigt dir nur, was passieren würde.

Dasselbe Panel gibt es an zwei weiteren Stellen: in Schritt 3 des Verbindungs-Assistenten und hinter dem Test-Button mit dem Kreispfeil in einer Zeile unter App-Einstellungen → Verbindungen.

Änderst du Befehl, URL, Header oder JSONPath, wird ein vorheriges Ergebnis verworfen — was auf dem Bildschirm steht, gehört also immer zu dem, was gerade in den Feldern steht.

Was das Ergebnis-Panel zeigt

Die Kopfzeile liest sich als Ermittelter Wert mit der Zahl in Grün (Vorschau: 1234) oder als Test fehlgeschlagen in Rot. Darunter nur die Abschnitte, für die es Daten gibt:

Abschnitt	Inhalt
Befehl / URL	der exakte Aufruf, nachdem die Datums-Tokens aufgelöst wurden, mit Kopieren-Button
Ausgabe / Antwort	stdout bei Bash, sonst der Antwort-Body; ab 400 Zeichen oder 6 Zeilen auf sechs Zeilen eingeklappt, mit Mehr anzeigen
Fehler	stderr (nur Bash) und die Fehlermeldung (jede Quelle)
Meta-Zeile	Shell und Exit-Code bei Bash, sonst Methode und HTTP-Status — dazu immer Dauer in Millisekunden

Die Zahl in der Vorschau kommt aus demselben Code, den auch der Scheduler benutzt. Ein grüner Test heißt also: Ein geplanter Abruf würde genau diesen Wert speichern.

Zwei Ecken, die du kennen solltest: Antwort-Bodies werden vor der Anzeige auf 4.096 Zeichen gekürzt, und bei einem Connector-Test im KPI-Dialog steht in der Meta-Zeile immer POST als Methode — auch bei den Connectoren, die tatsächlich GET verwenden.

Der Bash-Test verweigert außerhalb von macOS den Dienst mit „Shell-Befehle sind nur unter macOS verfügbar“. Der HTTP-Test läuft überall, aber der daraus entstehende KPI wird außerhalb von macOS trotzdem nicht nach Zeitplan abgerufen.

Freigabe: warum Bash und HTTP dein ausdrückliches OK brauchen

Bash- und HTTP-KPIs schreibst du selbst, und sie können überall hinzeigen. Pulsaria führt sie deshalb erst aus, wenn du die genaue Konfiguration bestätigt hast — und merkt sich einen Fingerabdruck dessen, was du bestätigt hast.

Solange ein Bash- oder HTTP-KPI nicht freigegeben ist, steht oben im Dialog ein bernsteinfarbenes Banner Freigabe erforderlich: „Auto-KPIs laufen erst, wenn du sie freigibst. Teste den Befehl unten und klicke dann auf ‚Freigeben‘. Ohne Freigabe überspringt der Scheduler diesen KPI.“ Klick auf Freigeben, bestätige im folgenden Dialog, und ein grünes Banner Freigegeben ersetzt das amberfarbene.

Intern speichert die App einen SHA-256-Fingerabdruck genau dessen, was du gesehen hast:

• bei Bash den Befehlstext, wie er dasteht;
• bei HTTP die URL, die Header mit sortierten Schlüsseln und den JSONPath — die Reihenfolge der Header-Zeilen macht die Freigabe also nicht ungültig.

Vor jedem Abruf — geplant oder von Hand — wird der Fingerabdruck neu berechnet und verglichen:

Zustand	Was passiert
Fingerabdruck stimmt überein	der KPI läuft
kein Fingerabdruck gespeichert	der Lauf wird übersprungen und als „Befehl nicht freigegeben — in den KPI-Einstellungen testen und freigeben“ protokolliert
Fingerabdruck passt nicht mehr	der Lauf scheitert mit „Befehl wurde geändert — bitte erneut freigeben“

Der Grund: kpi-definitions.json ist eine ganz normale Datei auf deiner Platte. Ein anderes Programm, ein Sync-Konflikt von einem zweiten Mac oder eine Änderung von Hand könnten einen Befehl nach der Freigabe verändern. Der Fingerabdruck sorgt dafür, dass Pulsaria nie einen Befehl ausführt, den du nicht gesehen hast.

Einen nicht freigegebenen KPI kannst du speichern — er wird nur nicht abgerufen. Beim Speichern erscheint der Hinweis Gespeichert — noch nicht freigegeben / „Der Scheduler überspringt diese KPI, bis du sie freigibst.“

Was eine Freigabe ungültig macht

• Das Bearbeiten von Befehl, URL, Headern oder JSONPath.
• Das Duplizieren des KPI. Die Kopie startet ohne Freigabe, und der Toast sagt das auch.
• Der Import eines KPI aus einem JSON-Export. Freigaben werden bei jedem importierten KPI bewusst entfernt, damit nichts vorautorisiert von einem anderen Rechner ankommt.

Die gewollte Ausnahme sind Datums-Tokens. {{today}}, {{firstDayOfMonth}} und die 13 weiteren Tokens werden so gespeichert, wie du sie schreibst, und erst im Moment des Abrufs aufgelöst. Eine rollierende Abfrage bleibt damit freigegeben, während ihre Daten weiterwandern.

Connector-KPIs überspringen diesen ganzen Ablauf: kein Banner, kein Freigeben-Button, kein Fingerabdruck.

Was der Bestätigungsdialog zeigt

Ein Klick auf Freigeben öffnet Bash-Befehl bestätigen bzw. HTTP-Konfiguration bestätigen und zeigt den Befehl — oder URL und JSONPath in zwei Zeilen — noch einmal im Klartext. Bei Bash wird der Text auf zehn offensichtlich gefährliche Muster geprüft (rm -rf, sudo, dd if=, mkfs, Fork-Bomb, curl … | sh, wget … | sh, eval, chmod 777, Schreiben auf /dev/sd*); jeder Treffer wird unter „Verdächtige Muster erkannt:“ im Klartext aufgelistet. Darunter steht: „Gib nur Quellen frei, denen du vertraust. Bei späteren Edits ist eine erneute Bestätigung erforderlich.“

Diese Prüfung ist ein Hinweis, keine Sicherheitsgrenze. Ein freigegebener Befehl läuft mit deinen vollen Benutzerrechten, und der Freigeben-Button verlangt keinen Testlauf — du kannst etwas freigeben, das du nie ausgeführt hast oder das gerade fehlgeschlagen ist.

Wenn ein Abruf fehlschlägt

Ein fehlgeschlagener Abruf schreibt nie einen Wert. Die KPI-Karte behält ihre letzte gute Zahl, der Status bleibt unverändert — genau deshalb kann eine still kaputte Quelle im Dashboard eine Weile unauffällig aussehen.

Es gibt keine automatische Wiederholung und kein Backoff. Der nächste geplante Zeitpunkt ist der Wiederholungsversuch.

Wo Fehler auftauchen

• Einmal als Toast. Ein geplanter Fehlschlag erzeugt einen roten Toast Auto-KPI fehlgeschlagen mit <KPI-Name>: <Fehler> und der Aktion Details ansehen, die das Fetch-Log öffnet.
• Als Sammelmeldung. Aktualisieren im Dashboard meldet 3 erfolgreich · 1 fehlgeschlagen · 2 übersprungen. Wurde etwas übersprungen, ist der Toast informativ (Auto-KPIs aktualisiert) und bietet eine Freigeben-Abkürzung zum ersten übersprungenen KPI; gab es nur Fehler, ist er rot (Auto-KPIs mit Fehlern) und bietet Details. Ohne automatische KPIs steht dort Keine Auto-KPIs konfiguriert.
• Pro KPI. Jetzt ausführen auf einer Karte oder auf der Detailseite meldet KPI aktualisiert mit <Name>: <Wert> oder Auto-KPI fehlgeschlagen mit Details ansehen.
• Im Fetch-Log. Jeder Versuch — Erfolg, Fehler und übersprungen — wird unter /logs festgehalten, neueste zuerst, begrenzt auf 500 Einträge. Nur dort überlebt ein Fehlschlag, nachdem der Toast verschwunden ist. Es gibt keine E-Mail und keine Push-Benachrichtigung.

Übersprungene Läufe werden als „nicht erfolgreich“ gespeichert und landen im Fetch-Log deshalb unter dem Filter Fehler, mit demselben roten Symbol wie echte Fehlschläge. Die amberfarbene Behandlung für „übersprungen“ gibt es nur in der Sammelmeldung.

Meldungen, die dir begegnen werden

Meldung	Bedeutung
Befehl nicht freigegeben — in den KPI-Einstellungen testen und freigeben	der KPI wurde nie freigegeben; er wurde übersprungen, nicht versucht
Befehl wurde geändert — bitte erneut freigeben	der gespeicherte Befehl passt nicht mehr zum Fingerabdruck
Ausgabe ist keine Zahl	der Befehl lief durch, aber stdout war leer oder keine Zahl
Exit-Code 1	der Befehl endete mit einem Code ungleich 0; stderr steht in der Log-Zeile
Command timed out after 10s	der Shell-Befehl lief in die harte Zeitgrenze
HTTP 401	ein eigener HTTP-KPI bekam eine Antwort außerhalb von 2xx
JSONPath-Ergebnis ist keine Zahl	der Pfad hat nicht getroffen oder das Gefundene ist keine Zahl
Zugangsdaten fehlen im Schlüsselbund. Bitte die Verbindung erneut autorisieren.	der Schlüsselbund-Eintrag dieser Verbindung ist weg
Verbindung nicht gefunden (gelöscht?)	die Verbindung, auf die dieser KPI zeigt, wurde gelöscht

Connector-Fehler bekommen übersetzte, lesbare Meldungen — etwa „Zugriff verweigert (403). Stelle sicher, dass die Service-Account-E-Mail Zugriff auf die Property hat.“ Eigene HTTP-KPIs bekommen das nicht: Dort steht nur das nackte HTTP <Status>.

Grenzen, die für alle gelten

Diese Werte gelten für jede automatische Quelle und lassen sich nicht konfigurieren:

• 10 Sekunden Timeout, für Shell-Befehle wie für HTTP-Requests.
• 64 KB Obergrenze für die Antwort. Größere Bodies werden abgeschnitten, was das JSON-Parsen meist zerlegt.
• Nur http:// und https://, höchstens 5 Weiterleitungen, und Weiterleitungen auf andere Schemata werden abgelehnt.
• Eigene HTTP-KPIs können nur GET. Es gibt keine Methodenauswahl und keinen Request-Body.
• Die abgerufene Zahl wird unter dem heutigen lokalen Kalendertag gespeichert, egal welchen Zeitraum die Zahl selbst beschreibt.
• Ist die Testphase abgelaufen oder die Lizenz widerrufen, pausiert der automatische Abruf komplett und Aktualisieren ist deaktiviert, mit dem Tooltip „Lizenz oder aktive Testversion nötig“.

Wie es weitergeht

• Connectoren — die sechs Dienste, ihre Metriken und wie Verbindungen funktionieren.
• Eigene HTTP-Quellen — URL, Header, JSONPath und Datums-Tokens.
• Shell-Befehle — die Ausführungsumgebung und was darin gerne kaputtgeht.
• Zeitpläne & Aktualisierung — Cron-Presets, Nachholen nach geschlossener App und die manuellen Auslöser.
• Fetch-Log — wie du den Verlauf aller Versuche liest.
• Datenschutz: Was den Mac verlässt — mit welchen Hosts ein automatischer KPI spricht.