81. pepsi-telemetry

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

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

81.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 — die einzige Identität ist die anonyme system_id — und durch MAX_BODY plus die Ratenlimits des Front-Servers begrenzt.

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

81.3. 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).

81.4. 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).

81.5. 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 ist daher nur ein Symlink — es gibt keinen Proxy-Pfad einzutragen und damit auch keinen, den man falsch machen 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, lokale Änderungen — etwa ein anderer server_name für einen privaten Collector — überstehen daher Paketaktualisierungen.

Ändern Sie den Socket-Pfad, so wird daraus eine Aussage an vier Stellen: das ListenStream= der .socket-Unit, das RuntimeDirectory= des Dienstes und die 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 — was sich lohnt, denn eine Abweichung ist im Test unsichtbar und erreicht die Produktion als nichts weiter als ein 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 deklarierenden Unit — und chownt es samt seinem Inhalt bei jedem Start — und entfernt es ohne RuntimeDirectoryPreserve=, 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.

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 — während der Collector active, gesund und still wäre und nie eine Verbindung gesehen hätte. Den Collector auf einem eigenen Host zu betreiben ist weiterhin die vorgesehene Installation, aber es ist nicht das, was die beiden auseinanderhält.

81.6. Siehe auch

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