Truques para depurar aplicações dentro de containers Docker

Depurar aplicações dentro de containers Docker apresenta desafios únicos. O isolamento, a efemeridade e a ausência de ferramentas familiares podem transformar uma simples investigação em uma tarefa complexa. Este artigo reúne truques práticos para inspecionar, diagnosticar e corrigir problemas em containers, desde ambientes de desenvolvimento até produção.

1. Acessando o Container em Tempo Real

O comando mais fundamental para depuração é o docker exec. Ele permite executar comandos em um container em execução:

docker exec -it meu-container bash

Se o container não tiver bash, tente sh ou ash (em imagens Alpine).

Diferença entre docker exec e docker attach:
- docker exec cria um novo processo no container — ideal para depuração, pois não interfere no processo principal.
- docker attach conecta-se ao processo principal (PID 1) e ao seu STDIN/STDOUT. Se você sair com Ctrl+C, pode encerrar o container.

Dentro do container, instale ferramentas mínimas para diagnóstico:

apt-get update && apt-get install -y curl net-tools iputils-ping
# ou para Alpine:
apk add --no-cache curl busybox-extras

2. Inspecionando Logs e Saída Padrão

O comando docker logs é a primeira ferramenta para entender o comportamento da aplicação:

# Últimas 50 linhas com timestamps
docker logs --tail 50 --timestamps meu-container

# Seguir logs em tempo real
docker logs --follow meu-container

Para análise posterior, redirecione os logs para um arquivo local:

docker logs meu-container > ~/logs/meu-container-$(date +%Y%m%d).log 2>&1

Monitore eventos do ciclo de vida do container:

docker events --filter 'container=meu-container' --since '5m'

Isso ajuda a identificar se o container está reiniciando ou sendo interrompido por políticas de saúde.

3. Verificando Processos e Recursos Internos

Execute comandos de monitoramento diretamente no container:

docker exec meu-container ps aux
docker exec meu-container top -b -n 1

Para métricas de recursos em tempo real, use docker stats:

docker stats meu-container --no-stream
# ou em tempo real:
docker stats meu-container

Procure por processos zumbis (estado Z no ps aux) e vazamentos de memória (uso crescente de RSS ao longo do tempo). Containers que consomem memória além do limite configurado são encerrados pelo OOM killer.

4. Depurando Redes e Conectividade

Teste conectividade básica:

docker exec meu-container ping google.com
docker exec meu-container curl -v http://servico-interno:8080/health

Inspecione portas e conexões ativas:

docker exec meu-container netstat -tulpn
docker port meu-container

Para simular falhas de rede durante testes, use iptables dentro do container (requer --cap-add=NET_ADMIN):

# Bloquear todo tráfego de saída
docker exec meu-container iptables -A OUTPUT -j DROP

# Bloquear porta específica
docker exec meu-container iptables -A INPUT -p tcp --dport 5432 -j DROP

Ferramentas como toxiproxy podem ser executadas como sidecar para simular latência e desconexões de forma controlada.

5. Analisando Sistemas de Arquivos e Volumes

Copie arquivos entre o host e o container sem precisar de shell interativo:

# Do container para o host
docker cp meu-container:/app/logs/error.log ./error.log

# Do host para o container
docker cp ./config.json meu-container:/app/config.json

Verifique permissões de arquivos montados:

docker exec meu-container ls -la /data
docker exec meu-container stat /data/arquivo.conf

Use docker diff para detectar alterações no sistema de arquivos desde a criação do container:

docker diff meu-container

A saída mostra arquivos alterados (C), adicionados (A) ou deletados (D). Isso é útil para verificar se arquivos de configuração estão sendo sobrescritos ou se logs estão sendo gerados no local esperado.

6. Utilizando Imagens com Ferramentas de Depuração Embutidas

Mantenha imagens especializadas para depuração. A imagem nicolaka/netshoot é uma suíte completa de ferramentas de rede:

docker run -it --network container:meu-container nicolaka/netshoot

Isso cria um container que compartilha o namespace de rede do container alvo, permitindo usar tcpdump, ngrep, iftop e outras ferramentas sem instalá-las no container original.

Para produção, construa uma imagem "debug" separada:

# Dockerfile.debug
FROM alpine:latest
RUN apk add --no-cache strace curl tcpdump htop

Use-a apenas quando necessário, minimizando a superfície de ataque em produção.

7. Depuração com Breakpoints e Profiling

Para aplicações Python, injete breakpoints com pdb:

docker exec -it meu-container python -m pdb /app/meu_script.py

Para profiling, use py-spy sem modificar o código da aplicação:

# Instale py-spy no container ou use imagem com suporte
docker exec meu-container py-spy record -o /tmp/profile.svg --pid 1

Para linguagens compiladas (C/C++/Rust), o strace é indispensável:

docker exec meu-container strace -p 1 -e trace=network -o /tmp/strace.log

Atenção: strace e profilers como perf exigem a capacidade SYS_PTRACE:

docker run --cap-add=SYS_PTRACE --security-opt seccomp=unconfined minha-imagem

Use --privileged com cautela — ele concede todas as capacidades e desabilita o seccomp, comprometendo o isolamento.

8. Estratégias para Ambientes de Produção

Em produção, evite instalar ferramentas diretamente no container. Use sidecar containers no mesmo pod (Kubernetes):

# Exemplo conceitual de pod com sidecar de depuração
apiVersion: v1
kind: Pod
spec:
  containers:
  - name: app
    image: minha-aplicacao
  - name: debug
    image: nicolaka/netshoot
    command: ["sleep", "infinity"]

Para depurar processos sem instalar nada, use --pid=container:<id>:

docker run -it --rm --pid=container:meu-container ubuntu:latest bash

Isso permite visualizar todos os processos do container alvo com ps aux e inspecionar /proc.

No Kubernetes, use kubectl debug ou containers efêmeros (ephemeral containers) — recursos nativos que criam containers de depuração temporários no mesmo pod, sem modificar a definição original.

10 Dicas Finais

  1. Sempre use --rm em containers de depuração para não acumular containers parados.
  2. Documente os comandos usados em cada incidente para criar um playbook de depuração.
  3. Teste em staging antes de aplicar técnicas invasivas em produção.
  4. Considere a segurança: ferramentas como strace e tcpdump podem expor dados sensíveis.
  5. Automatize a coleta de informações com scripts que executam múltiplos comandos de diagnóstico simultaneamente.

Depurar containers requer uma combinação de conhecimento das ferramentas Docker, compreensão do sistema operacional e estratégias adaptadas ao ambiente. Com esses truques, você estará preparado para investigar desde problemas simples de conectividade até vazamentos de memória complexos.

Referências