Superviser Nextcloud avec Prometheus : métriques et alertes en 2026

Une page de connexion qui répond ne prouve pas qu’une instance Nextcloud fonctionne correctement. En 2026, un monitoring Nextcloud avec Prometheus peut suivre l’état de maintenance, la version, les applications, les sessions, les fichiers et le temps nécessaire pour produire les métriques. Il faut toutefois compléter ces données par la santé du serveur et un test HTTP extérieur.

Depuis Nextcloud 33, le serveur fournit un endpoint OpenMetrics natif sur /metrics. Ce guide explique comment l’autoriser sans l’exposer à tout Internet, le collecter avec Prometheus, construire un tableau de bord lisible et créer des alertes qui correspondent à une action réelle.

Que mesure réellement l’endpoint OpenMetrics de Nextcloud ?

Nextcloud produit lui-même des métriques au format OpenMetrics depuis la version 33. Prometheus peut donc interroger directement https://cloud.example.fr/metrics, sans compte administrateur ni application tierce sur une version compatible. Le guide complet de Nextcloud reste utile pour replacer cette supervision dans l’ensemble des fonctions de la plateforme.

Le code de la branche stable 35 déclare notamment les familles suivantes :

• nextcloud_instance_info indique la version complète, la version majeure et l’état d’installation. Utilisez-la pour vérifier la version observée après une mise à jour.
• nextcloud_maintenance expose l’activation du mode maintenance. Elle permet de détecter un verrouillage qui dure trop longtemps.
• nextcloud_app_enabled donne l’état et la version des applications installées. Elle aide à contrôler une application attendue après un changement.
• nextcloud_active_users compte les utilisateurs actifs sur 5 minutes, 15 minutes, 1 heure et 24 heures, sans exposer leur identité.
• nextcloud_active_sessions compte les sessions actives sur les mêmes périodes afin de comparer l’activité et le nombre de sessions.
• nextcloud_files répartit le nombre de fichiers par type MIME pour suivre la composition du stockage.
• nextcloud_running_jobs dénombre les tâches actuellement réservées par classe et donc en cours d’exécution.
• nextcloud_exporter_run_seconds mesure la durée de génération de la réponse afin de repérer un endpoint qui ralentit.

Les applications activées peuvent ajouter leurs propres familles. Dans le code stable 35, Files Sharing expose par exemple les partages par type, tandis que Comments publie le nombre de commentaires.

Ces métriques ne couvrent pas la charge CPU, la mémoire, l’espace disque, le débit réseau ou la disponibilité vue par un utilisateur extérieur. Une architecture Nextcloud à haute disponibilité demande donc plusieurs niveaux d’observation, pas un seul graphique applicatif.

Comment activer et sécuriser /metrics dans Nextcloud ?

L’endpoint existe nativement à partir de Nextcloud 33, mais il n’est pas ouvert à toutes les adresses. La documentation officielle prévoit le paramètre openmetrics_allowed_clients dans config.php. Par défaut, seules les adresses de boucle locale sont autorisées. Une requête provenant d’une adresse non admise reçoit un code HTTP 403.

Ajoutez seulement l’adresse du serveur Prometheus ou un réseau de supervision strictement délimité :

'openmetrics_allowed_clients' => [
    '192.0.2.10/32',
    '2001:db8::10/128',
],

Les adresses ci-dessus appartiennent aux plages réservées aux exemples. Remplacez-les par les adresses réellement utilisées dans votre réseau. Si Prometheus tourne sur le même hôte que Nextcloud, l’autorisation locale par défaut peut suffire.

Avec un reverse proxy, vérifiez l’adresse que Nextcloud considère comme celle du client. Une mauvaise configuration des proxys de confiance peut faire apparaître l’adresse du frontal au lieu de celle de Prometheus. Le guide du reverse proxy Nextcloud détaille les en-têtes et les paramètres à contrôler.

Testez ensuite depuis le serveur de collecte :

curl -fsS https://cloud.example.fr/metrics | sed -n '1,20p'

Une réponse valide commence par des lignes # TYPE, # UNIT ou # HELP, puis des métriques préfixées par nextcloud_. Si la collecte devient coûteuse, openmetrics_skipped_classes permet d’exclure un exporteur précis. Ne désactivez pas une famille avant d’avoir mesuré sa durée et vérifié qu’aucune alerte n’en dépend.

Comment configurer Prometheus pour collecter Nextcloud ?

Ajoutez une tâche de collecte dédiée dans prometheus.yml. Une fréquence de 30 secondes convient à un premier déploiement, mais elle ne constitue pas une valeur universelle. Une petite instance peu sollicitée peut être interrogée moins souvent. Prometheus impose aussi un délai de collecte inférieur ou égal à l’intervalle choisi.

scrape_configs:
  - job_name: nextcloud
    scheme: https
    metrics_path: /metrics
    scrape_interval: 30s
    scrape_timeout: 10s
    static_configs:
      - targets:
          - cloud.example.fr
        labels:
          environment: production

Validez le fichier avant de recharger Prometheus :

promtool check config /etc/prometheus/prometheus.yml

Dans l’interface Prometheus, la cible nextcloud doit apparaître avec l’état UP. La requête up{job="nextcloud"} renvoie alors 1. Un état DOWN peut venir du DNS, du certificat TLS, du réseau, d’un code 403 ou d’un délai dépassé. Lisez le message de la cible avant de modifier Nextcloud.

Sur Nextcloud 32 ou une version antérieure, /metrics n’est pas disponible nativement. Un exporteur tiers peut interroger ServerInfo, mais il ajoute une dépendance et des identifiants à gérer. Lorsque c’est possible, planifiez d’abord une mise à niveau prise en charge, puis utilisez l’endpoint natif documenté.

Quel tableau de bord Grafana construire pour Nextcloud ?

Un tableau de bord utile commence par les questions d’exploitation, pas par le nombre de graphiques. Organisez-le en quatre lignes afin qu’une anomalie mène rapidement à une hypothèse.

La première ligne affiche la disponibilité de la cible, nextcloud_maintenance et nextcloud_exporter_run_seconds. Elle répond à trois questions : Prometheus collecte-t-il encore la cible, Nextcloud est-il en maintenance, et la génération des métriques reste-t-elle proche de son niveau habituel ?

La deuxième ligne suit nextcloud_active_users et nextcloud_active_sessions avec le label time. Comparez par exemple les fenêtres « Last 15 minutes » et « Last day ». Ces séries décrivent une activité récente, pas le nombre total de collaborateurs ni une mesure de performance.

La troisième ligne regroupe nextcloud_files, nextcloud_shares si Files Sharing l’expose, et les applications attendues avec nextcloud_app_enabled. La métrique des fichiers est mise en cache pendant 30 minutes dans le code stable 35. Elle convient à une tendance de capacité, pas à une alerte à la minute.

La quatrième ligne ajoute les signaux externes. node_exporter fournit les métriques du noyau et du système, comme le CPU, la mémoire et les systèmes de fichiers. blackbox_exporter vérifie une URL en HTTP ou HTTPS et expose notamment probe_success. Cette séparation évite de conclure qu’un serveur sain garantit une application accessible.

Le nombre nextcloud_running_jobs correspond aux tâches dont reserved_at est supérieur à zéro. Il ne représente pas toute la file des travaux en attente. Pour régler l’exécution des tâches, suivez plutôt le guide des tâches d’arrière-plan Nextcloud avec cron. Les métriques spécifiques de Nextcloud Notify Push complètent le tableau lorsque ce service est installé.

Quelles alertes Prometheus créer pour Nextcloud ?

Une alerte doit décrire un état durable, inclure un contexte et renvoyer vers une action. Le mot-clé for demande à Prometheus d’attendre avant de considérer la règle active. Il réduit les notifications liées à une coupure très brève ou à une maintenance planifiée.

groups:
  - name: nextcloud
    rules:
      - alert: NextcloudMetricsUnavailable
        expr: up{job="nextcloud"} == 0
        for: 5m
        labels:
          severity: warning
        annotations:
          summary: "Prometheus ne collecte plus les métriques Nextcloud"
          description: "Vérifier le réseau, TLS, le code HTTP et openmetrics_allowed_clients."

      - alert: NextcloudMaintenanceProlongee
        expr: nextcloud_maintenance == 1
        for: 20m
        labels:
          severity: warning
        annotations:
          summary: "Nextcloud reste en mode maintenance"
          description: "Confirmer qu'une mise à jour est en cours ou désactiver le mode après contrôle."

      - alert: NextcloudExporterLent
        expr: nextcloud_exporter_run_seconds > 5
        for: 10m
        labels:
          severity: warning
        annotations:
          summary: "La production des métriques Nextcloud est lente"
          description: "Comparer au niveau habituel et identifier l'exporteur coûteux."

Les durées de 5, 20 et 10 minutes ainsi que le seuil de 5 secondes sont des exemples de départ. Mesurez votre niveau normal, votre délai d’intervention et la durée de vos mises à jour avant de les conserver. Une maintenance planifiée doit être inhibée ou rendue silencieuse dans Alertmanager.

Ajoutez séparément une alerte sur probe_success == 0 pour la disponibilité extérieure et des règles sur l’espace disque du système. Sinon, un endpoint /metrics joignable peut masquer une page web en panne, tandis qu’un test HTTP réussi peut masquer un disque presque plein.

Comment valider le monitoring avant la mise en production ?

Commencez par une recette courte et reproductible. Vérifiez d’abord que /metrics répond en 200 depuis Prometheus et en 403 depuis une source non autorisée. Contrôlez ensuite la cible dans Prometheus, puis les métriques brutes avant de construire les graphiques.

Observez au moins quelques heures de fonctionnement normal. Notez la durée habituelle de nextcloud_exporter_run_seconds, les variations d’activité et la fréquence de collecte. Déclenchez chaque règle dans un environnement de test ou avec une expression temporaire, puis confirmez que la notification contient le nom de l’instance, l’état observé et la première action attendue.

Enfin, documentez un mini runbook : où lire les journaux, comment vérifier le mode maintenance, qui reçoit l’alerte et quand l’escalader. Un tableau de bord sans procédure aide au diagnostic, mais ne garantit pas qu’une notification sera traitée. La supervision doit aussi être revue après une mise à jour majeure, l’ajout d’une application ou un changement de proxy.

Conclusion

Le monitoring Nextcloud avec Prometheus repose sur trois niveaux complémentaires : l’endpoint OpenMetrics natif pour l’état applicatif, les exporteurs système pour les ressources et une sonde extérieure pour l’accès réel. Restreignez /metrics par adresse, mesurez avant de fixer les seuils et traitez nextcloud_running_jobs comme des tâches en cours, pas comme une file complète. Vous obtenez ainsi des alertes plus rares, mais plus faciles à comprendre et à résoudre.

Découvrir les offres NextcloudEspace géré, hébergé en France

Sources officielles

• Nextcloud Developer Manual : Open Metrics exporter
• Nextcloud Administration Manual : paramètres OpenMetrics
• Code source Nextcloud stable35 : contrôleur OpenMetrics
• Code source Nextcloud stable35 : exporteurs OpenMetrics
• Prometheus : configuration des collectes
• Prometheus : règles d’alerte
• Prometheus Alertmanager
• Prometheus node_exporter
• Prometheus blackbox_exporter
• Grafana : source de données Prometheus