67. pepsi-telemetry-client

The per-host feature-telemetry aggregator: collects local feature-usage events and submits anonymous aggregates to the central collector.

67.1. Role

pepsi-telemetry-client is the producer side of Pepsi’s anonymous feature telemetry; the central collector is pepsi-telemetry. It ships in the main Pepsi package and runs as a small daemon on every deployment that has telemetry enabled. Run it with pepsi-telemetry-client serve.

The Pepsi programs on the host (the stage workers and pepsi-ingress) report feature use through an internal, non-blocking telemetry_update call that hands a short feature name to this daemon over a local UNIX socket — the calling stage never waits on the network. The daemon aggregates those events and submits them to TELEMETRY_SERVER under the deployment’s anonymous SYSTEM_ID.

67.2. How it works

  • Local socket. The daemon listens on [pepsi-telemetry-client] UNIXPATH (default /run/pepsi-telemetry/socket), group-shared with the pepsi and pepsi-ingress users. Each producer holds one persistent connection for the lifetime of its process and reconnects if the daemon restarts; events are dropped (best-effort) while it is unreachable, so a producer is never blocked.

  • In-memory aggregation. A per-interval count is kept for each feature, plus the cumulative set of feature names seen since start-up (the enabled-features snapshot). The number of distinct names is capped by MAX_FEATURES.

  • Periodic submission. Every SUBMIT_INTERVAL (default: at most once per minute) the daemon POSTs the per-interval counts to /telemetry/usage and the cumulative feature set to /telemetry/features, then resets the per-interval counts. A failed usage submission is retained and retried next interval rather than lost.

  • Clean shutdown. On SIGINT/SIGTERM it makes one final submission before exiting.

The daemon stamps each submission with the Pepsi release version it was built as, so the collector counts feature use per release.

67.3. Configuration

The master switch is [pepsi] SHARE_TELEMETRY, and it is off by default: telemetry is opt-in, so an installation that never answered the question runs no telemetry at all. Until it is set to yes the daemon exits immediately (exit status 0) and the in-process telemetry_update calls are no-ops that open no socket — the whole path is inert whether or not the service unit is enabled. [pepsi] SYSTEM_ID (generated by pepsi-setup, but only once the switch is on) and TELEMETRY_SERVER (default telemetry.pepsi.taler.net) complete the global configuration; the daemon’s own listener and timing knobs are in [pepsi-telemetry-client]. See pepsi-telemetry-client(1) and pepsi.conf(5) for the full list.

67.4. Enabling the service

The unit is deliberately not part of pepsi.target, unlike every other Pepsi daemon: the target is the single switch that starts the pipeline, and a unit named there would run on every deployment whatever the operator answered. pepsi-setup run instead matches the unit to the answer at the end of a successful run — systemctl enable --now when the switch is on, disable --now when it is not, so turning telemetry off stops the daemon rather than leaving it to notice. It will not enable a unit that has no valid SYSTEM_ID to start with, because the daemon refuses to run in that state and would only be restarted in a loop. Hosts without systemd, without the unit installed, or without root are told the one command to run instead.

67.5. Privacy

No personally identifying information leaves the host. The only identity is the random 256-bit SYSTEM_ID; the payloads are feature names and counts. Nothing is shared unless an operator asks for it: the switch defaults to off, the setup wizard asks the question with no as the default answer, and no identifier is generated for a deployment that has not opted in. An operator who has opted in can stop sharing again by setting SHARE_TELEMETRY = NO — the next pepsi-setup run then stops and disables the service as well — or by stopping/disabling the pepsi-telemetry-client service directly.

67.6. See also

pepsi-telemetry (the collector), pepsi-setup.