92. pepsi-telemetry-client¶
The per-host feature-telemetry aggregator: collects local feature-usage events and submits anonymous aggregates to the central collector.
92.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. It also runs, dormant, on a deployment that has not enabled telemetry
but wants the browser console to be able to switch it on. Run it with pepsi-telemetry-client serve.
The Pepsi programs on the host (the stage workers, pepsi-ingress,
pepsi-httpd, pepsi-dispatch and the operator tools) 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.
92.2. How it works¶
Local socket. The daemon listens on
[pepsi-telemetry-client] UNIXPATH(default/run/pepsi-telemetry/socket). The socket is group-shared with thepepsi,pepsi-ingress,pepsi-httpdandpepsi-keydiscusers (members of grouppepsi-telemetry). Its directory belongs to this unit alone; the collector listens in/run/pepsi-collector. 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 daemonPOSTs the per-interval counts to/telemetry/usageand 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.
Dormant while off. With telemetry off it binds no socket and gathers and submits nothing. It re-reads the configuration file on
SIGHUP, every minute and on thetelemetry_changednotification, and then wakes up or goes back to sleep. Whoever rewrites the switch sends that notification, in both directions:pepsi-setupand the console’swrite-configtask. Going dormant discards what was gathered and not yet sent. The notification carries no authority; only the file decides.Status row. It keeps one row in
pepsi.telemetry_clientand deletes it on a clean stop. The row records whether the daemon is running, enabled and submitting, whether a usableSYSTEM_IDis configured (a boolean, never the identifier), and a heartbeat.pepsi-httpdreads it to decide whether the setup console may offer to switch telemetry on.
The daemon stamps each submission with the Pepsi release version it was built as, so the collector counts feature use per release.
92.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 stays dormant 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]: UNIXPATH (default
/run/pepsi-telemetry/socket), UNIXPATH_MODE (default 0660),
UNIXPATH_GROUP (default pepsi-telemetry, the group that pepsi,
pepsi-ingress, pepsi-httpd and pepsi-keydisc are added to),
SUBMIT_INTERVAL (default 60 s, which must use h/m/s units and
may not be zero) and MAX_FEATURES
(default 4096). See pepsi-telemetry-client(1) and
pepsi.conf(5) for the full list.
92.4. Enabling the service¶
The unit is deliberately not started by pepsi.target, unlike the
pipeline’s own daemons. The target is the single switch that starts the
pipeline, and a unit named there would run on every deployment whatever the
operator answered. The unit is PartOf= the target, though, so stopping or
restarting the target does reach it.
pepsi-setup run instead arms the unit at the end of a successful run when
the switch is on (systemctl enable --now); when it is off it leaves the unit
as the operator left it: it neither starts nor stops the unit, because a running
daemon is dormant and is what the console needs. Either way it then
sends telemetry_changed, so turning telemetry off takes effect at once. With
the switch on and no valid SYSTEM_ID the unit is armed anyway; the daemon
stays dormant and says why. On a host without systemd, setup does nothing (there
is no unit to arm). Where systemd does not know the unit, setup says so only
when telemetry is on, and without root it logs the one systemctl command to
run.
92.4.1. Enabling it from the console¶
The browser setup console offers “yes” only while the daemon is running and a
SYSTEM_ID is configured; otherwise the question is disabled with directions,
and an API request to switch on is refused (409
telemetry_client_not_ready). The console never generates an identifier. To
let it offer the switch, on the server add SYSTEM_ID = and 64 hexadecimal
characters (e.g. openssl rand -hex 32) to [pepsi] and run systemctl
enable --now pepsi-telemetry-client.service. A console save keeps an existing
identifier whatever the answer.
92.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 in two ways. One is to set SHARE_TELEMETRY = NO,
either in the console or in the file followed by pepsi-setup run (or
SIGHUP, or a minute’s wait); the daemon then goes dormant and discards what
it had not sent. The other is to stop or disable the pepsi-telemetry-client
service directly.
The boundary is the daemon, not the console: it believes only the configuration
file, read through the one function every component uses, and an absent or
unparseable switch reads as off. A telemetry_changed notification cannot
turn it on, and pepsi-httpd may read the status row but not write it, so a
console cannot forge “ready”. The privacy claim this upholds is part of
Assets; the console’s side is described in Switching feature telemetry on from the console.
SYSTEM_ID is an identifier, not a secret that the collector checks. But
anybody who learns it can rewrite this deployment’s contribution to the public report,
so it is masked like a credential wherever configuration is shown
(pepsi-config dump, the administrative API, the settings-by-e-mail reply).
92.6. See also¶
pepsi-telemetry (the collector), pepsi-setup, pepsi-telemetry-client(1), pepsi.conf(5).