Troubleshooting Containers: Logs e Debugging Rápido

Introdução ao Troubleshooting de Containers

Em ambientes de produção, especialmente quando se utiliza orquestração básica com Docker Compose em VPSs, a capacidade de diagnosticar falhas rapidamente é tão crítica quanto a própria configuração dos serviços. O troubleshooting de containers não se trata apenas de ler logs, mas de entender a interdependência entre processos, redes, volumes e certificados de segurança.

Este guia técnico aborda as metodologias essenciais para identificar e resolver problemas comuns em stacks modernas, integrando práticas de debugging, análise de logs Docker, verificação de integridade de volumes persistentes e resolução de problemas com proxies reversos como o Traefik. O foco é fornecer ações concretas que sysadmins e desenvolvedores possam aplicar imediatamente em seus ambientes Linux.

1. Coleta Eficiente de Logs

O primeiro passo em qualquer investigação de falha é examinar o histórico de execução do container. Os logs são a fonte primária de informação sobre erros de aplicação, timeouts de conexão e exceções não tratadas. O comando docker logs é sua principal ferramenta, mas seu uso eficiente exige o conhecimento de flags específicas para filtrar ruído e focar no problema.

Para visualizar os logs de um container específico em tempo real, utilize a flag -f (follow). Isso permite que você monitore o fluxo de saída padrão enquanto reprodiz o erro:

docker logs -f [nome_do_container]

No entanto, em ambientes com múltiplos serviços, o volume de informação pode ser esmagador. É crucial usar a flag --tail para limitar a visualização às últimas linhas geradas antes do crash ou erro:

docker logs --tail 50 [nome_do_container]

Se o problema ocorreu horas atrás, você precisará filtrar por tempo. O Docker permite buscar logs anteriores usando a flag --since. Esta é uma técnica poderosa para investigar incidentes passados sem precisar de ferramentas externas de logging como ELK ou Loki inicialmente:

docker logs --since "2023-10-27T10:00:00" [nome_do_container]

Além disso, sempre verifique se o container está executando a imagem correta e se as variáveis de ambiente foram passadas corretamente. Um erro comum é assumir que uma variável foi definida quando ela não foi injetada no contexto do container. Use docker inspect para validar o ambiente:

docker inspect -f '{{range .Config.Env}}{{println .}}{{end}}' [nome_do_container]

2. Debugging de Rede e Conectividade

Quando uma aplicação containerizada não consegue se comunicar com o banco de dados, cache ou outros microsserviços, o problema geralmente reside na camada de rede do Docker. O Docker cria redes bridge isoladas por padrão, e erros de DNS ou roteamento são frequentes em configurações complexas.

A primeira verificação deve ser a conectividade interna. Entre no container afetado usando docker exec para rodar comandos de diagnóstico diretamente dentro do contexto da aplicação:

docker exec -it [nome_do_container] sh

Dentro do shell do container, utilize ferramentas como ping, nslookup ou curl para testar a resolução de nomes e a acessibilidade dos serviços. Lembre-se de que os containers não se comunicam pelo IP host, mas sim pelos nomes definidos no arquivo docker-compose.yml:

ping db-service
nslookup redis-cache
curl http://api-gateway:8080/health

Se a resolução de DNS falhar, verifique se o serviço está na mesma rede definida no Compose. Você pode listar as redes disponíveis e suas configurações com:

docker network ls
docker network inspect [nome_da_rede]

Para troubleshoot avançado de redes Docker, é útil verificar se há conflitos de portas ou se o iptables está bloqueando a comunicação. Em muitos casos, reiniciar a rede do Docker ou aplicar um flush nas regras de firewall pode resolver problemas intermitentes de roteamento:

sudo systemctl restart docker
sudo iptables -F

Se você estiver utilizando Traefik como proxy reverso, a maioria dos problemas de conectividade externa é na verdade um problema de configuração de Middlewares ou Routes. Verifique os logs do Traefik para ver se ele está reconhecendo as regras de roteamento definidas nos seus containers:

docker logs -f traefik

Procure por mensagens de erro relacionadas a "provider", "rule" ou "service". Se o Traefik não está gerando configurações para um container, verifique se as labels do Docker Compose estão sintaticamente corretas e se o container está na rede correta que o Traefik monitora.

3. Integridade de Volumes Persistentes

A perda ou corrupção de dados é um cenário crítico. Problemas com volumes persistentes podem manifestar-se como falhas ao iniciar bancos de dados (como PostgreSQL ou MySQL) devido a permissões incorretas ou diretórios corrompidos.

Se um banco de dados falha ao iniciar, verifique os logs para erros de "permission denied" ou "data directory has wrong ownership". O Docker Desktop e o Docker Engine em Linux geralmente rodam containers com um UID específico (frequentemente 999 ou root, dependendo da imagem). Se os arquivos no volume host foram criados por outro usuário, o container não terá acesso.

A solução envolve ajustar as permissões do diretório mapeado no host. Por exemplo, para garantir que o usuário dentro do container PostgreSQL tenha acesso:

sudo chown -R 999:999 /caminho/para/seu/volume/postgres
sudo chmod -R 750 /caminho/para/seu/volume/postgres

Outro cenário comum é o esgotamento de espaço em disco. Verifique a utilização do volume com:

docker system df -v

Este comando detalha quanto espaço cada volume está consumindo no disco host. Se um volume de logs ou banco de dados cresceu descontroladamente, você pode precisar fazer rotação manual dos logs ou expandir o armazenamento da VPS.

Para verificar a saúde do sistema de arquivos dentro do container sem entrar nele, use:

docker exec [nome_do_container] df -h

4. Troubleshooting com Traefik e SSL Automático

O Traefik é amplamente utilizado para gerenciar HTTPS e roteamento em stacks Docker. Problemas comuns incluem falhas na obtenção de certificados Let's Encrypt e redirecionamentos incorretos.

4.1. Falhas no SSL Automático

Se o certificado não é emitido, verifique três pontos críticos:

• DNS: O registro DNS do seu domínio aponta corretamente para o IP da sua VPS? Use dig ou nslookup para verificar.
• Portas 80 e 443: O Traefik precisa ter acesso a estas portas no host. Verifique se não há outro serviço (como Apache, Nginx padrão ou outro Docker container) ocupando-as.
• Webhook ACME: O Traefik deve conseguir acessar o endpoint de validação HTTP-01 do Let's Encrypt. Se você está atrás de um firewall restritivo ou ISP que bloqueia conexões de saída para a CA, isso falhará.

Verifique os logs do Traefik especificamente por mensagens "acme" e "http-01". Um erro comum é esquecer de expor a porta 80 do container Traefik no host:

ports:
  - "80:80"
  - "443:443"

Se o certificado estiver pendente, você pode forçar uma nova tentativa removendo o arquivo ACME do container (após fazer backup) e reiniciando o serviço, mas isso deve ser feito com cautela para não exceder os limites de taxa da Let's Encrypt.

4.2. Redirecionamentos e Middlewares

Se o site carrega sem HTTPS ou redireciona incorretamente, verifique a configuração do middleware redirectScheme. Um erro frequente é definir o scheme para https mas esquecer de configurar o permanently: true, resultando em loops de redirecionamento ou avisos de segurança nos navegadores.

A estrutura correta no Compose geralmente parece com:

traefik.http.middlewares.https-redirect.redirectscheme.scheme=https
traefik.http.middlewares.https-redirect.redirectscheme.permanent=true

5. Manutenção Automatizada e Watchtower

Após resolver um problema, a tendência é aplicar uma correção que requer atualização da imagem do container. Aqui entra o Watchtower, uma ferramenta para atualizar containers automaticamente quando novas imagens são publicadas.

No entanto, o troubleshooting de atualizações automáticas exige atenção para evitar downtime durante o processo. O Watchtower pode matar um container antes que a nova versão esteja pronta para aceitar conexões, causando erros 502 Bad Gateway no Traefik.

Configure o Watchtower com flags de limpeza e notificação para garantir transparência:

docker run -d \
  --name watchtower \
  -v /var/run/docker.sock:/var/run/docker.sock \
  containrrr/watchtower \
  --cleanup \
  --label-enable \
  --interval 300

A flag --label-enable garante que apenas containers marcados com a label com.centurylinklabs.watchtower.enable=true sejam atualizados, evitando atualizações acidentais de serviços críticos como o próprio banco de dados ou o proxy.

Se uma atualização quebrar sua stack, o Watchtower não possui "rollback" nativo simples. O procedimento de recuperação envolve:

1. Pull da imagem antiga manualmente: docker pull nome-imagem:v1.0
2. Reiniciar o container com a tag antiga.
3. Desabilitar temporariamente o Watchtower para o serviço afetado.

6. Checklist Final de Diagnóstico

Antes de fechar um ticket ou considerar um problema resolvido, siga este checklist técnico:

• Logs: O container está gerando logs consistentes sem erros críticos?
• Healthcheck: O status do container no Docker é "healthy"? Verifique com docker ps.
• Rede: Outros containers na mesma rede podem resolver o nome e acessar a porta exposta?
• Permissões: O usuário dentro do container tem acesso de leitura/escrita aos volumes montados?
• Recursos: A VPS não está em swap ou sem memória RAM? Use htop ou free -m para verificar.

Domínio dessas técnicas de troubleshooting containers reduz drasticamente o MTTR (Mean Time To Recovery) e aumenta a estabilidade da sua infraestrutura. Lembre-se: logs são seus melhores amigos, e a documentação oficial do Docker é sempre atualizada com as nuances das versões mais recentes.