coolwsdログレベルを使用してCollaboraオンライン接続ログをデバッグする方法

Collabora Online の現在の公開設定テンプレートでは、引き続きが公開logging.levelされておりcoolwsd.xml、サポートされている値は から までです。接続に失敗した場合は、一時的にレベルを上げて、失敗した接続を 1 回再現し、サービスの実際のログ出力先を調べ、完了したら通常のレベルに戻してください。XML に表示される値は、必ずしも有効な値ではありません。起動コマンドやコンテナ設定によって上書きされる場合があり、WebSocket のログ記録など、詳細なログ領域は個別に無効にできる場合があります。warningdebugtrace

このガイドでは、ブラウザとCollabora間の接続エラーやドキュメントの開き方のエラーの診断に焦点を当てています。coolwsd.xml.in2026年10月6日に検証された最新の公開ソーステンプレートと公式Collabora資料を使用しています。パッケージのデフォルト値やサービス名はリリースやデプロイメントによって異なる場合があるため、パスをコピーしたり再起動コマンドを実行する前に、実行中のインスタンスを確認してください。

coolwsdのログレベルが変更する内容

coolwsdCollabora Online WebSocket デーモンは、ブラウザセッションとドキュメントアクティビティを処理するサーバープロセスです。ログレベルによって、プロセスが出力する詳細情報が決まります。現在のソーステンプレートには、、、、、、、、、といった名前付きレベルと、数値レベル 0～8 がリストされています。数値はfatal、最も冗長性の低いものから最も冗長性の高いものへと続きます。最初の診断では、criticalが適切なステップアップです。より詳細な接続情報が必要な場合にのみ、を使用してください。errorwarningnoticeinformationdebugtracedebugtrace

個別の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。Pod を直接編集するのは一時的なものです。

編集する前に、実際の構成ファイルのバックアップを作成するか、デプロイメント値のコピーを保存してください。実行中のプロセスがどのファイルを読み込んでいるか不明な場合は、まずサービス定義または起動コマンドを確認してください。何も操作が行われないように見える一般的な原因は、アクティブな構成ではなくサンプルファイルを編集していることです。

ステップ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（通常は/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、 をCONTAINER_NAME実際のコンテナ名または ID に置き換えてください。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、、、、、がリストされています。トレースログが有効になっているにもかかわらずソケットの詳細が表示されない場合は、この設定を確認してください。簡単な診断を行うには、カンマ区切りの無効化リストから関連する、または領域のみを削除し、無関係な除外はそのままにしておきます。を再起動または再デプロイし、同じ制御テストを繰り返します。証拠を収集したら、元のリストに戻します。WebSocketAdminPixeldisabled_areasSocketWebSocket

ステップ6：通常のログ記録を復元し、証拠を保護する

<level>以前の運用値（通常はwarning公開ソーステンプレート）に戻し、変更された設定を復元しますdisabled_areas。パッケージングで必要な場合は、再起動または再デプロイします。サービスが正常に動作し、新しいデバッグメッセージやトレースメッセージが停止していることを確認します。時間制限付きの診断抜粋のみを制限された場所に保持します。

Collaboraのサポートまたは管理者へログの抜粋を送信する前に、可能な限りアクセストークン、認証ヘッダー、署名付きURL、ユーザー名、プライベートホスト名、およびドキュメント名を削除してください。タイムスタンプと、一連のエラーを再現するために必要な機密性の低いエラーコンテキストは保持してください。

よくあるデバッグのミス

• 変更のみlevel_startup:この設定は初期起動フェーズに適用され、その後は に戻りますlevel。起動後に失敗した場合は、 を変更してくださいlevel。
• traceすべてのカテゴリが有効になっていると仮定します。無効になっている領域では、冗長なソケットメッセージやWebSocketメッセージが抑制される可能性があります。フィルタリストを確認してください。
• 間違った場所を参照している可能性があります。ジャーナル、コンテナ出力、ファイルはそれぞれ異なるログ出力先です。空のファイルのトラブルシューティングを行う前に、どのログ出力先がアクティブになっているかを確認してください。
• トレースを有効にしたままにしておくと、ログの量が急増し、運用上の詳細情報が明らかになる場合があります。テストが完了したら、すぐに以前の値に戻してください。
• 複数の設定を同時に変更すると、どの設定が結果に影響を与えたのかを特定するのが難しくなります。値を1つだけ調整し、失敗を1回再現して、結果を記録してください。

情報源

• Collabora Online ソース: coolwsd.xml.in ログオプション
• Collabora Onlineソース：本番環境のログ記録のデフォルト設定
• Collabora オンライン SDK マニュアル、24.04
• Collabora Onlineのデプロイ構成用Helm値