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.

문제 해결을 단순화하기 위해 메트릭 엔드포인트를 공개적으로 노출하지 마십시오. 공식 Helm 설정에는 /cool/getMetrics인그레스에서 차단 및 관리자 URL에 대한 예제가 포함되어 있습니다. 가능한 한 인증된 내부 경로를 사용하십시오.

CPU 사용량과 활성 문서 또는 보기 간의 상관관계를 확인하십시오. 정상적인 편집 활동에 따라 CPU 사용량이 오르락내리락한다면 용량 또는 동시 접속 문제가 있을 수 있습니다. 상호 작용 작업이 없는데도 CPU 사용량이 계속 높다면 오래된 세션, 문제가 있는 문서, 반복적인 백그라운드 작업 또는 소프트웨어 문제를 조사하십시오.

3. CPU 사용량이 급증하는 정확한 시간대의 로그를 읽어보세요.

systemd로 관리되는 패키지 설치의 경우:

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

Docker의 경우:

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

서비스 또는 컨테이너 이름이 다른 경우 해당 이름으로 바꿔주세요. 문서 반복 로드, 키트 반복 생성, 저장 실패, 충돌, 재연결 루프 또는 동일한 문서 키가 반복적으로 나타나는 현상을 찾아보세요. 문서 열기, 재계산, 렌더링, 변환 또는 내보내기 중에 CPU 사용률이 일시적으로 높아지는 것은 정상적인 현상일 수 있습니다. 하지만 CPU 사용률이 지속적으로 높으면서 아무런 진전이 없거나 동일한 오류가 반복되는 경우가 더 심각한 경고 신호입니다.

4. 문서를 하나씩 추가하여 급증 현상을 재현합니다.

가상의 서버로 돌아갑니다. 키트 프로세스 중 하나라도 사용량이 많으면 해당 문서를 닫거나 격리하고 CPU 사용량이 감소하는지 확인합니다. 그런 다음 사용량이 적은 시간대에 동일한 파일을 열고 프로세스 목록과 메트릭을 모니터링합니다. 간단한 테스트 문서를 사용하여 이 과정을 반복합니다.

이러한 비교는 전체 서비스를 즉시 재시작하는 것보다 더 유용합니다.

• 특정 파일 하나만으로 인해 트래픽 급증이 확실하게 발생한다면, 해당 파일의 내용, 수식, 포함된 개체, 렌더링 작업 부하 또는 문서별 버그가 원인일 가능성이 높습니다.
• 여러 사용자가 동시에 접속할 경우 모든 파일에서 비슷한 수준의 과부하가 발생한다면 서버 용량 및 동시 접속률을 점검하십시오.
• 모든 사용자 활동이 중단된 후에도 CPU 사용률이 높게 유지된다면, 정리 작업, 오래된 키트, 반복적인 백그라운드 작업 또는 회귀 오류에 집중해야 합니다.
• 업그레이드 직후 문제가 발생했다면, 다른 여러 변수를 변경하기 전에 이전 버전과 새 버전을 기록해 두십시오.

5. 하나의 문서가 코어를 독점할 수 있는 경우 문서별 동시 처리량을 줄입니다.

현재 Collabora 구성 템플릿 문서에는 per_document.max_concurrency문서 처리 시 사용되는 최대 스레드 수가 명시되어 있습니다. 템플릿의 기본값은 4입니다. 호스트 사양이 낮거나 단일 복잡한 문서가 시스템 자원을 과도하게 사용하는 경우, 이 값을 줄이면 CPU 사용량을 더욱 예측 가능하게 만들 수 있습니다.

예를 들어, 2라는 값을 테스트할 수 있습니다.

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

숫자 2를 맹목적으로 복사하지 마십시오. 사용자가 대용량 스프레드시트나 프레젠테이션을 자주 다루고 서버에 코어 수가 충분한 경우, 더 낮은 값은 오히려 작업 속도를 저하시킬 수 있습니다. 설정을 하나 변경하고 동일한 작업 부하를 재현한 다음 CPU 사용량, 응답 속도 및 완료 시간을 비교해 보십시오.

6. 정리 및 유휴 세션 설정을 적극적으로 적용하기 전에 설정을 확인하십시오.

현재 coolwsd.xml템플릿에는 리소스를 많이 소모하는 유휴 문서를 정리하는 로직이 포함되어 있습니다. 이 글을 작성하는 시점에서 템플릿은 정리 점검 간격을 10,000ms, 비정상 동작 기간을 60초, 유휴 임계값을 300초, CPU 사용률 85% 이상으로 설정하여 문서를 정리 대상으로 지정하고 있습니다. 또한 문서별 유휴 시간 초과를 3,600초로 설정하고 있습니다.

동일한 템플릿에는 뷰별 시간 제한이 포함되어 있습니다. 현재 값은 포커스가 없는 브라우저 뷰가 흐려지고 업데이트가 중지되기까지 300초, 비활성 뷰가 유사하게 처리되기까지 900초가 걸립니다. 이러한 뷰 시간 제한은 전체 문서 세션을 즉시 종료하는 것과는 다릅니다.

그래프를 보기 좋게 하려고 CPU 임계값을 지나치게 낮게 설정하지 마십시오. 정리 기능은 리소스를 많이 소모하는 불량 문서나 유휴 문서를 걸러내기 위한 것이지, 계산 비용이 많이 들 때마다 일반적인 활성 편집 작업을 종료하기 위한 것이 아닙니다.

7. 제어된 구성 변경 사항을 저장한 후에만 재시작하십시오.

먼저 현재 활성화된 구성을 백업하십시오. 패키지 설치는 일반적으로 환경 변수를 사용합니다 /etc/coolwsd/coolwsd.xml. Docker 배포는 환경 변수 또는 명령줄 재정의를 통해 옵션을 전달하거나 구성 파일을 컨테이너에 마운트할 수 있습니다. 편집하기 전에 실제로 활성화된 소스가 무엇인지 확인하십시오.

패키지 설치의 경우:

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

Docker 컨테이너의 경우:

docker restart collabora
docker ps --filter name=collabora

재부팅만으로 CPU 문제가 일시적으로 해결되지만 문제가 반복적으로 재발하는 경우, 이는 문제 해결의 근본적인 원인이 아니라 진단 정보일 뿐입니다. 어떤 작업 부하 또는 상태에서 문제가 재발하는지 파악할 수 있을 때까지 이 과정을 반복하십시오.

8. 동일한 작업 부하 조건에서 전후를 비교합니다.

동일한 문서, 비슷한 수의 사용자, 그리고 동일한 작업 순서를 사용하십시오. 특정 순간을 비교하는 대신 몇 분 동안 측정하십시오. 예시 시나리오에서, 성공적인 결과는 재현된 작업 부하 동안 서버 과부하가 더 이상 발생하지 않으면서 문서 열기, 편집, 저장 및 공동 작업이 허용 가능한 수준으로 작동하는 것을 의미합니다.

튜닝 대신 업데이트를 해야 하는 경우는 언제일까요?

특정 Collabora 버전에서 문제가 발생하기 시작했고 특정 파일이나 작업에서 문제를 재현할 수 있다면, 구성 조정만으로는 소프트웨어 결함을 숨길 수 있습니다. Collabora는 현재 안정 브랜치의 최신 버전을 사용할 것을 권장합니다. 2026년 10월 7일 기준으로 공식 26.04 릴리스 노트 페이지에는 26.04.3.3이 최신 Collabora Online 릴리스로 표시되어 있습니다.

CODE 사용자 여러분께서는 Collabora에서 개발자 에디션을 소규모 팀, 재택 근무, 개발 환경 및 새로운 기능 테스트 용도로 적합하며, 프로덕션 환경에는 적합하지 않다고 명시하고 있음을 유념해 주시기 바랍니다. 따라서 CODE에서 프로덕션 환경에 문제가 발생할 경우, 개발 에디션의 동작 방식을 계속해서 조정하는 것보다 지원되는 Collabora Online 제품으로 전환하는 것이 더 나은 선택일 수 있습니다.

하지 말아야 할 일

• 높은 coolwsd수치가 메모리 누수나 무한 루프를 의미한다고 단정하지 마십시오.
• CPU 문제 발생 시 실제로 필요한 경우가 아니라면 디버그 또는 추적 로깅을 상시 설정하지 마십시오. 자세한 로깅은 추가적인 오버헤드와 저장 공간 부담을 초래합니다.
• 단순히 모니터링 편의를 위해 관리 콘솔이나 메트릭 엔드포인트를 공용 인터넷에 노출하지 마십시오.
• 정상적인 활성 세션이 종료될 때까지 정리 임계값을 낮추지 마십시오.
• CPU 할당량을 첫 번째 진단 단계로 사용하지 마십시오. 엄격한 제한은 공유 호스트에서 이웃 사용자를 보호할 수 있지만, CPU 문제를 문서 렌더링 속도 저하 및 시간 초과로만 나타낼 뿐 근본적인 원인을 파악하지 못하게 할 수 있습니다.

권장되는 문제 해결 순서

1. 바쁜 프로세스가 기존 프로세스인지 coolwsd, loolwsd아니면 하위 키트/키트 프로세스인지 확인하십시오.
2. Docker 또는 호스트의 CPU 사용량, 메모리 사용량, 활성 문서 및 보기 수를 기록합니다.
3. 정확한 급증 기간과 로그를 연관시켜 분석합니다.
4. 의심스러운 문서 하나와 간단한 대조 문서를 사용하여 재현해 보십시오.
5. per_document.max_concurrency특정 문서가 병렬 CPU 사용량을 과도하게 차지하는 경우에만 테스트하십시오 .
6. 정리 및 유휴 설정값을 검토하되, 불필요하게 공격적으로 설정하지 마십시오.
7. 제어된 구성 변경 후에는 재시작하고 서비스 상태를 확인하십시오.
8. 동일한 작업 부하를 적용 전후로 비교한 다음, 동작이 특정 버전과 관련된 것처럼 보이면 현재 안정 버전을 확인하십시오.

공식 참고 자료

이 가이드의 구성 세부 정보는 현재 Collabora Online 소스 템플릿인 Collabora Online coolwsd.xml 구성 템플릿을 기반으로 합니다 . 공식 SDK 설명서에는 로깅, 성능 제어 및 Prometheus 호환 메트릭 엔드포인트에 대한 내용이 나와 있습니다. Collabora Online SDK 설명서를 참조하십시오. 버전 확인은 제조업체의 Collabora Online 26.04 릴리스 노트를 참조하십시오 . 개발자 에디션의 사용 목적에 대해서는 공식 CODE 26.04 릴리스 공지를 참조하십시오 .

실질적인 목표는 Collabora Online이 가능한 한 적은 CPU를 사용하도록 강제하는 것이 아닙니다. 오히려 적절한 편집 및 공동 작업 성능을 유지하면서 CPU 사용량을 설명 가능하고 유용한 작업에 비례하도록 만드는 것입니다.