..
  This file is part of PEPSI.
  Copyright (C) 2026 Pepsi contributors

  PEPSI is free software; you can redistribute it and/or modify it under the
  terms of the GNU Affero General Public License as published by the Free
  Software Foundation; either version 3, or (at your option) any later version.

===============
pepsi-telemetry
===============

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

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.

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.

Feature-stability table
=======================

The companion script ``contrib/update-feature-stability.sh`` fetches
``GET /telemetry/report`` and regenerates :doc:`../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).

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 :doc:`../configuration` and
:manpage:`pepsi-telemetry(1)`.

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.

See also
========

:doc:`pepsi-telemetry-client` (the per-host client that submits to this
collector), :doc:`pepsi-httpd`, :doc:`pepsi-setup`, :doc:`../feature-stability`,
:manpage:`pepsi.conf(5)`.