85.1.53. pepsi-telemetry

anonymous feature-telemetry collector

Section du manuel:

1

85.1.53.1.1. Nom

pepsi-telemetry - collecteur central et anonyme, sur consentement explicite, de la télémétrie de fonctionnalités.

85.1.53.1.2. Synopsis

pepsi-telemetry [GLOBAL-OPTIONS] serve

85.1.53.1.3. Description

pepsi-telemetry est le collecteur central de la télémétrie de fonctionnalités de Pepsi, anonyme et sur consentement explicite. C’est un petit serveur HTTP, délibérément séparé de pepsi-httpd(1) et livré dans son propre paquet Debian, destiné à s’exécuter sur un seul hôte (par défaut telemetry.pepsi.taler.net) derrière un serveur frontal nginx ou Apache existant qui termine le TLS et limite le débit.

Les installations Pepsi qui donnent leur consentement ([pepsi] SHARE_TELEMETRY = YES ; l’option vaut no par défaut, de sorte qu’une installation qui ne l’a jamais réglée ne soumet rien et ne se voit même jamais attribuer de system_id) soumettent deux sortes de rapport, identifiés uniquement par un system_id aléatoire de 256 bits (aucune information identifiant personnellement). Le collecteur les stocke dans la table pepsi.telemetry, en comptant l’usage par version Pepsi rapportée, et expose un rapport agrégé qui ne révèle jamais un system_id individuel.

Le collecteur se connecte au schéma PostgreSQL pepsi partagé en tant que rôle pepsi-telemetry via la socket locale. Sur un hôte qui ne sert que la télémétrie, le reste du schéma reste simplement vide. Installez-le et mettez-le à niveau avec pepsi-setup -c /etc/pepsi-telemetry/pepsi-telemetry.conf schema (voir pepsi-setup(1)) ; comme tout programme Pepsi, le collecteur refuse de démarrer (code de sortie 78) sur un schéma d’une autre version.

85.1.53.1.4. Points de terminaison

Les trois points de terminaison résident sous /telemetry/. Les deux points de terminaison de soumission sont ouverts et non authentifiés — la seule identité de déploiement est le system_id anonyme, et cette identité est auto-déclarée : le collecteur ne l’émet pas et ne vérifie rien à son sujet au-delà de sa forme de 64 caractères hexadécimaux ; c’est donc un identifiant, jamais un justificatif. L’abus est borné par un plafond de corps de requête (MAX_BODY), les limites par soumission décrites ci-dessous et la limitation de débit du serveur web frontal — notez que le site Apache livré utilise mod_ratelimit, qui freine la bande passante des réponses et ne limite pas du tout la cadence des requêtes ; seul le site nginx a limit_req.

POST /telemetry/features

Enregistrer l”instantané des fonctionnalités activées d’un déploiement. Corps

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

Chaque valeur de fonctionnalité doit être un scalaire JSON : true pour une simple fonctionnalité activée/désactivée, ou une chaîne/un nombre pour une fonctionnalité portant un mode. L’instantané fait autorité pour (system_id, version) : les fonctionnalités qu’il liste deviennent activées (leur scalaire conservé comme valeur de détail), les fonctionnalités qu’il omet sont marquées désactivées (leur usage accumulé est conservé). Répond 204 en cas de succès, 400 pour un corps malformé / un mauvais system_id / une valeur non scalaire, 413 lorsque le corps dépasse MAX_BODY, 408 lorsque le corps n’achève pas d’arriver dans les 30 secondes.

Trois bornes supplémentaires par soumission s’appliquent aux deux points de terminaison de soumission, et existent parce que c’est le seul composant exposé à l’internet : au plus 512 noms dans un corps, chaque nom faisant de 1 à 64 caractères parmi [A-Za-z0-9._-], et une version d’au plus 32 caractères (elle fait partie de la clé de ligne, de sorte qu’une version non bornée est une réserve de lignes non bornée). Chaque nom que Pepsi rapporte est une constante de compilation de cette forme, de sorte que le jeu de caractères peut être aussi étroit.

POST /telemetry/usage

Accumuler les comptes d’usage des fonctionnalités. Corps

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

Chaque valeur est un entier non négatif ne dépassant pas 2^40 : le nombre de fois où la fonctionnalité a été exercée depuis la soumission précédente (un delta). Les comptes sont sommés côté serveur et attribués à la version rapportée, et le total courant par déploiement est plafonné à 10^12 — le point de terminaison n’est pas authentifié et rien ne purge une ligne, de sorte qu’un compte proche du plafond 64 bits ferait sinon déborder l’agrégat ci-dessous et le coincerait définitivement. Les champs facultatifs period_start/period_end sont acceptés et ignorés. Répond comme pour /telemetry/features.

GET /telemetry/report

Renvoyer le rapport agrégé public en JSON. Une entrée par fonctionnalité avec le récapitulatif inter-versions — deployments et uses (compte total d’exercices) — plus une ventilation by_version par version. deployments compte les déploiements dont l’instantané stocké porte la fonctionnalité activée, et « activée » signifie « exercée au moins une fois depuis le dernier démarrage de pepsi-telemetry-client(1) » — et non « configurée ». Deux conséquences : une fonctionnalité enclenchée mais jamais déclenchée (dane là où aucune destination ne publie de TLSA, tlsrpt un jour calme, une étape de rebond qui ne se déclenche jamais) n’est jamais rapportée comme activée ; et comme l’ensemble tenu par le démon est propre au processus, le redémarrer bascule tout l’ensemble de fonctionnalités de ce déploiement à désactivé jusqu’à ce que chaque fonctionnalité soit exercée de nouveau, de sorte qu’un rapport engendré dans cette fenêtre sous-compte. Aucun system_id n’apparaît jamais, de sorte que le rapport peut être servi ouvertement sans risque. Exemple

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

Le script contrib/update-feature-stability.sh transforme ce rapport en la table de stabilité des fonctionnalités du manuel.

Les chiffres ne sont pas vérifiés, et ne peuvent pas l’être en l’état du protocole. Comme system_id est auto-déclaré (ci-dessus), deployments compte les identifiants distincts qui ont été soumis, non les installations distinctes : n’importe qui peut frapper une centaine d’identifiants aléatoires et poster sous chacun un instantané de fonctionnalités et un compte d’usage, ce qui suffit à soi seul à porter une fonctionnalité au-delà des seuils stable de la table engendrée. Lisez le rapport, et les paliers de stabilité qui en dérivent, comme une adoption rapportée de bonne foi et non comme une preuve. Combler l’écart demande que le collecteur émette l’identifiant lors d’une poignée de main à la première soumission et renvoie un secret que les soumissions ultérieures présentent (comparé en temps constant), ou une exigence équivalente de soumission signée.

Une version manquante ou vide est notée comme la chaîne vide plutôt que rejetée, de sorte qu’un client qui n’en rapporte aucune contribue tout de même (regroupé comme une version inconnue).

85.1.53.1.5. Configuration

La section [pepsi-telemetry] configure l’unique listener et les limites de requête ; la connexion à la base de données provient de la section partagée [pepsi-postgres].

Passez toujours -c /etc/pepsi-telemetry/pepsi-telemetry.conf. C’est là que réside la configuration livrée, mais ce n’est pas la valeur par défaut : le composant source de configuration du collecteur est pepsi, de sorte que sans -c la recherche habituelle trouve /etc/pepsi/pepsi.conf ou /etc/pepsi.conf — la configuration du pipeline de courrier, qui sur un hôte dédié au collecteur n’existe pas du tout. pepsi-telemetry.service passe l’option, et c’est pourquoi le déploiement livré fonctionne ; une exécution à la main doit le faire elle aussi.

SERVE

systemd (ce que règle la configuration livrée, activation par socket via pepsi-telemetry.socket), unix ou tcp — le même vocabulaire de listener que celui des autres serveurs. En mode unix, réglez UNIXPATH (/run/pepsi-collector/pepsi-telemetry.sock, ce vers quoi pointent les sites reverse-proxy livrés) et facultativement UNIXPATH_GROUP (le groupe du serveur web frontal, par exemple www-data) et UNIXPATH_MODE (par défaut 0660). Le mode tcp (BIND_TO/PORT, port 8080 par défaut) sert en clair et est destiné aux tests locaux uniquement. Il n’y a pas de TLS dans pepsi-telemetry lui-même ; le serveur web frontal le termine.

MAX_BODY

Taille maximale acceptée du corps de requête en octets (par défaut 65536).

MAX_CONNECTIONS

Plafond des connexions servies simultanément (par défaut 128).

DB_POOL_SIZE

Taille du pool de connexions à la base de données (par défaut 2).

85.1.53.1.6. Options globales

serve est la seule sous-commande. Ces options globales la précèdent (un indicateur placé à la fin est rejeté).

-c FILE, –config FILE

Lit la configuration depuis FILE au lieu de parcourir les emplacements par défaut ($XDG_CONFIG_HOME/pepsi.conf, $HOME/.config/pepsi.conf, /etc/pepsi/pepsi.conf, /etc/pepsi.conf) — dont aucun n’est le fichier propre au collecteur, alors passez-le toujours ; voir ci-dessus.

-L LOGLEVEL, –log LOGLEVEL

Règle la verbosité de journalisation. LOGLEVEL est l’un de error, warn, info, debug ou trace (par défaut : info).

-v, –verbose

Affiche les messages de journal de toutes les sources, y compris les bibliothèques tierces.

-h, –help

Affiche un résumé d’utilisation et quitte.

-V, –version

Affiche la version et quitte.

85.1.53.1.7. Fichiers

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

La configuration du collecteur, livrée par le paquet Debian. Elle n’est pas trouvée automatiquement — voir ci-dessus — de sorte que chaque invocation a besoin de -c /etc/pepsi-telemetry/pepsi-telemetry.conf.

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

Socket UNIX sur laquelle le collecteur écoute : liée par pepsi-telemetry.socket sous le SERVE = systemd livré, ou créée par le démon lui-même si vous réglez SERVE = unix avec cet UNIXPATH. Le répertoire provient du RuntimeDirectory=pepsi-collector du service (avec RuntimeDirectoryPreserve=yes, de sorte que l’arrêt du service ne supprime pas une socket encore liée à l’intérieur), ou de systemd lorsqu’il lie la socket.

Le répertoire n’appartient qu’à ce seul service, et les deux moitiés de cet énoncé sont délibérées. Ce n’est pas /run/pepsi, celui du pipeline de courrier, et ce n’est pas /run/pepsi-telemetry, celui du client de télémétrie (dont la socket propre est /run/pepsi-telemetry/socket, possédée par pepsi). systemd applique à chaque démarrage un chown du répertoire d’exécution et de son contenu vers le User= de l’unité qui le déclare, de sorte que deux unités partageant un répertoire sous des comptes différents réécrivent mutuellement leurs sockets : si la socket du collecteur se trouvait dans le répertoire du client, le démarrage du client retirerait à la socket son groupe www-data et le serveur frontal répondrait 502 à chaque requête tandis que le collecteur resterait en fonctionnement sans rien journaliser, n’ayant jamais vu de connexion. Des noms de fichiers distincts dans un répertoire partagé n’y aident pas ; un répertoire à soi, si.

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

Fichiers de site reverse-proxy livrés (désactivés) par le paquet Debian ; activez celui qui correspond à votre serveur frontal.

85.1.53.1.8. Voir aussi

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