coolwsd 로그 레벨을 사용하여 Collabora Online 연결 로그를 디버깅하는 방법

Collabora Online의 현재 공개 구성 템플릿은 여전히 ​​` <log_reserve_value> logging.level`에 값을 노출하며 coolwsd.xml, 지원되는 값은 ` warning<log_reserve_value> `부터 ` debug<log_reserve_value> trace`까지입니다. 연결 실패 시에는 `reserve_value>` 레벨을 잠시 높인 후, 연결 실패를 재현하고 서비스의 실제 로그 대상 위치를 확인한 다음 작업이 완료되면 원래 레벨로 복원하십시오. XML에 표시된 값이 항상 실제 값은 아닙니다. 시작 명령이나 컨테이너 설정에 따라 값이 재정의될 수 있으며, WebSocket 로깅과 같이 상세도가 높은 영역은 별도로 비활성화될 수 있습니다.

이 가이드는 브라우저와 Collabora 간의 연결 오류 또는 문서 열기 오류를 진단하는 데 중점을 둡니다. coolwsd.xml.in2026년 10월 6일 기준으로 최신 공개 소스 템플릿과 Collabora 공식 자료를 사용했습니다. 패키지 기본값 및 서비스 이름은 릴리스 및 배포 버전에 따라 다를 수 있으므로 경로를 복사하거나 재시작 명령을 실행하기 전에 실행 중인 인스턴스를 확인하십시오.

coolwsd 로그 레벨 변경 사항

coolwsdCollabora Online WebSocket Daemon은 브라우저 세션 및 문서 활동을 처리하는 서버 프로세스입니다. 로그 레벨은 프로세스가 출력하는 상세 정보의 수준을 결정합니다. 현재 소스 템플릿에는 fatal, critical, error, warning, notice, information, debug, 및 trace와 같은 명명된 레벨과 0~8까지의 숫자 레벨이 나열되어 있습니다. 숫자 값은 가장 자세한 정보부터 가장 자세한 정보까지 순서대로 나열됩니다. 초기 진단에는 debug이 레벨이 적절하며 , trace더 자세한 연결 정보가 필요할 때만 사용하십시오.

별도의 level_startup설정은 초기 시작 시 로깅을 제어하며, 이후에는 로깅 수준이 설정값으로 돌아갑니다 level. 현재 템플릿은 시작 시 로깅 수준을 높게 설정하지만 trace, 이는 정상 작동 시에도 추적 로깅 수준이 유지된다는 의미는 아닙니다. level_startup서비스가 이미 실행 중인 상태에서 문제가 발생하면 이 설정을 변경하지 마십시오.

더 자세한 출력은 로그 용량을 증가시킬 수 있으며 URL, 주소, 세션 식별자 또는 기타 운영 세부 정보를 포함할 수 있습니다. 로그는 민감한 정보로 취급해야 하며, 필요한 기간의 로그만 수집하고 공유하기 전에 비밀 정보를 삭제해야 합니다.

1단계: 이 Collabora 인스턴스가 실행되는 방식을 파악합니다.

먼저 Collabora Online이 시스템 서비스로 실행되는지, Docker 또는 Podman에서 실행되는지, 아니면 Kubernetes에서 실행되는지 확인하십시오. 이는 실행 중인 컨테이너 내부의 파일을 변경해도 저장되지 않을 수 있고, 컨테이너 로그가 파일이 아닌 표준 출력으로 전송될 수 있기 때문에 중요합니다.

• 시스템 패키지: 실행 중인 서비스와 해당 유닛 이름(일반적으로 )을 확인하십시오 coolwsd. 구성은 일반적으로 입니다 /etc/coolwsd/coolwsd.xml. 이전 릴리스에서는 레거시 loolwsd경로를 사용할 수 있습니다.
• Docker 또는 Podman: 컨테이너 이름과 구성 제공 방식을 지정합니다. 일반적으로 바인드 마운트된 파일이나 배포 변수가 영구적인 구성 소스로 사용됩니다.
• Kubernetes: Helm 값, ConfigMap 또는 배포 매니페스트를 검사하여 필요한 정보를 확인하세요 coolwsd.xml. 파드를 직접 편집하는 것은 임시적인 조치입니다.

편집하기 전에 실제 구성 파일의 백업을 만들거나 배포 값의 사본을 저장하십시오. 실행 중인 프로세스가 어떤 파일을 읽는지 확실하지 않은 경우 서비스 정의 또는 시작 명령을 먼저 확인하십시오. 아무런 반응이 없는 것처럼 보이는 일반적인 원인은 활성 구성 파일이 아닌 샘플 파일을 편집하는 것입니다.

2단계: 활성 레벨을 일시적으로 높입니다.

활성 설정에서 coolwsd.xml해당 섹션을 찾아 <logging>내부 값만 변경하십시오 <level>. 먼저 로 시작하십시오 debug. 연결 시도 후에도 충분한 세부 정보가 제공되지 않으면 trace재현을 위해 잠시 를 사용하십시오. 기존 설정 level_startup, 파일 설정 및 관련 없는 구성은 변경하지 않고 그대로 두십시오.

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

이는 관련 XML 구조의 축약된 예시이며, 전체 구성 파일을 대체하는 것이 아닙니다. 컨테이너 배포의 경우, 해당 이미지 또는 차트에서 지원하는 영구 저장 메커니즘을 통해 옵션을 설정하십시오. Collabora 공식 소스 코드에는 명령줄 구성 재정의 기능이 포함되어 있으므로, 값이 무시되는 경우 시작 인수 또는 배포 매개변수에서 두 번째 logging.level값을 확인하십시오.

로그가 파일로 저장되는 경우, 현재 소스 템플릿은 logging.file일반적으로 `/ etc/log/log` 아래에 파일 경로를 문서화합니다 /var/log/coolwsd.log. 하지만 프로덕션 빌드에서는 파일 로깅이 비활성화될 수 있습니다. 파일 출력을 활성화하거나 사용자 지정 경로를 사용하는 경우, cool서비스 계정에 해당 위치에 쓰기 권한이 있는지, 그리고 systemd가 서비스에 해당 위치에 쓰기 권한을 허용하는지 확인하십시오. 권한 문제를 해결하기 위해 로그 파일의 읽기 권한을 모든 사용자에게 허용하지 마십시오.

3단계: 재시작 또는 재배포 후, 한 번 재현해 보세요.

대부분의 패키지 구성은 서비스 재시작 후에 적용됩니다. 활성 편집 세션이 중단될 수 있으므로 적절한 유지 관리 시간이나 테스트 인스턴스에서 재시작하십시오. systemd 서비스의 경우 일반적인 명령은 다음과 같습니다.

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

호스트에서 사용하는 실제 서비스 이름을 사용하십시오. 컨테이너의 경우 영구 구성을 업데이트하고 해당 컨테이너를 다시 시작하거나 재배포하십시오. Kubernetes의 경우 일반 릴리스 프로세스를 통해 매니페스트 또는 Helm 변경 사항을 적용하십시오. 문제를 재현하기 전에 프로세스가 정상적으로 시작되는지 확인하십시오.

정확한 시간, 영향을 받은 사용자 또는 테스트 계정, 문서 열기 단계 및 브라우저에 표시되는 오류를 기록하십시오. 오류를 한 번 재현한 후에는 요청 생성을 중지하십시오. 타임스탬프가 찍힌 단일 시도는 관련 없는 세션의 긴 스트림보다 Collabora, 리버스 프록시 및 스토리지 또는 WOPI 호스트 전반에 걸쳐 상관 관계를 파악하기가 더 쉽습니다.

4단계: 배포에 대한 로그 소스를 읽습니다.

systemd 서비스의 경우, 문제를 재현하는 동안 저널을 따라가세요.

sudo journalctl -u coolwsd -f

제한된 최근 창을 검사하려면 를 사용하십시오 sudo journalctl -u coolwsd --since "10 minutes ago". 단위 이름이 다른 경우 해당 이름으로 대체하십시오. Docker의 경우 를 사용 docker logs --since 10m --follow CONTAINER_NAME하고 를 실제 컨테이너 이름 또는 ID로 바꾸십시오 CONTAINER_NAME. Podman과 Kubernetes는 자체 로그 명령을 제공합니다. 호스트 파일이 존재한다고 가정하기보다는 배포 런타임 문서를 확인하십시오.

파일 로깅이 활성화된 경우, 구성된 경로(예: )를 확인하십시오 sudo tail -F /var/log/coolwsd.log. 파일에 있는 경로는 다를 수 있습니다. 파일이 없다고 해서 서비스가 로그를 생성하지 않았다는 의미는 아닙니다. 서비스가 대신 저널이나 컨테이너 출력에 로그를 기록하고 있을 수 있습니다.

5단계: 연결 순서를 상관 분석합니다.

기록된 타임스탬프의 항목부터 시작합니다. 경고 및 오류 표시와 연결 관련 용어(예: WOPI, WebSocket, Socket, 또는 관련 요청 경로)를 검색합니다. 파일에서 먼저 집중적으로 검색할 필터는 다음과 같습니다.

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

다음 순서를 확인하십시오. 브라우저가 공용 URL에 도달했는지, 리버스 프록시가 요청을 전달했는지, WebSocket 업그레이드가 완료되었는지, 그리고 Collabora가 문서 호스트에 연결되었는지 확인하십시오. 프록시의 액세스 및 오류 로그는 coolwsd 로그에서 확인할 수 없는 질문(예: 요청이 서비스에 도달했는지 여부)에 대한 답을 제공할 수 있습니다. 브라우저에서 WebSocket 연결 실패를 보고하지만 coolwsd에 일치하는 요청이 기록되지 않으면 문서 권한을 변경하기 전에 DNS, TLS 종료, 방화벽 규칙 및 리버스 프록시 라우팅을 조사하십시오.

현재 구성 템플릿에는 상세도 높은 출력에 대한 기본값으로 Socket, WebSocket, Admin, 가 포함되어 있습니다. 추적 로깅이 활성화되어 있지만 소켓 세부 정보가 표시되지 않으면 이 설정을 확인하십시오. 간단한 진단을 위해 쉼표로 구분된 비활성화 목록에서 관련 또는 영역만 제거하고 관련 없는 제외 항목은 그대로 유지하십시오. 시스템을 재시작하거나 재배포한 후 동일한 제어 테스트를 반복하십시오. 증거를 수집한 후 원래 목록을 복원하십시오.Pixeldisabled_areasSocketWebSocket

6단계: 정상적인 로깅을 복원하고 증거를 보호합니다.

일반적으로 공개 소스 템플릿에 있는 <level>이전 프로덕션 값으로 되돌리고 변경된 사항을 복원합니다 . 패키징 요구 사항에 따라 다시 시작하거나 재배포합니다. 서비스가 정상적으로 작동하고 새로운 디버그 또는 추적 메시지가 더 이상 표시되지 않는지 확인합니다. 시간 제한이 있는 진단 발췌본만 제한된 위치에 보관합니다.warningdisabled_areas

Collabora 지원팀이나 관리자에게 로그 발췌본을 보내기 전에, 가능한 경우 액세스 토큰, 인증 헤더, 서명된 URL, 사용자 이름, 개인 호스트 이름 및 문서 이름을 제거하십시오. 문제 재현에 필요한 타임스탬프와 민감하지 않은 오류 컨텍스트는 보존하십시오.

흔히 저지르는 디버깅 실수

• 변경 전용 level_startup: 이 설정은 초기 시작 단계에만 적용되며 이후에는 기본값으로 돌아갑니다 level. 시작 후 오류가 발생하면 설정을 변경하십시오 level.
• trace모든 범주가 ​​활성화되어 있다고 가정합니다 . 비활성화된 영역은 상세도가 높은 소켓 또는 웹소켓 메시지를 숨길 수 있습니다. 필터 목록을 확인하세요.
• 잘못된 위치를 보고 있는 것입니다. 저널, 컨테이너 출력 및 파일은 서로 다른 로그 기록 저장소입니다. 빈 파일 문제를 해결하기 전에 어떤 저장소가 활성화되어 있는지 확인하십시오.
• 추적 기능을 활성화합니다. 대용량 로깅은 빠르게 증가할 수 있으며 더 자세한 운영 정보를 제공합니다. 테스트가 완료되면 이전 값으로 복원합니다.
• 여러 설정을 한 번에 변경하면 어떤 설정이 결과에 영향을 미쳤는지 파악하기가 더 어려워집니다. 값 하나만 조정하고, 오류를 한 번 재현한 다음 결과를 기록하십시오.

출처

• Collabora Online 출처: coolwsd.xml.in 로깅 옵션
• Collabora Online 출처: 프로덕션 로깅 기본 설정
• Collabora 온라인 SDK 매뉴얼, 24.04
• Collabora Online Helm 배포 구성 값