91. pepsi-telemetry¶
The central, anonymous, opt-in feature-telemetry collector.
91.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.
91.2. Features¶
Two open submission endpoints.
POST /telemetry/featuresrecords which features a deployment has enabled (a snapshot: listed features become enabled, omitted ones disabled, with usage history retained), andPOST /telemetry/usageaccumulates per-feature usage counts (deltas, summed server-side). Both are unauthenticated and bounded byMAX_BODYplus the front server’s rate limits; the only identity is the anonymoussystem_id.Per-version counting. The
versionreported 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/reportreturns per-feature rollups (distinct enabled deployments and total uses) with a per-version breakdown, as JSON. It never exposes an individualsystem_id, so it is safe to serve openly.No TLS of its own. It serves plain HTTP on a UNIX socket (
/run/pepsi-collector/pepsi-telemetry.sock, socket-activated viaSERVE = systemdas shipped, or bound by the daemon itself withSERVE = unix) for a reverse proxy, or plaintext TCP for local testing. TLS is terminated by the fronting nginx/Apache.
91.3. Limits and what the figures are worth¶
The collector is the one Pepsi component meant to face the internet unauthenticated,
so every submission is bounded: the body by MAX_BODY and a 30-second read
deadline, at most 512 feature names per body, each 1–64 characters of
[A-Za-z0-9._-], a version of at most 32 characters, and usage deltas of
at most 2^40 with each running total clamped at 10^12. Request rates are left
to the front server: the shipped nginx site has limit_req, while the Apache
site’s mod_ratelimit only throttles response bandwidth. Its database role
reaches the telemetry table and nothing else (An attacker who has the database).
The system_id is self-asserted: the collector neither issues nor verifies
it. The report therefore counts identifiers submitted, not installations.
Anyone can mint identifiers and inflate a feature’s figures, and anyone who learns a
deployment’s identifier can overwrite that deployment’s snapshot. Read the report
and the stability tiers derived from it as adoption reported in good faith, not as
evidence.
91.4. 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).
91.5. Configuration¶
[pepsi-telemetry]: SERVE (unix/tcp/systemd) with the matching
transport options (UNIXPATH/UNIXPATH_MODE/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).
91.6. Deployment¶
The Debian pepsi-telemetry package ships a systemd service and socket unit
(serving on /run/pepsi-collector/pepsi-telemetry.sock), its configuration
file /etc/pepsi-telemetry/pepsi-telemetry.conf, and reverse-proxy site files
for both nginx and Apache, installed under their canonical site names:
/etc/nginx/sites-available/telemetry.pepsi.taler.net
/etc/apache2/sites-available/telemetry.pepsi.taler.net.conf
They arrive complete and disabled, already pointing at the socket that the shipped units bind, so enabling one takes only a symlink. There is no proxy path to fill in, and so none to get wrong:
# nginx
$ ln -s ../sites-available/telemetry.pepsi.taler.net /etc/nginx/sites-enabled/
$ systemctl reload nginx
# Apache (a2ensite makes the same symlink)
$ a2enmod proxy proxy_http ssl ratelimit headers
$ a2ensite telemetry.pepsi.taler.net
$ systemctl reload apache2
Then provision a certificate for the host, and install the schema from the
collector’s own file, which needs nothing but its [pepsi-postgres]
section:
$ pepsi-setup -c /etc/pepsi-telemetry/pepsi-telemetry.conf schema
Package upgrades upgrade the schema the same way, and the collector refuses to
start against a schema from another release until they have (see
Upgrading). Both site files are conffiles, so local edits survive
package upgrades, such as a different server_name for a private collector.
If you change the socket path, you must change it in four places: the
.socket unit’s ListenStream=, the service’s RuntimeDirectory=, and
the two site files (plus UNIXPATH in the collector’s own configuration, if
you switch it to SERVE = unix). make check-telemetry-socket, which
make check runs, compares them and fails the build if any two disagree.
The check is worth having, because a mismatch is invisible in testing and shows
up in production only as a 502 from the front server.
The collector’s runtime directory belongs to it alone, and that is the point.
It is not /run/pepsi (the mail pipeline’s, shared by pepsi-ingress,
pepsi-httpd and the setup-apply doorbell), and it is not
/run/pepsi-telemetry (the telemetry client’s, whose socket
/run/pepsi-telemetry/socket is owned by pepsi). systemd gives a runtime
directory to the User= of the unit that declares it, chowning it and its
contents on every start, and without RuntimeDirectoryPreserve= it removes
the directory 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 (No unit may claim it as a RuntimeDirectory).
Distinct file names in a shared directory are not protection. Were the
collector’s socket in the client’s directory, a host running both would work
until the client next started; the collector’s socket would then be chowned to
pepsi:pepsi, lose the www-data group the front server connects through,
and every request would become a 502, while the collector stays active,
healthy and silent, having never seen a connection. Running the collector on a host of
its own is still the intended deployment, but it is not what keeps the two
apart.
91.7. See also¶
pepsi-telemetry-client (the per-host client that submits to this collector), pepsi-httpd, pepsi-setup, Feature stability, pepsi.conf(5).