85.1.53. pepsi-telemetry

anonymous feature-telemetry collector

Handbuchabschnitt:

1

85.1.53.1.1. Name

pepsi-telemetry - zentraler, anonymer Opt-in-Collector für Funktionstelemetrie.

85.1.53.1.2. Übersicht

pepsi-telemetry [GLOBAL-OPTIONS] serve

85.1.53.1.3. Beschreibung

pepsi-telemetry ist der zentrale Collector für Pepsis anonyme Opt-in-Funktionstelemetrie. Es ist ein kleiner HTTP-Server, bewusst getrennt von pepsi-httpd(1) und in einem eigenen Debian-Paket ausgeliefert, gedacht für den Betrieb auf einem einzigen Host (standardmäßig telemetry.pepsi.taler.net) hinter einem bestehenden nginx- oder Apache-Front-Server, der TLS terminiert und ratenbegrenzt.

Pepsi-Installationen, die teilnehmen ([pepsi] SHARE_TELEMETRY = YES; die Option ist standardmäßig no, sodass eine Installation, die sie nie gesetzt hat, nichts übermittelt und der nie auch nur eine system_id zugewiesen wird), übermitteln zwei Arten von Berichten, nur durch eine zufällige 256-Bit-system_id identifiziert (keine personenbezogenen Informationen). Der Collector speichert sie in der pepsi.telemetry-Tabelle, zählt die Nutzung pro gemeldeter Pepsi-Version und stellt einen Aggregatbericht bereit, der nie eine einzelne system_id preisgibt.

Der Collector verbindet sich als die pepsi-telemetry-Rolle über den lokalen Socket mit dem gemeinsamen pepsi-PostgreSQL-Schema. Auf einem Host, der nur Telemetrie bedient, bleibt der Rest des Schemas einfach leer. Installieren und aktualisieren Sie es mit pepsi-setup -c /etc/pepsi-telemetry/pepsi-telemetry.conf schema (siehe pepsi-setup(1)); wie jedes Pepsi-Programm verweigert der Collector den Start (Exit-Status 78) gegen ein Schema aus einem anderen Release.

85.1.53.1.4. Endpunkte

Alle drei Endpunkte liegen unter /telemetry/. Die beiden Übermittlungs-Endpunkte sind offen und nicht authentifiziert — die einzige Installations-Identität ist die anonyme system_id, und diese Identität ist selbst behauptet: Der Collector stellt sie weder aus noch prüft er irgendetwas daran über ihre Form aus 64 Hexadezimalzeichen hinaus; sie ist also ein Bezeichner und nie ein Zugangsnachweis. Missbrauch wird durch eine Obergrenze für den Anfrage-Body (MAX_BODY), die unten beschriebenen Grenzen je Übermittlung und die Ratenbegrenzung des vorgeschalteten Webservers begrenzt — beachten Sie, dass die ausgelieferte Apache-Site mod_ratelimit verwendet, das die Bandbreite der Antwort drosselt und die Anfragerate überhaupt nicht begrenzt; nur die nginx-Site hat limit_req.

POST /telemetry/features

Zeichnet den Schnappschuss der aktivierten Funktionen einer Installation auf. Body:

{"system_id": "<64 hex>", "version": "0.1.0",
 "features": {"arc": true, "dane": "strict", ...}}

Jeder Funktionswert muss ein JSON-Skalar sein: true für eine einfache Ein/Aus-Funktion oder eine Zeichenkette/Zahl für eine Funktion, die einen Modus trägt. Der Schnappschuss ist maßgeblich für (system_id, version): aufgeführte Funktionen werden aktiviert (ihr Skalar als Detailwert beibehalten), weggelassene Funktionen werden als deaktiviert markiert (ihre angesammelte Nutzung bleibt erhalten). Antwortet 204 bei Erfolg, 400 bei einem fehlerhaften Body / einer fehlerhaften system_id / einem nicht-skalaren Wert, 413, wenn der Body MAX_BODY überschreitet, 408, wenn der Body nicht innerhalb von 30 Sekunden vollständig eintrifft.

Drei weitere Schranken je Einreichung gelten für beide Einreichungs-Endpunkte, und sie bestehen, weil dies die eine Komponente ist, die dem Internet ausgesetzt ist: höchstens 512 Namen in einem Body, jeder Name 1 bis 64 Zeichen aus [A-Za-z0-9._-], und eine version von höchstens 32 Zeichen (sie ist Teil des Datensatzschlüssels, eine unbeschränkte wäre also ein unbeschränkter Vorrat an Datensätzen). Jeder Name, den Pepsi meldet, ist eine Kompilierzeitkonstante dieser Form, daher kann der Zeichensatz so eng sein.

POST /telemetry/usage

Sammelt Funktionsnutzungs-Zähler an. Body:

{"system_id": "<64 hex>", "version": "0.1.0",
 "usage": {"arc": 42, "srs": 7, ...}}

Jeder Wert ist eine nicht-negative Ganzzahl von höchstens 2^40: die Anzahl der Male, die die Funktion seit der vorherigen Übermittlung ausgeführt wurde (ein Delta). Die Zähler werden serverseitig summiert und der gemeldeten Version zugeschrieben, und die laufende Gesamtsumme je Installation wird bei 10^12 gekappt — der Endpunkt ist nicht authentifiziert und nichts entfernt einen Datensatz, sodass ein Zähler nahe der 64-Bit-Obergrenze andernfalls das Aggregat weiter unten überlaufen ließe und es dauerhaft blockierte. Die optionalen Felder period_start/period_end werden akzeptiert und ignoriert. Antwortet wie bei /telemetry/features.

GET /telemetry/report

Gibt den öffentlichen Aggregatbericht als JSON zurück. Ein Eintrag pro Funktion mit der versionsübergreifenden Zusammenfassung — deployments und uses (Gesamtzahl der Ausführungen) — plus einer versionsweisen by_version-Aufschlüsselung. deployments zählt die Installationen, deren gespeicherter Schnappschuss die Funktion aktiviert hat, und „aktiviert“ heißt „seit dem letzten Start von pepsi-telemetry-client(1) mindestens einmal ausgeführt“ — nicht „konfiguriert“. Zwei Folgen: Eine Funktion, die eingeschaltet, aber nie ausgelöst wird (dane, wenn kein Ziel TLSA veröffentlicht, tlsrpt an einem ruhigen Tag, eine Bounce-Stage, die nie feuert), wird überhaupt nie als aktiviert gemeldet; und weil die Menge des Daemons prozessbezogen ist, kippt ein Neustart die gesamte Funktionsmenge dieser Installation auf deaktiviert, bis jede Funktion erneut ausgeführt wird, sodass ein in diesem Fenster erzeugter Bericht zu niedrig zählt. Es erscheint nie eine system_id, sodass der Bericht gefahrlos offen bereitgestellt werden kann. Beispiel:

{"generated": "2026-06-27T12:00:00Z",
 "features": [
   {"name": "arc", "deployments": 298, "uses": 91234,
    "by_version": [{"version": "0.2.0", "deployments": 210, "uses": 80012}]}
 ]}

Das Skript contrib/update-feature-stability.sh verwandelt diesen Bericht in die Funktionsstabilitätstabelle des Handbuchs.

Die Zahlen sind ungeprüft, und das Protokoll lässt in seiner jetzigen Form nichts anderes zu. Weil die system_id selbst behauptet ist (siehe oben), zählt deployments verschiedene übermittelte Bezeichner, nicht verschiedene Installationen: Jeder kann hundert zufällige Bezeichner prägen und unter jedem einen Funktions-Schnappschuss und einen Nutzungszähler absetzen, was für sich genommen genügt, um eine Funktion über die stable-Schwellen der erzeugten Tabelle zu heben. Lesen Sie den Bericht und die daraus abgeleiteten Stabilitätsstufen als in gutem Glauben gemeldete Verbreitung, nicht als Beleg. Diese Lücke zu schließen erfordert, dass der Collector den Bezeichner bei einem Handshake der ersten Übermittlung ausstellt und ein Geheimnis zurückgibt, das spätere Übermittlungen vorlegen (in konstanter Zeit verglichen), oder eine gleichwertige Anforderung signierter Übermittlungen.

Eine fehlende oder leere version wird als leere Zeichenkette festgehalten statt abgelehnt, sodass ein Client, der keine meldet, dennoch beiträgt (als unbekannte Version eingeordnet).

85.1.53.1.5. Konfiguration

Der [pepsi-telemetry]-Abschnitt konfiguriert den einzigen Listener und die Grenzwerte für Anfragen; die Datenbankverbindung stammt aus dem gemeinsamen [pepsi-postgres]-Abschnitt.

Übergeben Sie immer -c /etc/pepsi-telemetry/pepsi-telemetry.conf. In dieser Datei liegt die ausgelieferte Konfiguration, aber sie ist nicht der Standardwert: Die Konfigurationsquellen-Komponente des Collectors ist pepsi, sodass die übliche Suche ohne -c /etc/pepsi/pepsi.conf oder /etc/pepsi.conf findet — die Konfiguration der Mail-Pipeline, die auf einem reinen Collector-Host überhaupt nicht existiert. pepsi-telemetry.service übergibt die Option, weshalb die ausgelieferte Installation funktioniert; ein Aufruf von Hand muss es ebenfalls tun.

SERVE

systemd (was die ausgelieferte Konfiguration setzt, socket-aktiviert über pepsi-telemetry.socket), unix oder tcp — dasselbe Listener-Vokabular, das die anderen Server verwenden. Im unix-Modus setzen Sie UNIXPATH (/run/pepsi-collector/pepsi-telemetry.sock, passend zu dem, wohin die ausgelieferten Reverse-Proxy-Sites weiterleiten) und optional UNIXPATH_GROUP (die Gruppe des Front-Webservers, z. B. www-data) und UNIXPATH_MODE (Standardwert 0660). Der tcp-Modus (BIND_TO/PORT, Standard-Port 8080) bedient Klartext und ist nur für lokales Testen gedacht. In pepsi-telemetry selbst gibt es kein TLS; der vorgeschaltete Webserver terminiert es.

MAX_BODY

Maximal akzeptierte Größe des Anfrage-Body in Bytes (Standardwert 65536).

MAX_CONNECTIONS

Obergrenze gleichzeitig bedienter Verbindungen (Standardwert 128).

DB_POOL_SIZE

Größe des Datenbank-Verbindungspools (Standardwert 2).

85.1.53.1.6. Globale Optionen

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

-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) — von denen keiner die eigene Datei des Collectors ist; geben Sie sie also immer an, siehe oben.

-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.53.1.7. Dateien

/etc/pepsi-telemetry/pepsi-telemetry.conf

Die Konfiguration des Collectors, vom Debian-Paket ausgeliefert. Sie wird nicht automatisch gefunden — siehe oben —, daher braucht jeder Aufruf -c /etc/pepsi-telemetry/pepsi-telemetry.conf.

/run/pepsi-collector/pepsi-telemetry.sock

UNIX-Socket, auf dem der Collector lauscht: unter dem ausgelieferten SERVE = systemd von pepsi-telemetry.socket gebunden, oder vom Daemon selbst angelegt, wenn Sie SERVE = unix mit diesem UNIXPATH setzen. Das Verzeichnis stammt aus dem RuntimeDirectory=pepsi-collector des Dienstes (mit RuntimeDirectoryPreserve=yes, damit das Stoppen des Dienstes keinen darin noch gebundenen Socket löscht) oder von systemd, wenn es den Socket bindet.

Das Verzeichnis gehört diesem Dienst allein, und beide Hälften davon sind Absicht. Es ist nicht /run/pepsi, das der Mail-Pipeline, und es ist nicht /run/pepsi-telemetry, das des Telemetrie-Clients (dessen eigener Socket /run/pepsi-telemetry/socket ist und pepsi gehört). systemd chownt ein Laufzeitverzeichnis und seinen Inhalt bei jedem Start auf den User= der deklarierenden Unit, sodass zwei Units, die sich ein Verzeichnis unter verschiedenen Konten teilen, einander die Sockets umschreiben: Läge der Socket des Collectors im Verzeichnis des Clients, nähme der startende Client dem Socket die Gruppe www-data weg, und der Frontserver antwortete auf jede Anfrage mit 502, während der Collector weiterliefe und nichts protokollierte, da er nie eine Verbindung zu sehen bekäme. Verschiedene Dateinamen in einem gemeinsamen Verzeichnis helfen nicht; ein eigenes Verzeichnis schon.

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

Reverse-Proxy-Site-Dateien, die (deaktiviert) vom Debian-Paket ausgeliefert werden; aktivieren Sie die zu Ihrem Front-Server passende.

85.1.53.1.8. Siehe auch

pepsi-httpd(1), pepsi-setup(1), pepsi.conf(5).