82. pepsi-telemetry-client

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

82.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 — und, ruhend, auf einer, die das nicht getan 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 und pepsi-ingress) 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.

82.2. Wie es funktioniert

  • Lokaler Socket. Der Daemon lauscht auf [pepsi-telemetry-client] UNIXPATH (Standardwert /run/pepsi-telemetry/socket, ein Verzeichnis, das dieser Unit allein gehört — der Kollektor lauscht in /run/pepsi-collector), gruppengeteilt mit den Benutzern pepsi und pepsi-ingress. 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 der Benachrichtigung telemetry_changed — in beide Richtungen gesendet von dem, der den Schalter umschreibt: pepsi-setup und die write-config-Aufgabe der Konsole —, bei SIGHUP und jede Minute, und wacht dann auf oder schläft wieder ein. 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 (läuft, aktiviert, übermittelt, ob eine brauchbare SYSTEM_ID konfiguriert ist — ein Boolescher Wert, nie der Bezeichner — und ein Heartbeat), der bei einem sauberen Stopp gelöscht wird. 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.

82.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 und pepsi-ingress 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.

82.4. Den Dienst aktivieren

Die Unit wird bewusst nicht von pepsi.target gestartet, anders als die eigenen Daemons der Pipeline (sie ist PartOf= des Targets, sodass Stoppen oder Neustarten des Targets sie durchaus erreicht): Das Target ist der eine Schalter, der die Pipeline startet, und eine dort benannte Unit liefe auf jeder Installation, gleich was der Operator geantwortet hat. 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 Operator sie hinterlassen hat — es startet sie nie und stoppt sie auch nicht mehr, 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 geschieht nichts (es gibt keine Unit zu aktivieren); wo systemd die Unit nicht kennt, sagt Setup das nur, wenn die Telemetrie an ist; ohne root protokolliert es den einen auszuführenden systemctl-Befehl.

82.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.

82.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 Operator 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 Operator, der teilnimmt, kann das Teilen wieder beenden, indem er SHARE_TELEMETRY = NO setzt — 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 — oder indem er den Dienst pepsi-telemetry-client direkt stoppt/deaktiviert.

82.6. Siehe auch

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