85.1.54. pepsi-telemetry-client

per-host feature-telemetry aggregator and submitter

Section du manuel:

1

85.1.54.1.1. Nom

pepsi-telemetry-client - agréger la télémétrie locale d’usage des fonctionnalités et la soumettre au collecteur central.

85.1.54.1.2. Synopsis

pepsi-telemetry-client [GLOBAL-OPTIONS] serve

85.1.54.1.3. Description

pepsi-telemetry-client est le côté producteur par hôte de la télémétrie de fonctionnalités anonyme de Pepsi (le collecteur central est pepsi-telemetry(1)). C’est un petit démon de longue durée qui :

  • écoute sur une socket UNIX locale les événements d’usage de fonctionnalités émis par les programmes Pepsi sur le même hôte (les workers d’étape et pepsi-ingress(1), via l’API interne telemetry_update) ;

  • accumule les événements en mémoire — un décompte par intervalle pour chaque fonctionnalité plus l’ensemble cumulatif des fonctionnalités vues cette exécution ;

  • à chaque SUBMIT_INTERVAL (par défaut : au plus une fois par minute), soumet les décomptes au collecteur à TELEMETRY_SERVER sous le SYSTEM_ID anonyme de ce déploiement et réinitialise les décomptes par intervalle (en les refusionnant pour réessai si une soumission échoue) ;

  • à l’arrêt (SIGINT/SIGTERM), effectue une dernière soumission afin qu’un arrêt propre ne perde pas l’intervalle courant.

Il ne détient aucun secret hormis le SYSTEM_ID anonyme ; son seul trafic sortant est du HTTPS vers le collecteur. Sa connexion à la base de données (sous le rôle pepsi) sert à deux choses et à rien d’autre : un LISTEN sur le canal telemetry_changed, et l’enregistrement de vie à une seule ligne pepsi.telemetry_client décrit ci-dessous. Sans base de données, il fonctionne quand même, en suivant le fichier de configuration à chaque heartbeat.

La télémétrie est sur consentement explicite : à moins que [pepsi] SHARE_TELEMETRY n’ait été réglé sur yes, l’API producteur est sans effet et n’ouvre aucune socket, et le démon tourne en sommeil — il ne lie aucune socket, ne collecte rien et ne soumet rien. C’est ce que reçoit une installation qui n’a jamais répondu à la question, que l’unité de service soit activée ou non. Une option absente, une section [pepsi] absente et une valeur inanalysable se lisent toutes comme désactivées — « je n’ai pas pu savoir » n’est jamais un consentement — et l’interrupteur est consulté avant que [pepsi-telemetry-client] ne soit analysée le moins du monde, de sorte qu’une faute de frappe dans une section qui ne peut pas compter ne peut pas affecter un démon en sommeil.

Les programmes producteurs se connectent à la socket paresseusement et tolèrent l’absence du démon (les événements sont simplement abandonnés tant qu’il est arrêté), de sorte que l’ordre entre le démon et le reste du pipeline n’a pas d’importance.

85.1.54.1.4. En sommeil et actif

Le démon relit le fichier de configuration — le fichier, par le même lecteur unique de SHARE_TELEMETRY qu’utilisent tous les autres composants — chaque fois que

  • la notification telemetry_changed arrive. Quiconque réécrit l’interrupteur l’envoie après avoir écrit le fichier, dans les deux sens : pepsi-setup(1) (run et l’assistant) et la tâche write-config de pepsi-setup apply, par laquelle la console du navigateur le modifie. La charge utile (on / off) est informative ; la notification ne porte aucune autorité, et une notification en désaccord avec le fichier ne change rien ;

  • il reçoit SIGHUP ;

  • son heartbeat se déclenche (chaque minute), de sorte qu’une modification à la main — ou une notification manquée pendant que la base de données était absente — prend de toute façon effet en moins d’une minute.

Passer du sommeil à l’activité lie la socket et commence les soumissions. Passer de l’activité au sommeil — consentement retiré — ferme toutes les connexions des producteurs, supprime la socket et jette tout ce qui a été collecté et pas encore envoyé plutôt que de faire une dernière soumission. Un démon activé qui ne peut pas soumettre (pas de SYSTEM_ID utilisable, ou une section [pepsi-telemetry-client] qui ne s’analyse pas) reste lui aussi en sommeil, et dit pourquoi dans son journal et dans sa ligne d’état, au lieu de sortir et d’entrer dans une boucle de redémarrage.

Les producteurs installent leur récepteur une seule fois, au démarrage. pepsi-dispatch(1) écoute sur le même canal et retire ses workers d’étape, de sorte que le pipeline commence (ou cesse) de rendre compte sans redémarrage ; les processus de longue durée pepsi-ingress(1) et pepsi-httpd(1) commencent à rendre compte après leur prochain redémarrage. (Après la désactivation, rien de ce qu’ils envoient n’est reçu : la socket a disparu.)

85.1.54.1.4.1. La ligne d’état

Le démon tient une ligne dans pepsi.telemetry_client : si le fichier qu’il a lu en dernier active la télémétrie, s’il soumet, si un SYSTEM_ID utilisable est configuré — un booléen, jamais l’identifiant —, une courte raison lorsqu’un démon activé est en sommeil, sa version, et un heartbeat rafraîchi chaque minute. Un arrêt propre supprime la ligne ; une ligne plus ancienne que trois heartbeats se lit comme un démon qui ne tourne pas. pepsi-httpd(1), qui peut lire la table mais pas y écrire, s’en sert pour décider si la console de configuration peut proposer d’activer la télémétrie (voir Activation depuis la console).

85.1.54.1.5. Activer le service

pepsi.target ne démarre délibérément pas pepsi-telemetry-client.service, contrairement aux démons propres du pipeline : la cible est l’unique interrupteur qui démarre le pipeline, de sorte qu’une unité qu’elle entraîne par son Wants tournerait sur chaque déploiement quelle qu’ait été la réponse de l’opérateur. (L’unité est PartOf= la cible, de sorte qu’arrêter ou redémarrer pepsi.target arrête ou redémarre le client de télémétrie. Ce sens-là est voulu ; seul l’entraînement par la cible ne l’est pas.)

À la place, pepsi-setup(1) arme l’unité à la fin d’un pepsi-setup run réussi (ce que l’assistant propose aussi d’exécuter pour vous) lorsque SHARE_TELEMETRY est activé : enable --now. Lorsqu’il est désactivé, la configuration laisse l’unité exactement dans l’état où l’opérateur l’a laissée — elle ne la démarre jamais, et ne l’arrête plus : un démon en cours d’exécution est en sommeil et ne soumet rien, et le garder en marche est ce qui permet à la console du navigateur de proposer plus tard d’activer la télémétrie. Dans les deux cas, la configuration envoie ensuite la notification telemetry_changed, de sorte qu’un démon en cours d’exécution suit aussitôt la nouvelle réponse (désactiver la télémétrie prend effet immédiatement, pas au prochain heartbeat). Un déploiement qui ne veut aucun démon de télémétrie désactive l’unité (systemctl disable --now pepsi-telemetry-client.service) ; la configuration ne défait jamais cela tant que la réponse est non.

Sur un hôte sans systemd, rien n’est fait et rien n’est dit de l’unité — il n’y a pas d’unité à armer. Là où systemd ne connaît pas l’unité (une installation depuis les sources, par exemple), la configuration ne le signale que si la télémétrie est activée, puisqu’un déploiement qui a refusé n’a de toute façon rien à faire. Sans root, elle journalise l’unique commande systemctl à exécuter.

Avec la télémétrie activée et aucun SYSTEM_ID valide (la configuration a été lancée sans -c, il n’y avait donc nulle part où en écrire un), l’unité est armée malgré tout — le démon reste en sommeil et dit pourquoi — et la configuration vous indique de relancer pepsi-setup run -c <FILE> pour qu’un identifiant puisse être généré.

85.1.54.1.5.1. Activation depuis la console

La console de configuration du navigateur (pepsi-httpd(1)) pose la même question SHARE_TELEMETRY, mais elle ne peut proposer « oui » que tant que ce démon tourne et dispose d’un SYSTEM_ID utilisable — la console ne génère jamais d’identifiant, puisqu’en frapper un sans consentement est précisément ce que le consentement explicite exclut. Lorsque l’un ou l’autre manque, la question est affichée désactivée, avec des indications, et un client de l’API qui essaie malgré tout est refusé avec 409 telemetry_client_not_ready. Pour que la console puisse activer la télémétrie, sur le serveur :

  1. donnez un identifiant à [pepsi] : SYSTEM_ID = suivi de 64 caractères hexadécimaux, par exemple la sortie de openssl rand -hex 32 ;

  2. démarrez le démon : systemctl enable --now pepsi-telemetry-client.service. Il reste en sommeil et ne soumet rien.

Un enregistrement dans la console qui active la télémétrie écrit alors le fichier par l’intermédiaire de l’applicateur privilégié, qui notifie le démon ; un enregistrement qui la désactive fait de même dans l’autre sens. La désactivation n’est jamais refusée. Un enregistrement dans la console conserve aussi un SYSTEM_ID existant, quelle que soit la réponse : il régénère le fichier entier, et en perdait autrefois l’identifiant (de sorte qu’une réactivation en frappait un différent).

85.1.54.1.6. Données soumises

Deux soumissions sont effectuées (voir pepsi-telemetry(1) pour les points de terminaison) :

  • POST /telemetry/usage — les décomptes de fonctionnalités par intervalle, attribués à la version Pepsi sous laquelle le démon a été construit.

  • POST /telemetry/features — l’instantané des fonctionnalités activées, dérivé de l’ensemble cumulatif des fonctionnalités vues depuis le démarrage du démon (une fonctionnalité est rapportée activée dès qu’elle a été exercée au moins une fois cette exécution).

Aucune information permettant d’identifier une personne n’est envoyée ; la seule identité est le SYSTEM_ID aléatoire de 256 bits que pepsi-setup(1) génère.

85.1.54.1.7. Configuration

Les interrupteurs globaux résident dans [pepsi] (partagés avec les producteurs) :

SHARE_TELEMETRY

Interrupteur principal marche/arrêt. Sur consentement explicite : la valeur par défaut est no. Tant qu’il n’est pas réglé sur yes, le démon reste en sommeil et l’API producteur ne fait rien.

SYSTEM_ID

L’identifiant anonyme de 256 bits (64 caractères hexadécimaux) soumis avec chaque rapport. Généré automatiquement par pepsi-setup(1) une fois SHARE_TELEMETRY activé — un déploiement qui n’a pas donné son consentement explicite ne s’en voit jamais générer un ; requis avant que le démon ne soumette quoi que ce soit. Un opérateur peut en ajouter un à la main tant que la télémétrie est désactivée (pour que la console puisse proposer l’interrupteur) ; c’est un acte de l’opérateur, pas de la configuration.

Traitez-le comme du matériel conférant un droit d’écriture, non comme une étiquette publique. Le collecteur ne l’émet jamais et ne le vérifie jamais au-delà de sa forme, et un instantané /telemetry/features fait autorité pour le couple (system_id, version) qu’il nomme : il active exactement les fonctionnalités qu’il liste et marque désactivée toute autre fonctionnalité stockée. Ainsi, quiconque apprend cette valeur peut annuler, ou réécrire, toute la contribution de ce déploiement au rapport public, et peut gonfler ses décomptes d’usage. C’est une valeur aléatoire de 256 bits et elle n’est jamais renvoyée par GET /telemetry/report, elle ne peut donc pas être devinée — mais elle réside dans pepsi.conf, alors ne collez pas cette section dans un rapport de bogue, un ticket de support ou un pastebin. L’anonymat n’est affecté dans aucun des deux cas ; ce qui fuit est la capacité de falsifier les chiffres de ce déploiement.

TELEMETRY_SERVER

Hôte du collecteur (par défaut telemetry.pepsi.taler.net). Le démon soumet à https://<server>/telemetry/{usage,features}. Une valeur contenant un scheme:// explicite est honorée telle quelle (par exemple http://localhost:18080 pour des tests locaux).

Les réglages de listener/soumission propres au démon résident dans [pepsi-telemetry-client] :

UNIXPATH

Socket d’écoute locale (par défaut /run/pepsi-telemetry/socket). C’est le même chemin auquel les producteurs se connectent, de sorte que le changer change les deux côtés.

UNIXPATH_GROUP, UNIXPATH_MODE

Groupe et mode de la socket (par défaut pepsi-telemetry et 0660), afin que les utilisateurs pepsi (workers d’étape) et pepsi-ingress puissent se connecter.

SUBMIT_INTERVAL

Intervalle entre les soumissions (par défaut 60 s). Utilisez les unités h/m/s.

MAX_FEATURES

Plafond du nombre de noms de fonctionnalités distincts tenus en mémoire (par défaut 4096), bornant la mémoire contre un producteur local au comportement défaillant.

85.1.54.1.8. Options globales

serve est la seule sous-commande. Ces options globales la précèdent (un drapeau placé après 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). L’unité livrée passe -c /etc/pepsi/pepsi.conf.

-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.54.1.9. Fichiers

/run/pepsi-telemetry/socket

Socket UNIX par défaut sur laquelle le démon écoute. Le démon crée lui-même la socket ; le répertoire qui l’entoure provient du RuntimeDirectory=pepsi-telemetry de l’unité (mode 0755, avec RuntimeDirectoryPreserve=yes afin qu’un arrêt ne délie pas une socket encore liée à l’intérieur), et appartient à cette seule unité. pepsi-telemetry(1), le collecteur, écoute plutôt dans /run/pepsi-collector : systemd attribue par chown un répertoire d’exécution et tout ce qu’il contient au User= de l’unité déclarante à chaque démarrage, de sorte qu’une socket du collecteur placée dans ce répertoire perdrait silencieusement le groupe du serveur frontal à chaque démarrage de ce démon. Le collecteur et le client sont de toute façon destinés à des hôtes séparés.

85.1.54.1.10. Voir aussi

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