Comment résoudre le problème de forte utilisation du processeur dans Collabora Online (via loolwsd/coolwsd)

Lorsque Collabora Online utilise soudainement la majeure partie du processeur d'un serveur, la première chose à faire est de ne pas le redémarrer à répétition ni de limiter immédiatement l'utilisation du processeur à un niveau trop bas. Il convient d'abord de déterminer si la charge provient d'une activité normale sur les documents, d'une session problématique, d'un nombre excessif de tâches parallèles, d'une session inactive non nettoyée ou d'une régression spécifique à une version. Le nom du processus peut varier coolwsdselon les versions, qu'elles soient récentes ou loolwsdanciennes.

Scénario illustratif : imaginez un serveur à 8 vCPU exécutant Collabora Online derrière Nextcloud. Seules quelques personnes semblent modifier des documents, mais le conteneur Collabora affiche une utilisation du processeur entre 250 % et 350 % pendant plusieurs minutes. Il s’agit d’un exemple hypothétique utilisé tout au long de ce guide, et non d’un test de performance mesuré ou d’un rapport issu d’un déploiement réel.

En octobre 2026, la branche stable actuelle de Collabora était la 26.04, et les notes de version officielles indiquent que Collabora Online 26.04.3.3 a été publié le 14 septembre 2026. Les modèles de configuration actuels utilisent cette coolwsdappellation. Les outils de migration de Collabora documentent encore l'ancienne /etc/loolwsd/loolwsd.xmlappellation pour les installations de la version 6.4 ou antérieure, ce qui explique pourquoi les administrateurs peuvent encore rencontrer les deux appellations.

1. Vérifiez quel processus consomme réellement du processeur.

Commencez par examiner le système d'exploitation ou le conteneur. Une valeur élevée coolwsdn'indique pas automatiquement que le démon de coordination effectue lui-même toutes les tâches de traitement de documents les plus gourmandes en ressources. Collabora exécute également des processus kit/forkit pour les sessions de documents ; il est donc important d'analyser l'arborescence des processus et l'utilisation du processeur par processus avant de modifier la configuration.

ps -eo pid,ppid,pcpu,pmem,etime,cmd --sort=-pcpu | head -n 25
top -H -p $(pgrep -d, -f 'coolwsd|loolwsd|coolkit|loolkit|forkit')

Pour Docker, vérifiez également le conteneur dans son ensemble :

docker stats --no-stream

Dans cet exemple, supposons que le conteneur utilise près de 300 % du processeur et qu'un processus du kit soit constamment en tête de liste. Cela indique une session de document active spécifique plutôt qu'une surcharge générale du serveur.

2. Consultez les indicateurs de performance de Collabora plutôt que de vous fier uniquement aux données générales.

Collabora Online expose des métriques compatibles avec Prometheus à l'adresse `@Prometheus.getMethods()` /cool/getMetrics. Le manuel du SDK indique que ce point de terminaison peut fournir des informations sur l'utilisation du processeur et de la mémoire, les processus en cours d'exécution, les vues et d'autres données d'utilisation du serveur. L'authentification est identique à celle de la console d'administration, sauf si l'accès aux métriques est explicitement configuré pour un accès non authentifié.

Ne rendez pas l'URL de métriques publiquement, même pour simplifier le dépannage. La configuration officielle de Helm inclut des exemples d' /cool/getMetricsURL de blocage et d'administration au niveau d'un point d'entrée. Utilisez un chemin interne authentifié chaque fois que cela est possible.

Recherchez une corrélation entre l'utilisation du processeur et les documents ou vues ouverts. Si l'utilisation du processeur varie en fonction de l'activité d'édition, il peut s'agir d'un problème de capacité ou de concurrence. Si l'utilisation du processeur reste élevée sans activité interactive correspondante, examinez les sessions inactives, un document problématique, des tâches en arrière-plan répétées ou un problème logiciel.

3. Consultez les journaux au moment précis où l'utilisation du processeur augmente.

Pour une installation de paquet gérée par systemd :

journalctl -u coolwsd --since "15 minutes ago" --no-pager
journalctl -u coolwsd -f

Pour Docker :

docker logs collabora --since 15m
docker logs -f collabora

Si votre service ou conteneur porte un nom différent, remplacez-le. Recherchez les chargements de documents répétés, les créations de kits répétées, les échecs d'enregistrement, les plantages, les boucles de reconnexion ou l'apparition répétée de la même clé de document. Une utilisation du processeur plus élevée pendant une courte période lors de l'ouverture, du recalcul, du rendu, de la conversion ou de l'exportation d'un document peut être normale. En revanche, une utilisation soutenue du processeur sans progression utile ou la répétition d'une même erreur constituent un signe d'alerte plus important.

4. Reproduisez le pic avec un document à la fois.

Revenez au serveur hypothétique. Si un processus du kit est très gourmand en ressources, fermez ou isolez le document suspect et observez si l'utilisation du processeur diminue. Ouvrez ensuite ce même fichier pendant une période d'inactivité, tout en surveillant la liste des processus et les indicateurs. Répétez l'opération avec un document de test simple.

Cette comparaison est plus utile que de redémarrer immédiatement l'ensemble du service :

• Si un seul fichier déclenche systématiquement le pic, le contenu du fichier, les formules, les objets incorporés, la charge de travail de rendu ou un bogue spécifique au document sont des suspects plus probables.
• Si chaque fichier provoque une saturation similaire dès que plusieurs utilisateurs sont actifs, examinez la capacité du serveur et la concurrence.
• Si l'utilisation du processeur reste élevée après l'arrêt de toute activité utilisateur, concentrez-vous sur le nettoyage, les kits obsolètes, les tâches en arrière-plan répétitives ou une régression.
• Si le problème est apparu immédiatement après une mise à jour, notez les anciennes et nouvelles versions avant de modifier d'autres variables.

5. Réduire la concurrence par document lorsqu'un document peut monopoliser les cœurs.

Le modèle de configuration Collabora actuel définit per_document.max_concurrencyle nombre maximal de threads utilisés lors du traitement d'un document. La valeur par défaut est de 4. Sur un système peu puissant, ou lorsqu'un seul document complexe monopolise les ressources du processeur, réduire cette valeur permet d'obtenir une utilisation plus prévisible du processeur.

Par exemple, vous pourriez tester la valeur 2 :

<per_document>
    <max_concurrency>2</max_concurrency>
</per_document>

Ne copiez pas aveuglément la valeur 2. Si les utilisateurs manipulent régulièrement de grands tableurs ou des présentations et que le serveur dispose de suffisamment de cœurs, une valeur inférieure risque de ralentir les opérations. Modifiez un paramètre, reproduisez la même charge de travail et comparez l'utilisation du processeur, la réactivité et le temps d'exécution.

6. Vérifiez les paramètres de nettoyage et de session inactive avant de les rendre agressifs.

Le modèle actuel coolwsd.xmlintègre une logique de nettoyage pour les documents inactifs gourmands en ressources. À l'heure actuelle, le modèle affiche un intervalle de vérification de nettoyage de 10 000 ms, une période de 60 secondes en cas de comportement anormal, un seuil d'inactivité de 300 secondes et un seuil d'utilisation du processeur de 85 % pour qu'un document soit éligible au nettoyage. Il inclut également un délai d'inactivité de 3 600 secondes par document.

Ce même modèle inclut des délais d'expiration par vue. Les valeurs actuelles indiquent 300 secondes avant qu'une vue hors focus ne soit assombrie et que les mises à jour cessent, et 900 secondes avant qu'une vue inactive ne subisse le même traitement. Ces délais d'expiration ne correspondent pas à la fermeture immédiate d'une session de document complète.

Évitez de régler le seuil d'utilisation du processeur à un niveau trop bas uniquement pour améliorer l'apparence du graphique. Le nettoyage est conçu pour identifier les documents corrompus ou inactifs qui consomment beaucoup de ressources, et non pour interrompre l'édition en cours dès qu'elle devient gourmande en ressources.

7. Redémarrez uniquement après avoir enregistré une modification de configuration contrôlée.

Commencez par sauvegarder la configuration active. Les installations de paquets utilisent généralement /etc/coolwsd/coolwsd.xml`git log`. Les déploiements Docker peuvent transmettre des options via des variables d'environnement ou des substitutions en ligne de commande, ou encore monter un fichier de configuration dans le conteneur. Vérifiez quelle source est réellement active avant toute modification.

Pour l'installation d'un paquet :

sudo cp /etc/coolwsd/coolwsd.xml /etc/coolwsd/coolwsd.xml.before-cpu-tuning
sudo systemctl restart coolwsd
systemctl status coolwsd --no-pager

Pour un conteneur Docker :

docker restart collabora
docker ps --filter name=collabora

Si un redémarrage suffit à résoudre temporairement le problème du processeur, mais que celui-ci persiste, il s'agit d'une information de diagnostic et non d'une solution permanente. Poursuivez la procédure jusqu'à ce que vous puissiez identifier la charge de travail ou l'état à l'origine de la récurrence du problème.

8. Comparer avant et après, à charge de travail égale.

Utilisez le même document, un nombre d'utilisateurs similaire et la même séquence d'opérations. Mesurez les résultats sur plusieurs minutes plutôt que de comparer un instant précis. Dans ce scénario, le succès se traduirait par le fait que le serveur n'est plus saturé pendant la charge de travail reproduite, et que l'ouverture, la modification, l'enregistrement et la collaboration sur les documents restent fonctionnels.

Quand faut-il mettre à jour plutôt que de régler le système ?

Si ce comportement est apparu avec une version spécifique de Collabora et que vous pouvez le reproduire avec un fichier ou une opération particulière, un réglage de la configuration risque de masquer un défaut logiciel. Collabora recommande d'utiliser la dernière version de la branche stable actuelle. Au 7 octobre 2026, la page officielle des notes de version 26.04 indique que la version 26.04.3.3 est la dernière version de Collabora Online disponible.

Pour les utilisateurs de CODE, il est important de rappeler que Collabora décrit l'édition Développement comme étant adaptée aux petites équipes, à un usage personnel, au développement et à la découverte de nouvelles fonctionnalités, tout en précisant qu'elle n'est pas conçue pour les environnements de production. Un incident en production sur CODE peut donc justifier le passage à la version Collabora Online, qui bénéficie d'un support technique, plutôt que de s'efforcer indéfiniment de contourner le comportement de l'édition Développement.

Ce qu'il ne faut pas faire

• Ne présumez pas qu'un coolwsdnombre élevé prouve une fuite de mémoire ou une boucle infinie.
• Ne configurez pas en permanence la journalisation de débogage ou de traçage pendant un incident lié au processeur, sauf si cela est réellement nécessaire ; la journalisation détaillée ajoute sa propre surcharge et une pression accrue sur le stockage.
• N’exposez pas la console d’administration ou le point de terminaison des métriques sur Internet public à des fins de simple commodité de surveillance.
• Ne réduisez pas les seuils de nettoyage tant que les sessions actives normales ne sont pas interrompues.
• N’utilisez pas les quotas de processeur comme première étape de diagnostic. Une limite stricte peut protéger les autres utilisateurs sur un serveur partagé, mais elle risque de transformer un problème de processeur en ralentissements du rendu des documents et en délais d’attente sans en révéler la cause.

Ordre de dépannage recommandé

1. Confirmez si le processus occupé est coolwsd, un processus plus ancien loolwsd, ou un processus enfant/forkit.
2. Enregistrez le processeur, la mémoire, les documents actifs et les vues du serveur Docker ou de l'hôte.
3. Corréler les journaux avec la fenêtre de pic exacte.
4. Reproduisez le problème avec un document suspect, puis avec un document témoin simple.
5. Effectuez ce test per_document.max_concurrencyuniquement si un document utilise trop de ressources CPU parallèles.
6. Examinez les paramètres de nettoyage et de veille sans les rendre inutilement agressifs.
7. Redémarrez après chaque modification de configuration contrôlée et vérifiez l'état du service.
8. Comparez la même charge de travail avant et après, puis vérifiez la version stable actuelle pour voir si le comportement semble spécifique à une version.

Références officielles

Les détails de configuration présentés dans ce guide sont basés sur le modèle source actuel de Collabora Online : le modèle de configuration coolwsd.xml de Collabora Online . Le manuel officiel du SDK documente la journalisation, les contrôles de performance et le point de terminaison des métriques compatible avec Prometheus : Manuel du SDK de Collabora Online . Pour vérifier la version, consultez les notes de version de Collabora Online 26.04 fournies par le fabricant . Pour connaître l'utilisation prévue de l'édition Développement, consultez l' annonce officielle de la version CODE 26.04 .

L’objectif pratique n’est pas de contraindre Collabora Online à utiliser le moins de ressources processeur possible. Il s’agit de rendre la consommation du processeur compréhensible et proportionnelle à l’activité utile, tout en préservant des performances acceptables en matière d’édition et de collaboration.