Usage Statistics Server is a Nextcloud app that gives other apps a shared place to receive and aggregate opt-in usage statistics.
Instead of each app building its own collection backend, schema registry, retention policy, storage model, and administration API, it can send versioned reports to this server and reuse the same infrastructure.
LibreSign is the first intended consumer, but the protocol is generic and can be used by other Nextcloud apps.
An app may need answers to questions such as:
- Which application versions are still being used?
- Which optional features are enabled?
- How does adoption change between releases?
- How many participating installations reported during a period?
Usage Statistics Server provides the backend for these questions without requiring user-level event tracking or application-specific database tables.
Reports are opt-in and self-reported by participating installations. The server validates them against an application schema, stores historical reporting periods, and exposes aggregated results to Nextcloud administrators.
Each participating app:
- defines the metrics it can report in a versioned schema;
- shows users exactly which data can be submitted;
- sends periodic reports with a persistent installation identifier;
- lets this server validate, store, retain, and aggregate the reports.
The ingestion protocol is application-agnostic. Metric values are typed and schema-controlled, and retries for the same reporting period are idempotent.
The server does not treat submitted data as an audited census. Reports come from software running on infrastructure controlled by the sender, so aggregated results should be described as statistics reported by participating installations.
Server administrators can configure data retention from the Nextcloud administration settings or with the usage-statistics-server:retention:* OCC commands.
Start here if you want to integrate another Nextcloud app:
- Protocol v1: report format, validation rules, and ingestion behavior.
- Application schemas: how applications define metrics and evolve schemas.
- Administrative API: endpoints for querying aggregated statistics.
- Retention: historical data retention and cleanup behavior.
The OpenAPI specifications are generated from the Nextcloud controller contracts and are kept in the repository for API consumers and generated types.