91. pepsi-telemetry

Der zentrale, anonyme Opt-in-Collector für Funktionstelemetrie.

91.1. Rolle

pepsi-telemetry sammelt anonyme Nutzungstelemetrie von Pepsi-Installationen, die per Opt-in teilnehmen. Es ist ein kleiner HTTP-Server, bewusst getrennt von pepsi-httpd und in einem eigenen Debian-Paket ausgeliefert, gedacht für den Betrieb auf einem Host — standardmäßig telemetry.pepsi.taler.net — hinter einem bestehenden nginx- oder Apache-Front-Server. Führen Sie es mit pepsi-telemetry serve aus.

Ein meldender Pepsi-Knoten wird nur durch eine zufällige 256-Bit-system_id identifiziert (keine personenbezogenen Informationen). Der Collector verbindet sich als die pepsi-telemetry-Rolle mit dem gemeinsamen pepsi-PostgreSQL-Schema und speichert alles in der pepsi.telemetry-Tabelle, wobei er die Nutzung pro gemeldeter Pepsi-Version zählt.

91.2. Funktionen

  • Zwei offene Übermittlungs-Endpunkte. POST /telemetry/features hält fest, welche Funktionen eine Installation aktiviert hat (ein Schnappschuss: aufgeführte Funktionen werden aktiviert, weggelassene deaktiviert, wobei die Nutzungshistorie erhalten bleibt), und POST /telemetry/usage sammelt Nutzungszähler pro Funktion an (Deltas, serverseitig summiert). Beide sind nicht authentifiziert und durch MAX_BODY plus die Ratenlimits des Front-Servers begrenzt; die einzige Identität ist die anonyme system_id.

  • Versionsweise Zählung. Die in jeder Übermittlung gemeldete version ist Teil des Tabellenschlüssels, sodass Nutzungsereignisse dem Pepsi-Release zugeschrieben werden, das sie erzeugt hat, und ein Upgrade separate Datensätze ansammelt.

  • Öffentlicher Aggregatbericht. GET /telemetry/report gibt funktionsweise Zusammenfassungen (verschiedene aktivierte Installationen und Gesamtnutzungen) mit einer versionsweisen Aufschlüsselung als JSON zurück. Es legt nie eine einzelne system_id offen, sodass es gefahrlos offen bereitgestellt werden kann.

  • Kein eigenes TLS. Es bedient Klartext-HTTP auf einem UNIX-Socket (/run/pepsi-collector/pepsi-telemetry.sock, wie ausgeliefert per SERVE = systemd socket-aktiviert oder mit SERVE = unix vom Daemon selbst gebunden) für einen Reverse-Proxy oder Klartext-TCP zum lokalen Testen. TLS wird vom vorgeschalteten nginx/Apache terminiert.

91.3. Grenzen und was die Zahlen wert sind

Der Collector ist die einzige Pepsi-Komponente, die dafür gedacht ist, dem Internet ohne Authentifizierung gegenüberzustehen, daher ist jede Übermittlung begrenzt: der Rumpf durch MAX_BODY und eine Lesefrist von 30 Sekunden, höchstens 512 Funktionsnamen pro Rumpf, jeder 1–64 Zeichen aus [A-Za-z0-9._-], eine version von höchstens 32 Zeichen und Nutzungsdeltas von höchstens 2^40, wobei jede laufende Summe bei 10^12 gekappt wird. Anfrage-Raten bleiben dem vorgelagerten Server überlassen: Die mitgelieferte nginx-Site hat limit_req, während mod_ratelimit der Apache-Site nur die Antwortbandbreite drosselt. Seine Datenbankrolle erreicht die Tabelle telemetry und nichts sonst (Ein Angreifer, der die Datenbank hat).

Die system_id ist selbst behauptet: Der Collector stellt sie weder aus noch verifiziert er sie. Der Bericht zählt daher übermittelte Kennungen, nicht Installationen. Jeder kann Kennungen prägen und die Zahlen einer Funktion aufblähen, und wer die Kennung einer Installation erfährt, kann deren Momentaufnahme überschreiben. Lesen Sie den Bericht und die daraus abgeleiteten Stabilitätsstufen als in gutem Glauben gemeldete Verbreitung, nicht als Beweis.

91.4. Funktionsstabilitätstabelle

Das Begleitskript contrib/update-feature-stability.sh ruft GET /telemetry/report ab und generiert Funktionsstabilität neu, wobei es jeder Funktion eine Stufe aus beidem zuweist, wie weit sie verbreitet und wie stark sie genutzt ist (eine Funktion muss für eine Stufe beide Schwellen überschreiten):

  • stable — Installationen ≥ 100 und Gesamtnutzungen ≥ 100000

  • used — Installationen ≥ 10 und Gesamtnutzungen ≥ 1000

  • experimental — andernfalls

Die Schwellen, die Quell-URL und der Ausgabepfad sind über Umgebungsvariablen überschreibbar (siehe den Skriptkopf).

91.5. Konfiguration

[pepsi-telemetry]: SERVE (unix/tcp/systemd) mit den passenden Transportoptionen (UNIXPATH/UNIXPATH_MODE/UNIXPATH_GROUP oder BIND_TO/PORT), MAX_BODY (Standardwert 65536), MAX_CONNECTIONS (Standardwert 128) und DB_POOL_SIZE (Standardwert 2). Die Datenbankverbindung stammt aus dem gemeinsamen [pepsi-postgres]-Abschnitt. Siehe Konfiguration und pepsi-telemetry(1).

91.6. Installation

Das Debian-Paket pepsi-telemetry liefert eine systemd-Service- und eine Socket-Unit (die auf /run/pepsi-collector/pepsi-telemetry.sock bedient), seine Konfigurationsdatei /etc/pepsi-telemetry/pepsi-telemetry.conf und Reverse-Proxy-Site-Dateien für nginx wie für Apache, installiert unter deren kanonischen Site-Namen:

/etc/nginx/sites-available/telemetry.pepsi.taler.net
/etc/apache2/sites-available/telemetry.pepsi.taler.net.conf

Sie kommen vollständig und deaktiviert an und zeigen bereits auf den Socket, den die ausgelieferten Units binden; eine davon zu aktivieren braucht daher nur einen Symlink. Es gibt keinen Proxy-Pfad einzutragen und damit auch keinen, den man falsch eintragen kann:

# nginx
$ ln -s ../sites-available/telemetry.pepsi.taler.net /etc/nginx/sites-enabled/
$ systemctl reload nginx

# Apache (a2ensite makes the same symlink)
$ a2enmod proxy proxy_http ssl ratelimit headers
$ a2ensite telemetry.pepsi.taler.net
$ systemctl reload apache2

Richten Sie danach ein Zertifikat für den Host ein und installieren Sie das Schema aus der eigenen Datei des Collectors, die nichts außer ihrem Abschnitt [pepsi-postgres] braucht:

$ pepsi-setup -c /etc/pepsi-telemetry/pepsi-telemetry.conf schema

Paketaktualisierungen führen das Upgrade des Schemas auf dieselbe Weise durch, und bis dahin verweigert der Collector den Start gegen ein Schema aus einem anderen Release (siehe Upgrade). Beide Site-Dateien sind conffiles, daher überstehen lokale Änderungen Paketaktualisierungen, etwa ein anderer server_name für einen privaten Collector.

Wenn Sie den Socket-Pfad ändern, müssen Sie ihn an vier Stellen ändern: im ListenStream= der .socket-Unit, im RuntimeDirectory= des Dienstes und in den beiden Site-Dateien (dazu UNIXPATH in der eigenen Konfiguration des Collectors, wenn Sie ihn auf SERVE = unix umstellen). make check-telemetry-socket, das make check ausführt, vergleicht sie und lässt den Build scheitern, wenn zwei davon nicht übereinstimmen. Diese Prüfung lohnt sich, denn eine Abweichung ist im Test unsichtbar und zeigt sich in der Produktion nur als 502 vom Front-Server.

Das Laufzeitverzeichnis des Collectors gehört ihm allein, und das ist der springende Punkt. Es ist nicht /run/pepsi (das der Mail-Pipeline, geteilt von pepsi-ingress, pepsi-httpd und der Setup-Apply-Türklingel), und es ist nicht /run/pepsi-telemetry (das des Telemetrie-Clients, dessen Socket /run/pepsi-telemetry/socket dem Benutzer pepsi gehört). systemd gibt ein Laufzeitverzeichnis dem User= der Unit, die es deklariert, und chownt es samt seinem Inhalt bei jedem Start; ohne RuntimeDirectoryPreserve= entfernt es das Verzeichnis, wenn diese Unit stoppt. Ein Verzeichnis, das sich Dienste unter verschiedenen Konten teilen, gehört daher am Ende demjenigen, der zuletzt gestartet ist, und wenn ein Dienst stoppt, löscht er die Sockets, die die anderen noch gebunden haben (Keine Unit darf es als RuntimeDirectory beanspruchen).

Unterschiedliche Dateinamen in einem gemeinsamen Verzeichnis sind kein Schutz. Läge der Socket des Collectors im Verzeichnis des Clients, würde ein Host, der beide betreibt, funktionieren, bis der Client das nächste Mal startet; der Socket des Collectors würde dann auf pepsi:pepsi gechownt, verlöre die Gruppe www-data, über die der Front-Server sich verbindet, und jede Anfrage würde zu einem 502. Der Collector bliebe dabei active, gesund und still und hätte nie eine Verbindung gesehen. Den Collector auf einem eigenen Host zu betreiben ist weiterhin die vorgesehene Installation, aber es ist nicht das, was die beiden auseinanderhält.

91.7. Siehe auch

pepsi-telemetry-client (der hostweise Client, der an diesen Collector übermittelt), pepsi-httpd, pepsi-setup, Funktionsstabilität, pepsi.conf(5).