70.1.42. pepsi-telemetry

anonymous feature-telemetry collector

Manual section:

1

70.1.42.1.1. Name

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

70.1.42.1.2. Synopsis

pepsi-telemetry [GLOBAL-OPTIONS] serve

70.1.42.1.3. Description

pepsi-telemetry is the central collector for Pepsi’s anonymous, opt-in feature telemetry. It is a small HTTP server, deliberately separate from pepsi-httpd(1) and shipped in its own Debian package, intended to run on a single host (by default telemetry.pepsi.taler.net) behind an existing nginx or Apache front server that terminates TLS and rate-limits.

Pepsi installations that opt in ([pepsi] SHARE_TELEMETRY = YES; the option defaults to no, so an installation that never set it submits nothing and is never even assigned a system_id) submit two kinds of report, identified only by a random 256-bit system_id (no personally identifying information). The collector stores them in the pepsi.telemetry table, counting usage per reported Pepsi version, and exposes an aggregate report that never reveals an individual system_id.

The collector connects to the shared pepsi PostgreSQL schema as the pepsi-telemetry role over the local socket. On a host that only serves telemetry the rest of the schema simply stays empty.

70.1.42.1.4. Endpoints

All three endpoints live under /telemetry/. The two submission endpoints are open and unauthenticated — the only deployment identity is the anonymous system_id — with abuse bounded by a request-body cap (MAX_BODY) and the fronting web server’s rate limiting.

POST /telemetry/features

Record a deployment’s enabled-feature snapshot. Body:

{"system_id": "<64 hex>", "version": "0.1.0",
 "features": {"arc": true, "dane": "strict", ...}}

Each feature value must be a JSON scalar: true for a plain on/off feature, or a string/number for a feature carrying a mode. The snapshot is authoritative for (system_id, version): features it lists become enabled (their scalar kept as a detail value), features it omits are marked disabled (their accumulated usage is retained). Replies 204 on success, 400 on a malformed body / bad system_id / non-scalar value, 413 when the body exceeds MAX_BODY.

POST /telemetry/usage

Accumulate feature-usage counts. Body:

{"system_id": "<64 hex>", "version": "0.1.0",
 "usage": {"arc": 42, "srs": 7, ...}}

Each value is a non-negative integer: the number of times the feature was exercised since the previous submission (a delta). Counts are summed server-side and attributed to the reported version. The optional period_start/period_end fields are accepted and ignored. Replies as for /telemetry/features.

GET /telemetry/report

Return the public aggregate report as JSON. One entry per feature with the cross-version rollup — deployments (distinct deployments with the feature enabled) and uses (total exercised count) — plus a per-version by_version breakdown. No system_id ever appears, so the report is safe to serve openly. Example:

{"generated": "2026-06-27T12:00:00Z",
 "features": [
   {"name": "arc", "deployments": 298, "uses": 91234,
    "by_version": [{"version": "0.2.0", "deployments": 210, "uses": 80012}]}
 ]}

The contrib/update-feature-stability.sh script turns this report into the manual’s feature-stability table.

A missing or empty version is recorded as the empty string rather than rejected, so an older client still contributes (bucketed as an unknown version).

70.1.42.1.5. Configuration

The [pepsi-telemetry] section configures the single listener and the request limits; the database connection comes from the shared [pepsi-postgres] section.

SERVE

unix (default in the shipped configuration), tcp or systemd — the same listener vocabulary the other servers use. In unix mode set UNIXPATH (default /run/pepsi-collector/telemetry.sock) and optionally UNIXPATH_GROUP (the front web server’s group, e.g. www-data). tcp mode (BIND_TO/PORT, default port 8080) serves plaintext and is intended for local testing only. There is no TLS in pepsi-telemetry itself; the fronting web server terminates it.

MAX_BODY

Maximum accepted request-body size in bytes (default 65536).

MAX_CONNECTIONS

Cap on simultaneously-served connections (default 128).

DB_POOL_SIZE

Database connection-pool size (default 2).

70.1.42.1.6. Files

/run/pepsi-collector/telemetry.sock

Default UNIX socket the collector listens on. The directory is created by the systemd unit’s RuntimeDirectory=pepsi-collector and belongs to this service alone — not /run/pepsi (the mail pipeline’s) and not /run/pepsi-telemetry (the telemetry client’s), because systemd chowns a runtime directory to the declaring unit’s User= on every start and deletes it on stop, which breaks any directory shared between differing accounts. Collectors upgraded from a version that served on /run/pepsi/telemetry.sock must move UNIXPATH and the front server’s proxy target to match.

/etc/nginx/sites-available/telemetry.pepsi.taler.net, /etc/apache2/sites-available/telemetry.pepsi.taler.net.conf

Reverse-proxy site files shipped (disabled) by the Debian package; enable the one matching your front server.

70.1.42.1.7. See also

pepsi-httpd(1), pepsi-setup(1), pepsi.conf(5).