66. pepsi-telemetry

The central, anonymous, opt-in feature-telemetry collector.

66.1. Role

pepsi-telemetry collects anonymous usage telemetry from Pepsi installations that opt in. It is a small HTTP server, deliberately separate from pepsi-httpd and shipped in its own Debian package, intended to run on one host — by default telemetry.pepsi.taler.net — behind an existing nginx or Apache front server. Run it with pepsi-telemetry serve.

A reporting Pepsi node is identified only by a random 256-bit system_id (no personally identifying information). The collector connects to the shared pepsi PostgreSQL schema as the pepsi-telemetry role and stores everything in the pepsi.telemetry table, counting usage per reported Pepsi version.

66.2. Features

  • Two open submission endpoints. POST /telemetry/features records which features a deployment has enabled (a snapshot: listed features become enabled, omitted ones disabled, with usage history retained), and POST /telemetry/usage accumulates per-feature usage counts (deltas, summed server-side). Both are unauthenticated — the only identity is the anonymous system_id — and bounded by MAX_BODY plus the front server’s rate limits.

  • Per-version counting. The version reported in each submission is part of the table key, so usage events are attributed to the Pepsi release that produced them and an upgrade accrues separate rows.

  • Public aggregate report. GET /telemetry/report returns per-feature rollups (distinct enabled deployments and total uses) with a per-version breakdown, as JSON. It never exposes an individual system_id, so it is safe to serve openly.

  • No TLS of its own. It serves plain HTTP on a UNIX socket (SERVE = unix, default /run/pepsi-collector/telemetry.sock) for a reverse proxy, or plaintext TCP for local testing. TLS is terminated by the fronting nginx/Apache.

66.3. Feature-stability table

The companion script contrib/update-feature-stability.sh fetches GET /telemetry/report and regenerates Feature stability, assigning each feature a tier from both how widely it is deployed and how heavily it is exercised (a feature must clear both thresholds for a tier):

  • stable — deployments ≥ 100 and total uses ≥ 100000

  • used — deployments ≥ 10 and total uses ≥ 1000

  • experimental — otherwise

The thresholds, source URL and output path are overridable via environment variables (see the script header).

66.4. Configuration

[pepsi-telemetry]: SERVE (unix/tcp/systemd) with the matching transport options (UNIXPATH/UNIXPATH_GROUP, or BIND_TO/PORT), MAX_BODY (default 65536), MAX_CONNECTIONS (default 128) and DB_POOL_SIZE (default 2). The database connection comes from the shared [pepsi-postgres] section. See Configuration and pepsi-telemetry(1).

66.5. Deployment

The Debian pepsi-telemetry package ships a systemd unit (serving on /run/pepsi-collector/telemetry.sock) and reverse-proxy site files for both nginx and Apache under sites-available/ defaulting to telemetry.pepsi.taler.net — enable the one matching your front server and provision a certificate for the host. Install the schema with pepsi-setup as on any Pepsi node.

The collector’s runtime directory is its own: it is created by the unit’s RuntimeDirectory=pepsi-collector and is deliberately neither /run/pepsi (the mail pipeline’s, shared by pepsi-ingress, pepsi-httpd and the setup-apply doorbell) nor /run/pepsi-telemetry (the telemetry client’s). systemd gives a runtime directory to the declaring unit’s own User= and removes it when that unit stops, so a directory shared between services running as different accounts ends up owned by whichever started last — and one service stopping deletes the sockets the others still have bound. Earlier versions of this unit shared /run/pepsi; if you are upgrading a collector that runs alongside a mail pipeline, move [pepsi-telemetry] UNIXPATH to the new directory and update your front server’s proxy_pass/ProxyPass to match.

66.6. See also

pepsi-telemetry-client (the per-host client that submits to this collector), pepsi-httpd, pepsi-setup, Feature stability, pepsi.conf(5).