Comment déboguer les journaux de connexion Collabora Online avec le niveau de journalisation coolwsd

Le modèle de configuration public actuel de Collabora Online expose toujours le logging.levelniveau de journalisation coolwsd.xml, avec des valeurs prises en charge allant de warning0 debugà 100. traceEn cas d'échec de connexion, augmentez brièvement le niveau, reproduisez une connexion défaillante, examinez la destination réelle des journaux du service, puis rétablissez le niveau normal. La valeur affichée dans le fichier XML n'est pas toujours la valeur effective : une commande de démarrage ou un paramètre du conteneur peut la remplacer, et les zones à forte verbosité, telles que la journalisation WebSocket, peuvent être désactivées séparément.

Ce guide explique comment diagnostiquer les problèmes de connexion entre le navigateur et Collabora ou les échecs d'ouverture de documents. Il utilise le coolwsd.xml.inmodèle source public actuel et la documentation officielle de Collabora (mis à jour le 6 octobre 2026). Les valeurs par défaut des packages et les noms des services peuvent varier selon la version et le déploiement ; assurez-vous donc de vérifier votre instance en cours d'exécution avant de copier les chemins d'accès ou les commandes de redémarrage.

Que change le niveau de journalisation de coolwsd ?

coolwsdLe démon WebSocket de Collabora Online est le processus serveur qui gère les sessions de navigation et l'activité des documents. Son niveau de journalisation détermine la quantité de détails qu'il génère. Le modèle de source actuel répertorie les niveaux nommés, notamment fatal` <nom_du_niveau>` , ... et `<nom_du_niveau> critical` , ainsi que les niveaux numériques de 0 à 8. Les valeurs numériques indiquent le niveau de détail le plus ou le moins détaillé. Pour un premier diagnostic, le niveau ` <nom_du_niveau>` est un bon choix ; utilisez-le uniquement si vous avez besoin d'informations de connexion plus précises.errorwarningnoticeinformationdebugtracedebugtrace

Le level_startupparamètre distinct contrôle la journalisation lors du démarrage initial, puis celle-ci revient à son niveau par défaut level. Le modèle actuel configure la journalisation au démarragetrace ; cela ne signifie pas que le fonctionnement normal reste en mode trace. Évitez de modifier ce paramètre level_startupsi le problème survient après le démarrage du service.

Des journaux plus détaillés peuvent augmenter leur volume et contenir des URL, des adresses, des identifiants de session ou d'autres informations opérationnelles. Traitez les journaux comme des données sensibles ; ne collectez que les informations nécessaires sur la période concernée et masquez les données confidentielles avant de les partager.

Étape 1 : Identifier le fonctionnement de cette instance Collabora

Commencez par déterminer si Collabora Online s'exécute en tant que service système, dans Docker ou Podman, ou dans Kubernetes. Cette information est importante car les modifications apportées à un fichier à l'intérieur d'un conteneur en cours d'exécution peuvent ne pas être conservées, et les journaux du conteneur peuvent être redirigés vers la sortie standard plutôt que vers un fichier.

• Package système : vérifiez le service en cours d’exécution et son nom d’unité, généralement `<nom_du_service>` coolwsd. La configuration est généralement `<nom_du_service>` /etc/coolwsd/coolwsd.xml. Les versions plus anciennes peuvent utiliser un loolwsdchemin d’accès hérité.
• Docker ou Podman : identifiez le nom du conteneur et la manière dont sa configuration est fournie. Un fichier monté ou une variable de déploiement constitue généralement la source persistante de la configuration.
• Kubernetes : examinez les valeurs Helm, la ConfigMap ou le manifeste de déploiement qui les fournit coolwsd.xml. La modification directe d’un pod est temporaire.

Avant toute modification, effectuez une sauvegarde du fichier de configuration actuel ou enregistrez une copie des valeurs de déploiement. En cas de doute sur le fichier utilisé par le processus en cours d'exécution, consultez d'abord sa définition de service ou sa commande de démarrage. Une action apparemment inactive est souvent due à la modification d'un fichier de test plutôt que de la configuration active.

Étape 2 : Augmenter temporairement le niveau actif

Dans la configuration active coolwsd.xml, repérez la <logging>section et modifiez uniquement la valeur qu'elle contient <level>. Commencez par debug. Si la tentative de connexion ne fournit toujours pas suffisamment de détails, utilisez brièvement tracepour une reproduction. Laissez inchangés les paramètres de fichiers existants level_startupet toute autre configuration non liée.

<config>
  <logging>
    <level>trace</level>
    <level_startup>trace</level_startup>
  </logging>
</config>

Il s'agit d'un exemple simplifié de la structure XML correspondante, et non d'un remplacement du fichier de configuration complet. Pour les déploiements de conteneurs, configurez l'option via le mécanisme de persistance pris en charge par l'image ou le graphique concerné. Le code source officiel de Collabora inclut des options de configuration en ligne de commande ; si la valeur semble ignorée, vérifiez les arguments de démarrage ou les paramètres de déploiement pour une seconde logging.levelvaleur.

Si les journaux sont enregistrés dans un fichier, le modèle de source actuel indique le chemin d'accès à ce fichier logging.file, généralement sous `/etc/log/log /var/log/coolwsd.log/`. Cependant, l'enregistrement dans un fichier peut être désactivé en production. Si vous activez la sortie dans un fichier ou utilisez un chemin personnalisé, assurez-vous que le coolcompte de service dispose des droits d'écriture et que systemd autorise le service à écrire à cet emplacement. Ne rendez pas le fichier journal accessible à tous pour résoudre un problème d'autorisations.

Étape 3 : Redémarrez ou redéployez, puis reproduisez une fois.

La plupart des configurations packagées prennent effet après un redémarrage du service. Il est recommandé de redémarrer pendant une fenêtre de maintenance appropriée ou sur une instance de test, car les sessions d'édition en cours peuvent être interrompues. Pour un service systemd, la commande typique est :

sudo systemctl restart coolwsd
sudo systemctl status coolwsd --no-pager

Utilisez le nom de service réel sur votre hôte. Pour un conteneur, mettez à jour la configuration persistante et redémarrez ou redéployez-le. Pour Kubernetes, appliquez la modification du manifeste ou de Helm via votre processus de déploiement habituel. Assurez-vous que le processus démarre correctement avant de reproduire le problème.

Enregistrez l'heure exacte, l'utilisateur concerné ou le compte de test, l'étape d'ouverture du document et l'erreur affichée dans le navigateur. Reproduisez l'erreur une seule fois, puis cessez de générer des requêtes. Une seule tentative horodatée est plus facile à corréler entre Collabora, le proxy inverse et le serveur de stockage ou l'hôte WOPI qu'une longue série de sessions sans lien entre elles.

Étape 4 : Consultez la source des journaux de votre déploiement

Pour un service systemd, suivez les instructions du journal lors de la reproduction du problème :

sudo journalctl -u coolwsd -f

Pour consulter une fenêtre récente délimitée, utilisez `docker log` sudo journalctl -u coolwsd --since "10 minutes ago". Si votre unité porte un autre nom, remplacez-le. Pour Docker, utilisez `docker log` docker logs --since 10m --follow CONTAINER_NAMEet remplacez ` CONTAINER_NAME<nom_du_conteneur>` par le nom ou l'ID du conteneur. Podman et Kubernetes possèdent leurs propres commandes de journalisation ; consultez la documentation d'exécution du déploiement plutôt que de supposer l'existence d'un fichier host.

sudo tail -F /var/log/coolwsd.logSi la journalisation dans des fichiers est activée, vérifiez le chemin configuré, par exemple : `/etc/log ...

Étape 5 : Corréler la séquence de connexion

Commencez par les entrées correspondant à l'horodatage enregistré. Recherchez les marqueurs d'avertissement et d'erreur, ainsi que les termes liés à la connexion, tels que WOPI` <input type="connection">`, `<input type="connection">`, `<input type="connection">` WebSocket, Socketou le chemin de requête pertinent. Dans un fichier, un premier filtre ciblé peut être :

grep -Ei 'ERR|WRN|WOPI|WebSocket' /var/log/coolwsd.log

Ensuite, vérifiez la séquence : le navigateur a-t-il atteint l’URL publique ? Le proxy inverse a-t-il transmis la requête ? La mise à niveau WebSocket s’est-elle terminée ? Collabora a-t-il contacté l’hébergeur du document ? Les journaux d’accès et d’erreurs du proxy peuvent répondre à des questions auxquelles le journal de coolwsd ne peut pas répondre, comme par exemple si la requête a bien atteint le service. Si le navigateur signale un échec de connexion WebSocket, mais que coolwsd n’enregistre aucune requête correspondante, examinez le DNS, la terminaison TLS, les règles de pare-feu et le routage du proxy inverse avant de modifier les permissions du document.

Le modèle de configuration actuel inclut les options `--verbose` Socket, `--trace` WebSocket, Admin`--network` et `--network` Pixelparmi les paramètres par défaut disabled_areaspour une sortie détaillée. Si la journalisation des traces est activée mais que les détails des sockets sont absents, examinez ce paramètre. Pour un diagnostic rapide, supprimez uniquement la zone concernée Socketde WebSocketla liste des options désactivées (séparées par des virgules), en conservant les exclusions non pertinentes. Redémarrez ou redéployez le système et répétez le même test contrôlé. Restaurez la liste d'origine après avoir recueilli les données.

Étape 6 : Rétablir la journalisation normale et protéger les preuves

Revenez <level>à la valeur de production précédente, généralement warningdans le modèle source public, et restaurez les modifications disabled_areas. Redémarrez ou redéployez si votre packaging l'exige. Vérifiez que le service est opérationnel et que les nouveaux messages de débogage ou de traçage ont cessé. Conservez uniquement l'extrait de diagnostic temporaire dans un emplacement restreint.

Avant d'envoyer un extrait de journal au support Collabora ou à un administrateur, supprimez autant que possible les jetons d'accès, les en-têtes d'autorisation, les URL signées, les noms d'utilisateur, les noms d'hôtes privés et les noms de documents. Conservez les horodatages et le contexte d'erreur non sensible nécessaire à la reproduction de la séquence.

Erreurs de débogage courantes

• Modification uniquementlevel_startup : ce paramètre s’applique à la phase de démarrage initiale, puis revient à sa valeur par défaut level. En cas d’échec après le démarrage, modifiez la valeur level.
• En supposant que tracetoutes les catégories soient activées : les zones désactivées peuvent masquer les messages de socket ou WebSocket très verbeux. Consultez la liste des filtres.
• Vous cherchez au mauvais endroit : les journaux, la sortie du conteneur et un fichier sont des sources de journalisation différentes. Déterminez laquelle est active avant de résoudre le problème d’un fichier vide.
• L'enregistrement des traces est activé : le volume important de journaux peut croître rapidement et expose davantage de détails opérationnels. Rétablissez la valeur précédente dès que le test est terminé.
• Modifier plusieurs paramètres simultanément complique l'identification du paramètre ayant influencé le résultat. Ajustez une seule valeur, reproduisez le problème et notez le résultat.

Sources

• Source Collabora Online : options de journalisation coolwsd.xml.in
• Source Collabora Online : paramètres par défaut de la journalisation de production
• Manuel du SDK en ligne Collabora, 24.04
• Valeurs Helm de Collabora Online pour la configuration de déploiement