70.1.43. pepsi-telemetry-client

per-host feature-telemetry aggregator and submitter

Manual section:

1

70.1.43.1.1. Name

pepsi-telemetry-client - aggregate local feature-usage telemetry and submit it to the central collector.

70.1.43.1.2. Synopsis

pepsi-telemetry-client [GLOBAL-OPTIONS] serve

70.1.43.1.3. Description

pepsi-telemetry-client is the per-host producer side of Pepsi’s anonymous feature telemetry (the central collector is pepsi-telemetry(1)). It is a small long-lived daemon that:

  • listens on a local UNIX socket for feature-usage events emitted by the Pepsi programs on the same host (the stage workers and pepsi-ingress(1), via the internal telemetry_update API);

  • accumulates the events in memory — a per-interval count for each feature plus the cumulative set of features seen this run;

  • every SUBMIT_INTERVAL (default: at most once per minute) submits the counts to the collector at TELEMETRY_SERVER under this deployment’s anonymous SYSTEM_ID and resets the per-interval counts (re-merging them for retry if a submission fails);

  • on shutdown (SIGINT/SIGTERM) makes one final submission so a clean stop does not lose the current interval.

It holds no database connection and no secrets beyond the anonymous SYSTEM_ID; its only outbound traffic is HTTPS to the collector.

Telemetry is opt-in: unless [pepsi] SHARE_TELEMETRY has been set to yes, the daemon logs that fact and exits immediately (exit status 0 — it is inert, not failed) and the producer API is a no-op that opens no socket. That is what an installation which never answered the question gets, whether or not the service unit is enabled.

The producer programs connect to the socket lazily and tolerate the daemon being absent (events are simply dropped while it is down), so ordering between the daemon and the rest of the pipeline does not matter.

70.1.43.1.4. Enabling the service

pepsi-telemetry-client.service is deliberately not part of pepsi.target, unlike every other Pepsi daemon: the target is the single switch that starts the pipeline, so a unit named there would run on every deployment whatever the operator answered.

Instead pepsi-setup(1) matches the unit to the answer at the end of a successful pepsi-setup run (which is also what the wizard offers to run for you): enable --now when SHARE_TELEMETRY is on, disable --now when it is not, so that turning telemetry off actually stops the daemon rather than relying on it to notice. Nothing is done on a host without systemd, without the unit installed, or without root; setup then logs the one command to run.

It will not enable the unit when telemetry is on but no valid SYSTEM_ID exists — the daemon refuses to start in that state and the unit is Restart=on-failure, so starting it would produce a restart loop rather than telemetry. Setup says so and leaves the unit alone; re-run pepsi-setup run -c <FILE> so an identifier can be generated.

70.1.43.1.5. Submitted data

Two submissions are made (see pepsi-telemetry(1) for the endpoints):

  • POST /telemetry/usage — the per-interval feature counts, attributed to the Pepsi version the daemon was built as.

  • POST /telemetry/features — the enabled-feature snapshot, derived from the cumulative set of features seen since the daemon started (a feature is reported enabled once it has been exercised at least once this run).

No personally identifying information is sent; the only identity is the random 256-bit SYSTEM_ID that pepsi-setup(1) generates.

70.1.43.1.6. Configuration

Global switches live in [pepsi] (shared with the producers):

SHARE_TELEMETRY

Master on/off switch. Opt-in: the default is no. Until it is set to yes the daemon exits at once and the producer API does nothing.

SYSTEM_ID

The anonymous 256-bit identifier (64 hex characters) submitted with every report. Generated automatically by pepsi-setup(1) once SHARE_TELEMETRY is on — a deployment that has not opted in never has one generated for it; required by the daemon.

TELEMETRY_SERVER

Collector host (default telemetry.pepsi.taler.net). The daemon submits to https://<server>/telemetry/{usage,features}. A value containing an explicit scheme:// is honoured verbatim (e.g. http://localhost:18080 for local testing).

The daemon’s own listener/submission knobs live in [pepsi-telemetry-client]:

UNIXPATH

Local listening socket (default /run/pepsi-telemetry/socket). This is the same path the producers connect to, so changing it changes both sides.

UNIXPATH_GROUP, UNIXPATH_MODE

Group and mode of the socket (defaults pepsi-telemetry and 0660), so the pepsi (stage workers) and pepsi-ingress users can connect.

SUBMIT_INTERVAL

Interval between submissions (default 60 s). Use h/m/s units.

MAX_FEATURES

Cap on the number of distinct feature names held in memory (default 4096), bounding memory against a misbehaving local producer.

70.1.43.1.7. Files

/run/pepsi-telemetry/socket

Default UNIX socket the daemon listens on (created by the systemd unit’s RuntimeDirectory).

70.1.43.1.8. See also

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