Como depurar logs de conexão do Collabora Online com o nível de log do coolwsd

O modelo de configuração pública atual do Collabora Online ainda expõe o parâmetro `--level` logging.levelem `<caminho_para_o_modelo> coolwsd.xml`, com valores suportados que variam de ` warning--level` a `--level`. Em caso de falha de conexão, aumente o nível brevemente, reproduza uma conexão com falha, inspecione o destino real do log do serviço e restaure o nível normal ao concluir. O valor exibido no XML nem sempre é o valor efetivo: um comando de inicialização ou uma configuração do contêiner pode substituí-lo, e áreas com alto nível de detalhamento, como o registro de logs do WebSocket, podem ser desativadas separadamente.debugtrace

Este guia se concentra no diagnóstico de falhas de conexão entre o navegador e o Collabora ou na abertura de documentos. Ele utiliza o coolwsd.xml.inmodelo de código-fonte público atual e o material oficial do Collabora, verificado em 6 de outubro de 2026. Os padrões de pacotes e nomes de serviços podem variar de acordo com a versão e a implantação; portanto, confirme a sua instância em execução antes de copiar caminhos ou executar comandos de reinicialização.

O que muda o nível de registro do coolwsd

coolwsdé o daemon WebSocket do Collabora Online, o processo do servidor que gerencia as sessões do navegador e a atividade dos documentos. Seu nível de registro determina a quantidade de detalhes que o processo emite. O modelo de origem atual lista níveis nomeados, incluindo fatal, critical, error, warning, notice, information, debug, e trace, bem como níveis numéricos de 0 a 8. Os valores numéricos variam do menos detalhado ao mais detalhado. Para uma primeira análise diagnóstica, debugé um nível razoável; use traceapenas quando precisar de detalhes de conexão mais precisos.

A configuração separada level_startupcontrola o registro de logs durante a inicialização, e depois o registro retorna ao nível definido em level. O modelo atual define o registro de logs na inicialização como trace; isso não significa que a operação normal permaneça no nível de rastreamento. Evite alterar essa configuração level_startupquando o problema ocorrer depois que o serviço já estiver em execução.

Um registro mais detalhado pode aumentar o volume de logs e incluir URLs, endereços, identificadores de sessão ou outros detalhes operacionais. Trate os logs como informações confidenciais; colete apenas o período necessário e oculte informações sigilosas antes de compartilhá-las.

Etapa 1: Identifique como esta instância do Collabora é executada.

Primeiro, determine se o Collabora Online está sendo executado como um serviço do sistema, em Docker ou Podman, ou em Kubernetes. Isso é importante porque as alterações feitas em um arquivo dentro de um contêiner em execução podem não ser persistidas, e os logs do contêiner podem ser direcionados para a saída padrão em vez de um arquivo.

Pacote do sistema: verifique o serviço em execução e seu nome de unidade, geralmente `<nome_da_unidade>` coolwsd. A configuração geralmente é `<caminho_da_configuração>` /etc/coolwsd/coolwsd.xml. Versões mais antigas podem usar um loolwsdcaminho legado.
Docker ou Podman: identifique o nome do contêiner e como sua configuração é fornecida. Um arquivo montado por bind ou uma variável de implantação geralmente é a fonte persistente de configuração.
Kubernetes: inspecione os valores do Helm, o ConfigMap ou o manifesto de implantação que o fornece coolwsd.xml. Editar um pod diretamente é uma solução temporária.

Um editor de texto exibindo uma seção de registro do arquivo coolwsd.xml com o nível de aviso definido como padrão e o nível de rastreamento como nível de inicialização. — O modelo de configuração pública atual mostra valores separados para o registro normal e para a fase inicial de inicialização.

Antes de editar, faça um backup do arquivo de configuração atual ou salve uma cópia dos valores de implantação. Se você não tiver certeza de qual arquivo o processo em execução está lendo, inspecione primeiro a definição do serviço ou o comando de inicialização. Uma causa comum de uma aparente falha (no-op) é editar um arquivo de exemplo em vez da configuração ativa.

Passo 2: Aumente temporariamente o nível ativo

No ambiente ativo coolwsd.xml, localize a <logging>seção e altere apenas o valor dentro dela <level>. Comece com debug. Se a tentativa de conexão ainda não produzir detalhes suficientes, use brevemente tracepara uma reprodução. Mantenha as level_startupconfigurações existentes de , arquivos e outras configurações não relacionadas inalteradas.

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

O nível de registro do coolwsd.xml mudou de aviso para rastreamento e foi marcado como temporário. — Use o modo de rastreamento temporariamente quando a depuração não mostrar detalhes suficientes; preserve a configuração de inicialização e outras opções XML.

Este é um exemplo resumido da estrutura XML relevante, não um substituto para o arquivo de configuração completo. Para implantações em contêineres, defina a opção por meio do mecanismo persistente compatível com essa imagem ou gráfico. O código-fonte oficial do Collabora inclui configurações de linha de comando para sobrescrita; portanto, se o valor parecer ignorado, verifique os argumentos de inicialização ou os parâmetros de implantação para um segundo logging.levelvalor.

Se os logs forem gravados em um arquivo, o modelo de origem atual documenta o caminho do arquivo em `/var/log` logging.file, geralmente `/ var/log` /var/log/coolwsd.log. No entanto, o registro em arquivo pode ser desativado em uma versão de produção. Se você ativar a saída em arquivo ou usar um caminho personalizado, confirme se a coolconta de serviço tem permissão de gravação nesse local e se o systemd permite que o serviço grave nesse local. Não torne o log legível para todos os usuários para resolver um problema de permissões.

Etapa 3: Reinicie ou reimplemente e, em seguida, reproduza o problema.

A maioria das configurações padrão entra em vigor após a reinicialização do serviço. Reinicie durante uma janela de manutenção adequada ou em uma instância de teste, pois as sessões de edição ativas podem ser interrompidas. Para um serviço systemd, um comando típico é:

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

Use o nome real do serviço no seu host. Para um contêiner, atualize a configuração persistente e reinicie ou reimplemente esse contêiner. Para Kubernetes, aplique a alteração no manifesto ou no Helm por meio do seu processo de lançamento normal. Confirme se o processo inicia corretamente antes de reproduzir o problema.

Registre o horário exato, o usuário afetado ou a conta de teste, a etapa de abertura do documento e o erro visível no navegador. Reproduza a falha uma única vez e, em seguida, pare de gerar solicitações. Uma única tentativa com registro de data e hora é mais fácil de correlacionar entre o Collabora, o proxy reverso e o host de armazenamento ou WOPI do que um longo fluxo de sessões não relacionadas.

Etapa 4: Leia o código-fonte do log da sua implantação.

Para um serviço systemd, acompanhe o registro de eventos enquanto reproduz o problema:

sudo journalctl -u coolwsd -f

Para inspecionar uma janela recente delimitada, use ` sudo journalctl -u coolwsd --since "10 minutes ago". Se sua unidade tiver outro nome, substitua-o. Para Docker, use ` docker logs --since 10m --follow CONTAINER_NAMEe substitua CONTAINER_NAMEpor `<nome_do_container>` pelo nome ou ID real do contêiner. Podman e Kubernetes têm seus próprios comandos de log; consulte a documentação de tempo de execução da implantação em vez de presumir que um arquivo de hosts exista.

Duas janelas de terminal exibindo o journalctl para os logs do coolwsd e do docker, com um nome de contêiner provisório e sem exemplo de saída. — Leia a partir do coletor de logs ativo; o texto do nome do contêiner no comando Docker é um marcador que deve ser substituído pelo nome real do seu contêiner.

Se o registro em arquivo estiver ativado, verifique o caminho configurado, por exemplo sudo tail -F /var/log/coolwsd.log, `/var/log/log`. O caminho no seu arquivo pode ser diferente. A ausência de um arquivo não significa necessariamente que o serviço não gerou registros; ele pode estar gravando no diário ou na saída do contêiner.

Etapa 5: Correlacione a sequência de conexão

Comece com as entradas no carimbo de data/hora registrado. Procure por marcadores de aviso e erro e termos relacionados à conexão, como <nome_da_conexão>, <nome_da_conexão> WOPI, WebSocket< Socketnome_da_conexão>, ou o caminho da solicitação relevante. Em um arquivo, um primeiro filtro focado pode ser:

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

Em seguida, siga a sequência: o navegador acessou o URL público? O proxy reverso encaminhou a solicitação? A atualização do WebSocket foi concluída? O Collabora contatou o servidor de hospedagem do documento? Os logs de acesso e de erro de um proxy podem responder a perguntas que o log do coolwsd não consegue responder, como, por exemplo, se a solicitação chegou ao serviço. Se o navegador reportar uma falha de conexão WebSocket, mas o coolwsd não registrar nenhuma solicitação correspondente, investigue o DNS, a terminação TLS, as regras de firewall e o roteamento do proxy reverso antes de alterar as permissões do documento.

O modelo de configuração atual lista Socket`trace_log`, WebSocket`trace_log`, Admin`trace_log` e `trace_log` Pixelentre as opções padrão disabled_areaspara saída com alto nível de detalhamento. Se o registro de rastreamento estiver ativo, mas os detalhes do socket estiverem ausentes, verifique essa configuração. Para um diagnóstico rápido, remova apenas a área relevante Socketda WebSocketlista de itens desativados (separada por vírgulas), mantendo as exclusões não relacionadas intactas. Reinicie ou reimplemente e repita o mesmo teste controlado. Restaure a lista original após coletar as evidências.

Etapa 6: Restaure o registro normal e proteja as evidências.

Retorne <level>ao valor de produção anterior, geralmente warningno modelo de código-fonte público, e restaure quaisquer alterações disabled_areas. Reinicie ou reimplemente, se necessário, de acordo com o seu pacote. Confirme se o serviço está íntegro e se as novas mensagens de depuração ou rastreamento cessaram. Mantenha apenas o trecho de diagnóstico com tempo limitado em um local restrito.

O nível de registro do coolwsd foi restaurado para aviso, com um comando de terminal pronto para filtrar as linhas de log relacionadas à conexão. — Restaure o nível de registro normal após o teste e, em seguida, revise um trecho específico e relevante, em vez de compartilhar um despejo de registro completo.

Antes de enviar um trecho do log para o suporte da Collabora ou para um administrador, remova tokens de acesso, cabeçalhos de autorização, URLs assinadas, nomes de usuário, nomes de host privados e nomes de documentos, sempre que possível. Preserve os registros de data e hora e o contexto de erro não sensível necessário para reproduzir a sequência.

Erros comuns de depuração

Alterar apenas level_startup: esta configuração aplica-se à fase inicial de inicialização e, em seguida, recorre ao valor padrão level. Para uma falha após a inicialização, altere level.
Supondo que tracetodas as categorias estejam habilitadas: áreas desabilitadas podem suprimir mensagens de socket ou WebSocket com alto nível de detalhamento. Verifique a lista de filtros.
Procurar no lugar errado: o diário, a saída do contêiner e um arquivo são destinos de log diferentes. Determine qual deles está ativo antes de solucionar problemas com um arquivo vazio.
Manter o rastreamento ativado: o registro de alto volume pode crescer rapidamente e expor mais detalhes operacionais. Restaure o valor anterior assim que o teste for concluído.
Alterar várias configurações ao mesmo tempo dificulta a identificação da configuração que afetou o resultado. Ajuste um valor, reproduza a falha e registre o resultado.

Fontes

Deixar um comentário

O que é o Microsoft Access? Como funcionam suas ferramentas de banco de dados?

O Microsoft Access é um aplicativo de banco de dados para Windows que permite armazenar registros relacionados, criar consultas, elaborar formulários de entrada de dados e gerar relatórios. Saiba como ele funciona e quando é adequado para você.

Alterar a altura e a largura das linhas de grade no Word 2010

Aprenda como ajustar a altura e a largura das linhas de grade no Word 2010, alterar a frequência das linhas visíveis e definir o espaçamento horizontal e vertical da grade de desenho subjacente.

Importação e exportação do Office Outlook 2010: Mova dados com um arquivo PST

Aprenda como importar um arquivo PST para o Outlook 2010 ou exportar emails, contatos, calendário e tarefas. Siga os menus corretos e evite pastas ausentes ou duplicadas.

Recupere a senha de um arquivo PST do Outlook com o Nucleus Kernel

Recupere uma senha esquecida de um arquivo PST do Outlook seguindo os passos atuais do Kernel, incluindo como identificar o arquivo correto, fazer um backup e verificar as limitações da ferramenta.

Como inserir uma página da web em um slide do PowerPoint

Use o suplemento LiveWeb para inserir um site em um slide do PowerPoint, definir seu tamanho e comportamento de atualização e verificar a compatibilidade antes da apresentação.

Contatos do Outlook 2010: Adicionar pessoas e usar a agenda de endereços

Aprenda como criar e organizar contatos no Outlook 2010, criar um grupo de contatos e selecionar pessoas salvas na Agenda de Endereços ao endereçar um e-mail.

Como criar um campo de hiperlink no Access 2010

Crie um campo de Hiperlink no Access 2010 no Modo de Exibição de Design e, em seguida, adicione e teste links para sites, e-mails ou arquivos compartilhados com os detalhes de destino corretos.

Como remover metadados e conteúdo ocultos de um documento do Word

Use o Inspetor de Documentos do Word para revisar detalhes do autor, comentários, alterações controladas, texto oculto e outros dados antes de compartilhar, e descubra o que a verificação pode não detectar.

Exportar e importar configurações da Faixa de Opções e da Barra de Ferramentas de Acesso Rápido no Office 2010

Mova guias personalizadas da Faixa de Opções e comandos da Barra de Ferramentas de Acesso Rápido no Office 2010 com um arquivo .exportedUI e proteja as configurações já existentes no seu computador de destino.

Converter uma planilha do Excel em papel quadriculado imprimível

Crie papel quadriculado imprimível no Excel ajustando as dimensões das células, definindo uma área de impressão, escolhendo papel A4 e ativando a impressão de linhas de grade no Excel para desktop.