Nextcloud app that exports per-user statistics on the native OpenMetrics endpoint /metrics (Prometheus-compatible).
Current release: v1.2.0. Requires Nextcloud 33–34 (OpenMetrics API introduced in 33).
| Component | Requirement |
|---|---|
| Nextcloud | 33 – 34 |
| PHP | as required by the Nextcloud version |
| Database | MySQL/MariaDB, PostgreSQL, or SQLite |
| Scraper | Prometheus (or any OpenMetrics client) |
occ commands and app file ownership belong to the PHP-FPM user. Examples below use nginx; on Debian/Ubuntu with Apache this is often www-data — substitute yours.
Download the app tarball from the latest release and unpack it into the apps directory (apps or custom_apps):
cd /var/www/nextcloud/custom_apps
sudo tar -xzf ~/usermetrics-1.2.0.tar.gz # filename as in the release
sudo chown -R nginx:nginx usermetrics
sudo -u nginx php /var/www/nextcloud/occ app:enable usermetricsConfirm:
sudo -u nginx php /var/www/nextcloud/occ app:list | grep usermetrics
curl -s http://127.0.0.1/metrics | grep usermetricssudo -u nginx git clone https://github.com/Yt4aZaveta/usermetrics.git /var/www/nextcloud/custom_apps/usermetrics
sudo -u nginx php /var/www/nextcloud/occ app:enable usermetricsMetrics appear on the instance /metrics endpoint together with core Nextcloud metrics:
curl -s http://127.0.0.1/metrics | grep usermetricsBy default the endpoint is localhost-only. Allow Prometheus scrapers in config/config.php:
'openmetrics_allowed_clients' => [
'127.0.0.1/32',
'10.0.0.0/8',
'192.168.0.0/16',
],If Prometheus scrapes by IP (common in Kubernetes) and gets 400 Trusted domain error, also add that host to trusted_domains — Nextcloud still checks the Host header on /metrics (upstream #58614). Prefer scraping via the real domain name when possible.
scrape_configs:
- job_name: nextcloud
metrics_path: /metrics
scheme: https
static_configs:
- targets: ['cloud.example.com']Metric names start with nextcloud_usermetrics_ (core exporter adds the nextcloud_ prefix).
Import grafana/dashboard.json:
- Grafana → Dashboards → New → Import
- Upload the file (or paste its contents)
- Pick your Prometheus datasource
The dashboard has:
- Server overview — users, storage, shares, top consumers, inactivity, quota usage
- User detail — switch the User dropdown for per-user stats
All names below are as registered by the app; Prometheus sees them with a nextcloud_ prefix.
| Metric | Labels | Description |
|---|---|---|
usermetrics_user_storage_used_bytes |
user |
Used space in home files/ (excludes unscanned size=-1 nodes) |
usermetrics_user_storage_unscanned_files |
user |
Home files/ nodes with unknown size (common on S3); only emitted when > 0 |
usermetrics_user_quota_bytes |
user |
Quota (-3 = unlimited, -2 = unknown) |
usermetrics_user_free_bytes |
user |
Remaining quota |
usermetrics_user_quota_usage_ratio |
user |
Usage ratio 0..1 |
usermetrics_user_last_login_timestamp_seconds |
user |
Last login (Unix; 0 = never) |
usermetrics_user_first_login_timestamp_seconds |
user |
First login |
usermetrics_user_enabled |
user |
Account enabled (1/0) |
usermetrics_user_has_email |
user |
Email configured |
usermetrics_user_backend_info |
user, backend |
Auth backend (Database / LDAP / …) |
usermetrics_user_shares |
user, type |
Owned shares by type |
usermetrics_user_shares_received |
user |
Incoming user shares |
usermetrics_user_files |
user |
File count |
usermetrics_user_folders |
user |
Folder count |
usermetrics_user_groups |
user |
Group memberships |
usermetrics_user_auth_tokens |
user |
Sessions / app passwords |
usermetrics_user_two_factor_enabled |
user |
At least one 2FA provider |
usermetrics_user_external_mounts |
user |
Non-home mounts |
usermetrics_user_trashbin_bytes |
user |
Trashbin size |
usermetrics_users |
state |
Totals: enabled / disabled / all |
usermetrics_users_never_logged_in |
— | Users who never logged in |
usermetrics_collector_duration_seconds |
— | Snapshot collection time |
usermetrics_collector_errors |
— | Failed enrich/collect stages (0 = healthy; stale last-good may still be served) |
Share type values: user, group, link, email, remote, circle, room, deck, …
# Users inactive for 30+ days
(time() - nextcloud_usermetrics_user_last_login_timestamp_seconds) > 30 * 24 * 3600
# Quota usage above 90%
nextcloud_usermetrics_user_quota_usage_ratio > 0.9
# Top storage consumers
topk(10, nextcloud_usermetrics_user_storage_used_bytes)
App config keys (occ config:app:set usermetrics …):
| Key | Default | Description |
|---|---|---|
cache_ttl |
300 |
Snapshot cache TTL in seconds (min 30) |
collect_file_counts |
true |
Count files/folders (can be expensive on huge instances) |
user_source |
accounts |
accounts: list users from local DB tables only (safe with LDAP). backends: enumerate user backends (may query LDAP on every snapshot) |
log_file |
{datadirectory}/usermetrics.log |
Absolute path to the app log file |
log_level |
info |
Minimum level: debug, info, warning, critical |
sudo -u nginx php /var/www/nextcloud/occ config:app:set usermetrics cache_ttl --value=600
sudo -u nginx php /var/www/nextcloud/occ config:app:set usermetrics collect_file_counts --value=falseTo skip specific exporters entirely (core Nextcloud setting):
'openmetrics_skipped_classes' => [
'OCA\\UserMetrics\\OpenMetrics\\UserFiles',
'OCA\\UserMetrics\\OpenMetrics\\UserFolders',
],By default the app writes to {datadirectory}/usermetrics.log (usually /var/www/nextcloud/data/usermetrics.log). That directory must be writable by the PHP user. Levels: debug < info < warning < critical. Warnings and criticals are also mirrored to the main Nextcloud log.
# show current path and level
sudo -u nginx php /var/www/nextcloud/occ usermetrics:logging
# change level
sudo -u nginx php /var/www/nextcloud/occ usermetrics:logging --level=debug
# change path
sudo -u nginx php /var/www/nextcloud/occ usermetrics:logging --file=/var/log/nextcloud/usermetrics.log
# reset path to default
sudo -u nginx php /var/www/nextcloud/occ usermetrics:logging --file=Logrotate example (uses copytruncate, safe while Nextcloud keeps the file open). In logrotate/usermetrics set create / su to your PHP user (nginx nginx or www-data www-data):
sudo cp /var/www/nextcloud/custom_apps/usermetrics/logrotate/usermetrics /etc/logrotate.d/usermetrics
# edit the path and user/group inside if needed
sudo logrotate -d /etc/logrotate.d/usermetricsWith the default user_source = accounts, scrapes never contact the LDAP server: the user list, display names and emails are read from the local oc_accounts table, and the backend (Database / LDAP) is detected from the oc_ldap_user_mapping table. All other metrics (logins, shares, storage, groups, tokens, 2FA) come from local Nextcloud tables regardless of the auth backend.
Notes:
- LDAP users appear in metrics after their first login or an account sync (
occ user:sync-account-data). - Storage and file counts are 0 until a user logs in for the first time (their home is not created yet).
- Users removed from LDAP keep being exported until you clean remnants (
occ ldap:show-remnants). - Metrics key users by Nextcloud
uid(often a UUID for LDAP). Display names are read for internal profile enrichment (has_email, etc.) but are not exported as labels — they churn and inflate cardinality.
- Exporters are registered in
appinfo/info.xmlvia<openmetrics>. - On scrape,
UserMetricsCollectorruns batched SQL (preferences, mounts/filecache, shares, groups, tokens, 2FA) once and caches the snapshot. - On enrich/collect failure, a last-known-good snapshot is served and
usermetrics_collector_errorsis non-zero. - Each
IMetricFamilyreads from that snapshot — no per-user filesystem mounts.
AGPL-3.0-or-later. See LICENSE.