92. pepsi-telemetry-client

Der hostbezogene Aggregator für Funktionstelemetrie: sammelt lokale Funktionsnutzungsereignisse und übermittelt anonyme Aggregate an den zentralen Collector.

92.1. Rolle

pepsi-telemetry-client ist die Produzenten-Seite von Pepsis anonymer Funktionstelemetrie; der zentrale Collector ist pepsi-telemetry. Es wird im Haupt-Pepsi-Paket ausgeliefert und läuft als kleiner Daemon auf jeder Installation, die Telemetrie aktiviert hat. Ruhend läuft es außerdem auf einer Installation, die Telemetrie nicht aktiviert hat, aber möchte, dass die Browser-Konsole sie einschalten kann. Führen Sie es mit pepsi-telemetry-client serve aus.

Die Pepsi-Programme auf dem Host (die Stage-Worker, pepsi-ingress, pepsi-httpd, pepsi-dispatch und die Betreiberwerkzeuge) melden Funktionsnutzung über einen internen, nicht-blockierenden telemetry_update-Aufruf, der einen kurzen Funktionsnamen über einen lokalen UNIX-Socket an diesen Daemon übergibt; die aufrufende Stage wartet nie auf das Netzwerk. Der Daemon aggregiert diese Ereignisse und übermittelt sie an TELEMETRY_SERVER unter der anonymen SYSTEM_ID der Installation.

92.2. Wie es funktioniert

  • Lokaler Socket. Der Daemon lauscht auf [pepsi-telemetry-client] UNIXPATH (Standardwert /run/pepsi-telemetry/socket). Der Socket ist gruppengeteilt mit den Benutzern pepsi, pepsi-ingress, pepsi-httpd und pepsi-keydisc (Mitglieder der Gruppe pepsi-telemetry). Sein Verzeichnis gehört dieser Unit allein; der Collector lauscht in /run/pepsi-collector. Jeder Produzent hält für die Lebensdauer seines Prozesses eine persistente Verbindung und verbindet sich neu, wenn der Daemon neu startet; Ereignisse werden verworfen (nach bestem Bemühen), während er unerreichbar ist, sodass ein Produzent nie blockiert wird.

  • In-Memory-Aggregation. Für jede Funktion wird ein Zähler pro Intervall gehalten, plus die kumulative Menge der seit dem Start gesehenen Funktionsnamen (der Schnappschuss der aktivierten Funktionen). Die Anzahl der verschiedenen Namen ist durch MAX_FEATURES begrenzt.

  • Periodische Übermittlung. Alle SUBMIT_INTERVAL (Standardwert: höchstens einmal pro Minute) POSTet der Daemon die Zähler pro Intervall an /telemetry/usage und die kumulative Funktionsmenge an /telemetry/features und setzt dann die Zähler pro Intervall zurück. Eine fehlgeschlagene Nutzungs-Übermittlung wird behalten und im nächsten Intervall wiederholt statt verloren.

  • Sauberes Herunterfahren. Bei SIGINT/SIGTERM macht es eine letzte Übermittlung, bevor es sich beendet.

  • Ruhend, solange ausgeschaltet. Bei ausgeschalteter Telemetrie bindet es keinen Socket und sammelt und übermittelt nichts. Es liest die Konfigurations*datei* erneut bei SIGHUP, jede Minute und bei der Benachrichtigung telemetry_changed und wacht dann auf oder schläft wieder ein. Diese Benachrichtigung sendet, in beide Richtungen, wer den Schalter umschreibt: pepsi-setup und die write-config-Aufgabe der Konsole. Beim Übergang in den Ruhezustand wird verworfen, was gesammelt und noch nicht gesendet wurde. Die Benachrichtigung trägt keine Autorität; allein die Datei entscheidet.

  • Statusdatensatz. Es führt einen Datensatz in pepsi.telemetry_client und löscht ihn bei einem sauberen Stopp. Der Datensatz hält fest, ob der Daemon läuft, aktiviert ist und übermittelt, ob eine brauchbare SYSTEM_ID konfiguriert ist (ein Boolescher Wert, nie der Bezeichner), und einen Heartbeat. pepsi-httpd liest ihn, um zu entscheiden, ob die Setup-Konsole anbieten darf, die Telemetrie einzuschalten.

Der Daemon stempelt jede Übermittlung mit der Pepsi-Release-Version, als die er gebaut wurde, sodass der Collector die Funktionsnutzung pro Release zählt.

92.3. Konfiguration

Der Hauptschalter ist [pepsi] SHARE_TELEMETRY, und er ist standardmäßig aus: Telemetrie ist Opt-in, sodass eine Installation, die die Frage nie beantwortet hat, überhaupt keine Telemetrie betreibt. Solange er nicht auf yes steht, bleibt der Daemon ruhend und die In-Process-telemetry_update-Aufrufe sind No-Ops, die keinen Socket öffnen; der gesamte Pfad ist inaktiv, ganz gleich ob die Service-Unit aktiviert ist oder nicht. [pepsi] SYSTEM_ID (von pepsi-setup erzeugt, aber nur, sobald der Schalter an ist) und TELEMETRY_SERVER (Standardwert telemetry.pepsi.taler.net) vervollständigen die globale Konfiguration. Die eigenen Listener- und Timing-Stellschrauben des Daemons stehen in [pepsi-telemetry-client]: UNIXPATH (Standardwert /run/pepsi-telemetry/socket), UNIXPATH_MODE (Standardwert 0660), UNIXPATH_GROUP (Standardwert pepsi-telemetry, die Gruppe, zu der pepsi, pepsi-ingress, pepsi-httpd und pepsi-keydisc hinzugefügt werden), SUBMIT_INTERVAL (Standardwert 60 s, das h/m/s-Einheiten verwenden muss und nicht null sein darf) und MAX_FEATURES (Standardwert 4096). Siehe pepsi-telemetry-client(1) und pepsi.conf(5) für die vollständige Liste.

92.4. Den Dienst aktivieren

Die Unit wird bewusst nicht von pepsi.target gestartet, anders als die eigenen Daemons der Pipeline. Das Target ist der eine Schalter, der die Pipeline startet, und eine dort benannte Unit liefe auf jeder Installation, gleich was der Betreiber geantwortet hat. Die Unit ist allerdings PartOf= des Targets, sodass Stoppen oder Neustarten des Targets sie durchaus erreicht. Stattdessen aktiviert pepsi-setup run die Unit am Ende eines erfolgreichen Laufs, wenn der Schalter an ist (systemctl enable --now); ist er aus, lässt es die Unit so, wie der Betreiber sie hinterlassen hat: Es startet sie weder, noch stoppt es sie, denn ein laufender Daemon ist ruhend und genau das, was die Konsole braucht. In beiden Fällen sendet es danach telemetry_changed, sodass das Abschalten der Telemetrie sofort wirkt. Ist der Schalter an und gibt es keine gültige SYSTEM_ID, wird die Unit trotzdem aktiviert; der Daemon bleibt ruhend und sagt, warum. Auf einem Host ohne systemd tut Setup nichts (es gibt keine Unit zu aktivieren). Wo systemd die Unit nicht kennt, sagt Setup das nur, wenn die Telemetrie an ist, und ohne root protokolliert es den einen auszuführenden systemctl-Befehl.

92.4.1. Aktivierung über die Konsole

Die Browser-Setup-Konsole bietet „ja“ nur an, solange der Daemon läuft und eine SYSTEM_ID konfiguriert ist; andernfalls ist die Frage mit Hinweisen deaktiviert, und eine API-Anfrage zum Einschalten wird abgewiesen (409 telemetry_client_not_ready). Die Konsole erzeugt nie einen Bezeichner. Damit sie den Schalter anbieten kann, fügen Sie auf dem Server SYSTEM_ID = und 64 Hexadezimalzeichen (z. B. openssl rand -hex 32) zu [pepsi] hinzu und führen systemctl enable --now pepsi-telemetry-client.service aus. Ein Speichern in der Konsole behält einen vorhandenen Bezeichner bei, gleich wie die Antwort lautet.

92.5. Privatsphäre

Keine personenbezogenen Informationen verlassen den Host. Die einzige Identität ist die zufällige 256-Bit-SYSTEM_ID; die Nutzlasten sind Funktionsnamen und Zähler. Nichts wird geteilt, solange ein Betreiber es nicht verlangt: Der Schalter ist standardmäßig aus, der Setup-Assistent stellt die Frage mit no als Standardantwort, und für eine Installation, die nicht teilnimmt, wird gar kein Bezeichner erzeugt. Ein Betreiber, der teilnimmt, kann das Teilen auf zwei Wegen wieder beenden. Der eine ist, SHARE_TELEMETRY = NO zu setzen, entweder in der Konsole oder in der Datei, gefolgt von pepsi-setup run (oder SIGHUP, oder einer Minute Wartezeit); der Daemon wird dann ruhend und verwirft, was er noch nicht gesendet hatte. Der andere ist, den Dienst pepsi-telemetry-client direkt zu stoppen oder zu deaktivieren.

Die Grenze ist der Daemon, nicht die Konsole: Er glaubt nur der Konfigurationsdatei, gelesen über die eine Funktion, die jede Komponente verwendet, und ein fehlender oder nicht parsebarer Schalter gilt als aus. Eine telemetry_changed-Benachrichtigung kann ihn nicht einschalten, und pepsi-httpd darf den Statusdatensatz lesen, aber nicht schreiben, sodass eine Konsole kein „ready“ fälschen kann. Die Datenschutzzusage, die dies wahrt, ist Teil von Schutzgüter; die Seite der Konsole wird in Feature-Telemetrie über die Konsole einschalten beschrieben.

SYSTEM_ID ist eine Kennung, kein Geheimnis, das der Collector prüft. Wer sie aber erfährt, kann den Beitrag dieser Installation zum öffentlichen Bericht umschreiben, daher wird sie überall, wo Konfiguration angezeigt wird, wie ein Zugangsdatum maskiert (pepsi-config dump, die administrative API, die Antwort der Einstellungen per E-Mail).

92.6. Siehe auch

pepsi-telemetry (der Kollektor), pepsi-setup, pepsi-telemetry-client(1), pepsi.conf(5).