85.1.54. pepsi-telemetry-client

per-host feature-telemetry aggregator and submitter

Handbuchabschnitt:

1

85.1.54.1.1. Name

pepsi-telemetry-client - lokale Funktionsnutzungs-Telemetrie aggregieren und an den zentralen Collector übermitteln.

85.1.54.1.2. Übersicht

pepsi-telemetry-client [GLOBAL-OPTIONS] serve

85.1.54.1.3. Beschreibung

pepsi-telemetry-client ist die hostweise Produzenten-Seite von Pepsis anonymer Funktionstelemetrie (der zentrale Collector ist pepsi-telemetry(1)). Es ist ein kleiner langlebiger Daemon, der:

  • auf einem lokalen UNIX-Socket auf Funktionsnutzungs-Ereignisse lauscht, die von den Pepsi-Programmen auf demselben Host ausgegeben werden (die Stage-Worker und pepsi-ingress(1), über die interne telemetry_update-API);

  • die Ereignisse im Speicher ansammelt — einen Zähler pro Intervall für jede Funktion plus die kumulative Menge der in diesem Lauf gesehenen Funktionen;

  • alle SUBMIT_INTERVAL (Standardwert: höchstens einmal pro Minute) die Zähler an den Collector unter TELEMETRY_SERVER mit der anonymen SYSTEM_ID dieser Installation übermittelt und die Zähler pro Intervall zurücksetzt (sie für eine Wiederholung wieder zusammenführt, falls eine Übermittlung fehlschlägt);

  • beim Herunterfahren (SIGINT/SIGTERM) eine letzte Übermittlung macht, sodass ein sauberer Stopp das aktuelle Intervall nicht verliert.

Es hält keine Geheimnisse über die anonyme SYSTEM_ID hinaus; sein einziger ausgehender Verkehr ist HTTPS zum Collector. Seine Datenbankverbindung (als Rolle pepsi) dient zwei Zwecken und keinen anderen: einem LISTEN auf dem Kanal telemetry_changed und dem einzeiligen Lebendigkeitseintrag pepsi.telemetry_client, der unten beschrieben ist. Ohne Datenbank funktioniert es weiterhin und folgt bei seinem Heartbeat der Konfigurationsdatei.

Telemetrie ist Opt-in: Solange [pepsi] SHARE_TELEMETRY nicht auf yes gesetzt wurde, ist die Produzenten-API eine No-Op, die keinen Socket öffnet, und der Daemon läuft ruhend — er bindet keinen Socket, sammelt nichts und übermittelt nichts. Das ist es, was eine Installation bekommt, die die Frage nie beantwortet hat, gleich ob die Dienst-Unit aktiviert ist oder nicht. Eine fehlende Option, ein fehlender [pepsi]-Abschnitt und ein nicht parsbarer Wert lesen sich alle als aus — „ich konnte es nicht feststellen“ ist nie eine Zustimmung —, und der Schalter wird konsultiert, bevor [pepsi-telemetry-client] überhaupt geparst wird, sodass ein Tippfehler in einem Abschnitt, der nicht von Belang sein kann, einen ruhenden Daemon nicht beeinträchtigen kann.

Die Produzenten-Programme verbinden sich erst bei Bedarf mit dem Socket und tolerieren die Abwesenheit des Daemons (Ereignisse werden einfach verworfen, während er aus ist), sodass die Reihenfolge zwischen dem Daemon und dem Rest der Pipeline keine Rolle spielt.

85.1.54.1.4. Ruhend und aktiv

Der Daemon liest die Konfigurationsdatei erneut — die Datei, über denselben einzigen Leser von SHARE_TELEMETRY, den jede andere Komponente verwendet —, wann immer

  • die Benachrichtigung telemetry_changed eintrifft. Wer den Schalter umschreibt, sendet sie nach dem Schreiben der Datei, in beide Richtungen: pepsi-setup(1) (run und der Assistent) und die write-config-Aufgabe von pepsi-setup apply, über die die Browser-Konsole ihn ändert. Die Nutzlast (on / off) ist nur informativ; die Benachrichtigung trägt keine Autorität, und eine Benachrichtigung, die der Datei widerspricht, ändert nichts;

  • es SIGHUP empfängt;

  • sein Heartbeat auslöst (jede Minute), sodass eine Bearbeitung von Hand — oder eine Benachrichtigung, die verpasst wurde, während die Datenbank weg war — ohnehin innerhalb einer Minute wirksam wird.

Der Übergang von ruhend zu aktiv bindet den Socket und beginnt mit dem Übermitteln. Der Übergang von aktiv zu ruhend — die Zustimmung wurde zurückgezogen — schließt jede Produzenten-Verbindung, entfernt den Socket und verwirft alles, was gesammelt und noch nicht gesendet wurde, statt eine letzte Übermittlung vorzunehmen. Ein aktivierter Daemon, der nicht übermitteln kann (keine brauchbare SYSTEM_ID oder ein [pepsi-telemetry-client]-Abschnitt, der sich nicht parsen lässt), bleibt ebenfalls ruhend und sagt in seinem Log und in seiner Statuszeile, warum, statt sich in eine Neustartschleife zu beenden.

Produzenten richten ihre Senke einmal beim Start ein. pepsi-dispatch(1) lauscht auf demselben Kanal und setzt seine Stage-Worker außer Dienst, sodass die Pipeline ohne Neustart mit dem Melden beginnt (oder aufhört); die langlebigen pepsi-ingress(1) und pepsi-httpd(1) beginnen nach ihrem nächsten Neustart mit dem Melden. (Nach dem Ausschalten wird nichts, was sie senden, empfangen: der Socket ist weg.)

85.1.54.1.4.1. Die Statuszeile

Der Daemon führt eine Zeile in pepsi.telemetry_client: ob die zuletzt gelesene Datei Telemetrie eingeschaltet hat, ob er übermittelt, ob eine brauchbare SYSTEM_ID konfiguriert ist — ein Wahrheitswert, nie die Kennung —, einen kurzen Grund, wenn ein aktivierter Daemon ruht, seine Version und einen Heartbeat, der jede Minute aufgefrischt wird. Ein sauberer Stopp löscht die Zeile; eine Zeile, die älter als drei Heartbeats ist, liest sich als ein Daemon, der nicht läuft. pepsi-httpd(1), das die Tabelle lesen, aber nicht schreiben darf, entscheidet anhand ihrer, ob die Setup-Konsole anbieten kann, Telemetrie einzuschalten (siehe Aktivieren über die Konsole).

85.1.54.1.5. Den Dienst aktivieren

pepsi.target startet pepsi-telemetry-client.service bewusst nicht, anders als die eigenen Daemons der Pipeline: Das Target ist der eine Schalter, der die Pipeline startet, sodass eine Unit, die es per Wants einbezöge, auf jeder Installation liefe, gleich was der Operator geantwortet hat. (Die Unit ist PartOf= des Targets, sodass das Stoppen oder Neustarten von pepsi.target den Telemetrie-Client stoppt oder neu startet. Diese Richtung ist gewollt; nur das Hereinziehen nicht.)

Stattdessen schaltet pepsi-setup(1) die Unit am Ende eines erfolgreichen pepsi-setup run scharf (was der Assistent Ihnen auch anbietet auszuführen), wenn SHARE_TELEMETRY an ist: enable --now. Ist es aus, lässt das Setup die Unit genau so, wie der Operator sie hinterlassen hat — es startet sie nie, und es stoppt sie nicht mehr: Ein laufender Daemon ruht und übermittelt nichts, und ihn laufen zu lassen ist das, was es der Browser-Konsole erlaubt, später anzubieten, Telemetrie einzuschalten. In beiden Fällen sendet das Setup danach die Benachrichtigung telemetry_changed, sodass ein laufender Daemon der neuen Antwort sofort folgt (das Ausschalten der Telemetrie wirkt sofort, nicht erst beim nächsten Heartbeat). Eine Installation, die überhaupt keinen Telemetrie-Daemon will, deaktiviert die Unit (systemctl disable --now pepsi-telemetry-client.service); das Setup macht das nie rückgängig, solange die Antwort nein ist.

Auf einem Host ohne systemd wird nichts getan und nichts über die Unit gesagt — es gibt keine Unit scharfzuschalten. Wo systemd die Unit nicht kennt (etwa bei einer Installation aus den Quellen), sagt das Setup dies nur, wenn Telemetrie an ist, da eine Installation, die sich dagegen entschieden hat, so oder so nichts zu tun hat. Ohne root protokolliert es den einen auszuführenden systemctl-Befehl.

Mit eingeschalteter Telemetrie und ohne gültige SYSTEM_ID (das Setup wurde ohne -c ausgeführt, es gab also keinen Ort, an den eine geschrieben werden konnte) wird die Unit trotzdem scharfgeschaltet — der Daemon bleibt ruhend und sagt, warum —, und das Setup fordert Sie auf, pepsi-setup run -c <FILE> erneut auszuführen, damit eine Kennung erzeugt werden kann.

85.1.54.1.5.1. Aktivieren über die Konsole

Die Browser-Setup-Konsole (pepsi-httpd(1)) stellt dieselbe Frage SHARE_TELEMETRY, kann aber „ja“ nur anbieten, solange dieser Daemon läuft und eine brauchbare SYSTEM_ID hat — die Konsole erzeugt nie eine Kennung, denn eine ohne Zustimmung zu prägen ist genau das, was Opt-in ausschließt. Fehlt eines davon, wird die Frage deaktiviert mit Hinweisen angezeigt, und ein API-Client, der es trotzdem versucht, wird mit 409 telemetry_client_not_ready abgewiesen. Damit die Konsole Telemetrie einschalten kann, tun Sie auf dem Server Folgendes:

  1. geben Sie [pepsi] eine Kennung: SYSTEM_ID = gefolgt von 64 Hexadezimalzeichen, z. B. die Ausgabe von openssl rand -hex 32;

  2. starten Sie den Daemon: systemctl enable --now pepsi-telemetry-client.service. Er bleibt ruhend und übermittelt nichts.

Ein Speichern in der Konsole, das Telemetrie einschaltet, schreibt dann die Datei über den privilegierten Applier, der den Daemon benachrichtigt; eines, das sie ausschaltet, tut dasselbe in die andere Richtung. Das Ausschalten wird nie abgelehnt. Ein Speichern in der Konsole behält außerdem eine vorhandene SYSTEM_ID, wie auch immer die Antwort lautet: Es erzeugt die ganze Datei neu und ließ früher die Kennung weg (sodass erneutes Einschalten eine andere prägte).

85.1.54.1.6. Übermittelte Daten

Es werden zwei Übermittlungen vorgenommen (siehe pepsi-telemetry(1) für die Endpunkte):

  • POST /telemetry/usage — die Funktionszähler pro Intervall, der Pepsi-Version zugeschrieben, als die der Daemon gebaut wurde.

  • POST /telemetry/features — der Schnappschuss der aktivierten Funktionen, abgeleitet aus der kumulativen Menge der seit dem Start des Daemons gesehenen Funktionen (eine Funktion wird als aktiviert gemeldet, sobald sie in diesem Lauf mindestens einmal genutzt wurde).

Es werden keine personenbezogenen Informationen gesendet; die einzige Identität ist die zufällige 256-Bit-SYSTEM_ID, die pepsi-setup(1) erzeugt.

85.1.54.1.7. Konfiguration

Globale Schalter liegen in [pepsi] (mit den Produzenten geteilt):

SHARE_TELEMETRY

Haupt-Ein/Aus-Schalter. Opt-in: der Standardwert ist no. Solange er nicht auf yes steht, bleibt der Daemon ruhend und die Produzenten-API tut nichts.

SYSTEM_ID

Der anonyme 256-Bit-Bezeichner (64 Hex-Zeichen), der mit jedem Bericht übermittelt wird. Automatisch von pepsi-setup(1) erzeugt, sobald SHARE_TELEMETRY an ist — für eine Installation, die nicht teilnimmt, wird nie einer erzeugt; erforderlich, bevor der Daemon irgendetwas übermittelt. Ein Operator darf einen von Hand hinzufügen, während Telemetrie aus ist (damit die Konsole den Schalter anbieten kann); das ist die Handlung des Operators, nicht die des Setups.

Behandeln Sie ihn als Material, das Schreibrechte verleiht, nicht als öffentliches Etikett. Der Collector gibt ihn nie aus und prüft ihn über seine Form hinaus nie, und ein /telemetry/features-Schnappschuss ist maßgeblich für das (system_id, version), das er benennt: Er aktiviert genau die Funktionen, die er auflistet, und markiert jede andere gespeicherte als deaktiviert. Wer diesen Wert also erfährt, kann den gesamten Beitrag dieser Installation zum öffentlichen Bericht auf null setzen oder umschreiben und ihre Nutzungszähler aufblähen. Es ist ein zufälliger 256-Bit-Wert und wird von GET /telemetry/report nie zurückgegeben, sodass er nicht zu erraten ist — aber er steht in pepsi.conf, fügen Sie diesen Abschnitt also nicht in einen Fehlerbericht, ein Support-Ticket oder ein Pastebin ein. Die Anonymität ist so oder so unberührt; preisgegeben wird die Fähigkeit, die Zahlen dieser Installation zu fälschen.

TELEMETRY_SERVER

Collector-Host (Standardwert telemetry.pepsi.taler.net). Der Daemon übermittelt an https://<server>/telemetry/{usage,features}. Ein Wert mit einem expliziten scheme:// wird wörtlich übernommen (z. B. http://localhost:18080 für lokales Testen).

Die eigenen Listener-/Übermittlungs-Stellschrauben des Daemons liegen in [pepsi-telemetry-client]:

UNIXPATH

Lokaler Lausch-Socket (Standardwert /run/pepsi-telemetry/socket). Dies ist derselbe Pfad, mit dem sich die Produzenten verbinden, sodass eine Änderung beide Seiten ändert.

UNIXPATH_GROUP, UNIXPATH_MODE

Gruppe und Modus des Sockets (Standardwerte pepsi-telemetry und 0660), damit sich die Benutzer pepsi (Stage-Worker) und pepsi-ingress verbinden können.

SUBMIT_INTERVAL

Intervall zwischen Übermittlungen (Standardwert 60 s). Verwenden Sie die Einheiten h/m/s.

MAX_FEATURES

Obergrenze für die Anzahl der im Speicher gehaltenen verschiedenen Funktionsnamen (Standardwert 4096), die den Speicher gegen einen fehlerhaften lokalen Produzenten begrenzt.

85.1.54.1.8. Globale Optionen

serve ist der einzige Unterbefehl. Diese globalen Optionen stehen davor (ein nachgestelltes Flag wird zurückgewiesen).

-c FILE, –config FILE

Liest die Konfiguration aus FILE, statt die Standardorte zu durchsuchen ($XDG_CONFIG_HOME/pepsi.conf, $HOME/.config/pepsi.conf, /etc/pepsi/pepsi.conf, /etc/pepsi.conf). Die ausgelieferte Unit übergibt -c /etc/pepsi/pepsi.conf.

-L LOGLEVEL, –log LOGLEVEL

Setzt die Log-Ausführlichkeit. LOGLEVEL ist eines von error, warn, info, debug oder trace (Standardwert: info).

-v, –verbose

Zeigt Log-Meldungen aus allen Quellen, einschließlich Drittanbieter-Bibliotheken.

-h, –help

Gibt eine Verwendungsübersicht aus und beendet sich.

-V, –version

Gibt die Version aus und beendet sich.

85.1.54.1.9. Dateien

/run/pepsi-telemetry/socket

Standard-UNIX-Socket, auf dem der Daemon lauscht. Der Daemon legt den Socket selbst an; das Verzeichnis darum herum stammt aus dem RuntimeDirectory=pepsi-telemetry der Unit (Modus 0755, mit RuntimeDirectoryPreserve=yes, damit ein Stopp keinen darin noch gebundenen Socket entfernt) und gehört allein dieser Unit. pepsi-telemetry(1), der Collector, lauscht stattdessen in /run/pepsi-collector: systemd chownt ein Laufzeitverzeichnis und alles darin bei jedem Start auf den User= der deklarierenden Unit, sodass ein Collector-Socket in diesem Verzeichnis bei jedem Start dieses Daemons stillschweigend die Gruppe des Frontservers verlöre. Collector und Client sind ohnehin für getrennte Hosts gedacht.

85.1.54.1.10. Siehe auch

pepsi-telemetry(1), pepsi-ingress(1), pepsi-setup(1), pepsi-httpd(1), pepsi-dispatch(1), pepsi.conf(5).