Skip to content

About

Nextcloud app: per-user OpenMetrics / Prometheus metrics (storage, shares, logins, …)

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

17 Commits

Folders and files

Repository files navigation

User Metrics for Nextcloud

English | Русский

Version License

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).

Requirements

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.

Installation

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 usermetrics

Confirm:

sudo -u nginx php /var/www/nextcloud/occ app:list | grep usermetrics
curl -s http://127.0.0.1/metrics | grep usermetrics

Install from git

sudo -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 usermetrics

Endpoint

Metrics appear on the instance /metrics endpoint together with core Nextcloud metrics:

curl -s http://127.0.0.1/metrics | grep usermetrics

By 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.

Prometheus scrape config

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).

Grafana dashboard

Import grafana/dashboard.json:

  1. Grafana → Dashboards → New → Import
  2. Upload the file (or paste its contents)
  3. 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

Exported metrics

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, …

Example PromQL

# 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)

Configuration

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=false

To skip specific exporters entirely (core Nextcloud setting):

'openmetrics_skipped_classes' => [
  'OCA\\UserMetrics\\OpenMetrics\\UserFiles',
  'OCA\\UserMetrics\\OpenMetrics\\UserFolders',
],

Logging

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/usermetrics

LDAP and other external user backends

With 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.

How it works

  1. Exporters are registered in appinfo/info.xml via <openmetrics>.
  2. On scrape, UserMetricsCollector runs batched SQL (preferences, mounts/filecache, shares, groups, tokens, 2FA) once and caches the snapshot.
  3. On enrich/collect failure, a last-known-good snapshot is served and usermetrics_collector_errors is non-zero.
  4. Each IMetricFamily reads from that snapshot — no per-user filesystem mounts.

License

AGPL-3.0-or-later. See LICENSE.

About

Nextcloud app: per-user OpenMetrics / Prometheus metrics (storage, shares, logins, …)

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages