How to Fix Collabora Online High CPU Usage from loolwsd / coolwsd

When Collabora Online suddenly uses most of a server's CPU, the most important first step is not to restart it repeatedly or immediately impose a very low CPU limit. First determine whether the load comes from normal document work, one pathological document session, too much parallel work, an idle session that is not being cleaned up, or a version-specific regression. The process name may be coolwsd on current releases and loolwsd on older installations.

Illustrative scenario: imagine an 8-vCPU server running Collabora Online behind Nextcloud. Only a few people appear to be editing documents, but the Collabora container sits around 250% to 350% CPU for several minutes. This is a hypothetical example used throughout this guide, not a measured benchmark or a report from a real deployment.

As of October 2026, Collabora's current stable branch is 26.04, and the official release notes list Collabora Online 26.04.3.3 as released on September 14, 2026. Current configuration templates use the coolwsd name. Collabora's migration tooling still documents the older /etc/loolwsd/loolwsd.xml path for installations from the 6.4 era or earlier, which is why administrators may still encounter both names.

1. Confirm which process is actually consuming CPU

Start at the operating-system or container level. A high number beside coolwsd does not automatically mean the coordinating daemon itself is doing all of the expensive document work. Collabora also runs kit/forkit processes for document sessions, so you want the process tree and per-process CPU usage before changing 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')

For Docker, also check the container as a whole:

docker stats --no-stream

In the illustrative scenario, suppose the container is near 300% CPU and one kit process is consistently at the top of the process list. That points you toward a specific active document session rather than a generic assumption that the entire server is overloaded.

2. Check Collabora's own metrics instead of relying only on top

Collabora Online exposes Prometheus-compatible metrics at /cool/getMetrics. The current SDK manual says this endpoint can report CPU and memory use, running kit processes, views, and other server-usage data. It uses the same authentication as the admin console unless metrics are explicitly configured for unauthenticated access.

Maak het metrics-eindpunt niet openbaar, alleen maar om het oplossen van problemen te vereenvoudigen. De officiële Helm-configuratie bevat zelfs voorbeelden voor het blokkeren van /cool/getMetricsURL's en beheerders-URL's bij een ingress. Gebruik waar mogelijk een geauthenticeerd, intern pad.

Zoek naar een verband tussen het CPU-gebruik en actieve documenten of weergaven. Als het CPU-gebruik stijgt en daalt bij legitieme bewerkingsactiviteiten, kan er sprake zijn van een capaciteits- of gelijktijdigheidsprobleem. Als het CPU-gebruik hoog blijft zonder bijbehorende interactieve werkzaamheden, onderzoek dan verouderde sessies, een problematisch document, herhaaldelijk uitgevoerde achtergrondtaken of een softwareprobleem.

3. Lees de logbestanden rond het exacte tijdstip waarop de CPU-belasting stijgt.

Voor een pakketinstallatie die wordt beheerd door systemd:

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

Voor Docker:

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

Als uw service of container een andere naam heeft, vervang deze dan. Zoek naar herhaaldelijk laden van documenten, herhaaldelijk aanmaken van kits, mislukte opslagpogingen, crashes, herverbindingslussen of dezelfde documentsleutel die steeds opnieuw verschijnt. Een korte periode met een hoger CPU-gebruik tijdens het openen, herberekenen, renderen, converteren of exporteren van documenten kan legitiem zijn. Een sterker waarschuwingssignaal is een aanhoudend hoog CPU-gebruik zonder nuttige voortgang of het herhaaldelijk optreden van dezelfde fout.

4. Reproduceer de piek met één document tegelijk.

Ga terug naar de hypothetische server. Als een van de processen in de kit veel CPU-gebruik vertoont, sluit of isoleer dan het betreffende document en observeer of het CPU-gebruik daalt. Open vervolgens hetzelfde bestand tijdens een rustige periode en houd de proceslijst en statistieken in de gaten. Herhaal dit met een eenvoudig testdocument.

Deze vergelijking is nuttiger dan het direct herstarten van de hele dienst:

• Als slechts één bestand consequent de piek veroorzaakt, is de inhoud van het bestand, de formules, ingesloten objecten, de renderingbelasting of een documentspecifieke bug een sterkere verdachte.
• Als elk bestand tot een vergelijkbare belasting leidt zodra meerdere gebruikers actief zijn, onderzoek dan de servercapaciteit en het aantal gelijktijdige gebruikers.
• Als het CPU-gebruik hoog blijft nadat alle gebruikersactiviteit is gestopt, richt u zich op opschoning, verouderde kits, herhaalde achtergrondtaken of een regressie.
• Als het probleem direct na een upgrade is ontstaan, noteer dan de oude en nieuwe versies voordat u veel andere variabelen wijzigt.

5. Beperk de gelijktijdige toegang per document wanneer één document de processorkernen kan monopoliseren.

De huidige Collabora-configuratiesjabloon beschrijft per_document.max_concurrencyhet maximale aantal threads dat wordt gebruikt tijdens de verwerking van een document. De standaardwaarde van de sjabloon is 4. Op een kleinere host, of wanneer een enkel complex document de machine kan overbelasten, kan het verlagen van deze waarde het CPU-gebruik voorspelbaarder maken.

Je zou bijvoorbeeld een waarde van 2 kunnen testen:

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

Kopieer de waarde 2 niet blindelings. Als gebruikers regelmatig grote spreadsheets of presentaties bewerken en de server over voldoende processorkernen beschikt, kan een lagere waarde de werking juist vertragen. Wijzig één instelling, voer dezelfde workload uit en vergelijk het CPU-gebruik, de reactiesnelheid en de verwerkingstijd.

6. Controleer de opschoon- en inactiviteitsinstellingen voordat u ze te agressief maakt.

De huidige coolwsd.xmlsjabloon bevat opschoonlogica voor resourceverslindende inactieve documenten. Op het moment van schrijven toont de sjabloon een opschooncontrole-interval van 10.000 ms, een periode van 60 seconden voor ongewenst gedrag, een drempelwaarde van 300 seconden voor inactiviteit en een drempelwaarde van 85% CPU-gebruik voordat een document in aanmerking komt voor opschoning. Het bevat tevens een time-out van 3.600 seconden voor inactiviteit per document.

Dezelfde sjabloon bevat time-outs per weergave. De huidige waarden geven aan dat een browserweergave die niet actief is, na 300 seconden wordt gedimd en niet meer wordt bijgewerkt, en dat een inactieve weergave na 900 seconden op dezelfde manier wordt behandeld. Deze time-outs voor weergaven zijn niet hetzelfde als het onmiddellijk sluiten van een volledige documentsessie.

Vermijd het instellen van de CPU-drempelwaarde extreem laag, alleen maar om de grafiek er beter uit te laten zien. De opschoonfunctie is bedoeld om resourceverslindende, slechte of inactieve documenten op te sporen, niet om gewone actieve bewerkingen te beëindigen zodra deze te veel rekenkracht vereisen.

7. Herstart alleen nadat een gecontroleerde configuratiewijziging is opgeslagen.

Maak eerst een back-up van de actieve configuratie. Pakketinstallaties gebruiken doorgaans `docker install` /etc/coolwsd/coolwsd.xml. Docker-implementaties kunnen opties doorgeven als omgevingsvariabelen of via de commandoregel, of een configuratiebestand in de container mounten. Controleer welke bron daadwerkelijk actief is voordat u iets wijzigt.

Voor een pakketinstallatie:

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

Voor een Docker-container:

docker restart collabora
docker ps --filter name=collabora

Als een herstart het CPU-probleem tijdelijk oplost, maar het probleem zich vervolgens herhaalt, is dat slechts diagnostische informatie en geen permanente oplossing. Ga door totdat u kunt verklaren welke werkbelasting of toestand de terugkerende problemen veroorzaakt.

8. Vergelijk de situatie voor en na de aanpassing onder dezelfde werkbelasting.

Gebruik hetzelfde document, ongeveer hetzelfde aantal gebruikers en dezelfde volgorde van handelingen. Meet gedurende meerdere minuten in plaats van een enkel moment te vergelijken. In het voorbeeldscenario zou succes betekenen dat de server niet langer overbelast raakt tijdens de nagebootste werkbelasting, terwijl het openen, bewerken, opslaan en samenwerken aan documenten nog steeds naar behoren functioneert.

Wanneer moet je updaten in plaats van tunen?

Als het probleem zich voordoet met een specifieke Collabora-versie en u het kunt reproduceren met een bepaald bestand of een bepaalde bewerking, dan kan het aanpassen van de configuratie mogelijk slechts een softwarefout maskeren. Collabora raadt aan de nieuwste versie uit de huidige stabiele branch te gebruiken. Op 7 oktober 2026 vermeldt de officiële release-opmerkingenpagina van versie 26.04 versie 26.04.3.3 als de meest recente Collabora Online-release die daar wordt weergegeven.

Voor CODE-gebruikers is het belangrijk te onthouden dat Collabora de Development Edition beschrijft als geschikt voor kleine teams, thuisgebruik, ontwikkeling en het uitproberen van nieuwe functionaliteiten, maar aangeeft dat deze niet bedoeld is voor productieomgevingen. Een incident in een productieomgeving met CODE kan daarom een ​​reden zijn om over te stappen naar het ondersteunde Collabora Online-product in plaats van eindeloos te blijven sleutelen aan het gedrag van de Development Edition.

Wat je vooral niet moet doen

• Ga er niet van uit dat een hoog coolwsdgetal wijst op een geheugenlek of een oneindige lus.
• Schakel debug- of trace-logging niet permanent in tijdens een CPU-incident, tenzij dit echt nodig is; uitgebreide logging brengt extra overhead en opslagruimte met zich mee.
• Stel de beheerdersconsole of het meetgegevenspunt niet bloot aan het openbare internet, enkel voor het gemak van monitoring.
• Verlaag de drempelwaarden voor opschoning niet totdat normale actieve sessies worden beëindigd.
• Gebruik CPU-quota niet als eerste diagnostische stap. Een harde limiet kan buren op een gedeelde host beschermen, maar kan een CPU-probleem omzetten in trage documentweergave en time-outs zonder de oorzaak aan het licht te brengen.

Aanbevolen volgorde voor probleemoplossing

1. Bevestig of het drukke proces coolwsdeen ouder proces is loolwsd, of een kinderkit/voorkit-proces.
2. Registreer het CPU-gebruik, het geheugen, de actieve documenten en de weergaven van Docker of de host.
3. Koppel de loggegevens aan het exacte piektijdstip.
4. Reproduceer het probleem met één verdacht document en vervolgens met een eenvoudig controledocument.
5. Test dit per_document.max_concurrencyalleen als één document te veel parallelle CPU-kracht verbruikt.
6. Controleer de opschoon- en inactiviteitsinstellingen zonder ze onnodig agressief te maken.
7. Start de service opnieuw op na elke gecontroleerde configuratiewijziging en controleer de status ervan.
8. Vergelijk dezelfde werklast voor en na de aanpassing en controleer vervolgens de huidige stabiele release als het gedrag versiespecifiek lijkt.

Officiële referenties

De configuratiegegevens in deze handleiding zijn gebaseerd op de huidige Collabora Online-bronsjabloon: Collabora Online coolwsd.xml-configuratiesjabloon . De officiële SDK-handleiding beschrijft logboekregistratie, prestatiebeheer en het Prometheus-compatibele metrische eindpunt: Collabora Online SDK-handleiding . Raadpleeg voor versiecontroles de release-opmerkingen van Collabora Online 26.04 van de fabrikant. Zie de officiële CODE 26.04-releaseaankondiging voor het beoogde gebruik van de Development Edition .

Het praktische doel is niet om Collabora Online zo min mogelijk CPU te laten gebruiken. Het is eerder om het CPU-gebruik verklaarbaar en evenredig te maken aan de nuttige werkzaamheden, met behoud van acceptabele prestaties voor bewerken en samenwerken.