Docker: Registro e Monitoramento de Logs

Última atualização: 2026-08-26

Um contêiner trava às 3 da manhã — logs e monitoramento são suas únicas ferramentas para identificar rapidamente a causa raiz.

1. O Que Você Vai Aprender

• Quatro Tipos de Drivers de Log e Seus Cenários Aplicáveis
• Dicas para Visualizar e Filtrar Logs em Tempo Real
• Métodos para Monitorar Recursos de Contêineres
• Estratégia de rotação de logs
• Abordagem para Coleta Centralizada de Logs

2. Uma História Real de uma Pessoa Engenheira de Operações

(1) Ponto de Dor: Nenhuma pista sobre o alerta OOM às 3 da manhã

Às 3 da manhã, um contêiner no ambiente de produção sofreu um pico repentino no uso de memória, causando um erro OOM. Charlie foi alertado e acordou, mas não sabia a causa — o arquivo de log tinha 2 GB, docker logs estava rolando rápido demais para encontrar a informação-chave e não havia dados históricos de monitoramento de recursos, então ele só podia supor.

(2) Soluções para Filtragem de Logs e Monitoramento de Recursos

Charlie usou a combinação de docker logs --since e grep para encontrar a requisição anormal em 30 segundos.

# Encontrar logs relacionados a OOM nas últimas 2 horas
docker logs --since 2h --tail 500 app 2>&1 | grep -i "oom\|memory\|error"

# Verificar histórico de uso de recursos
docker stats --no-stream

(3) Benefício: Identificar a causa raiz em 30 segundos

De 2 GB de logs, ele identificou o evento OOM e a requisição anormal em 30 segundos. Charlie então configurou rotação de logs e alertas Prometheus para que futuros alertas de madrugada incluíssem automaticamente a causa raiz.

3. Drivers de Log do Docker

(1) Quatro Tipos de Drivers de Log

graph LR
    CTN["Contêiner<br/>stdout/stderr"] --> DRV["Driver de Log"]
    DRV --> JSON["json-file<br/>Padrão, Arquivos Locais"]
    DRV --> JRN["journald<br/>Log do systemd"]
    DRV --> SYS["syslog<br/>Servidor de Log Remoto"]
    DRV --> GELF["gelf<br/>ELK/Loki"]

graph LR
    CTN["Contêiner<br/>stdout/stderr"] --> DRV["Driver de Log"]
    DRV --> JSON["json-file<br/>Padrão, Arquivos Locais"]
    DRV --> JRN["journald<br/>Log do systemd"]
    DRV --> SYS["syslog<br/>Servidor de Log Remoto"]
    DRV --> GELF["gelf<br/>ELK/Loki"]

(2) Configurar o driver de log

# Por contêiner: especificar driver de log na execução
docker run -d \
  --log-driver json-file \
  --log-opt max-size=10m \
  --log-opt max-file=3 \
  --name app myapp:1.0

// Global: /etc/docker/daemon.json
{
  "log-driver": "json-file",
  "log-opts": {
    "max-size": "10m",
    "max-file": "3"
  }
}

4. Uso Avançado de docker logs

▶ Exemplo: Filtro de tempo --since (Dificuldade: ⭐⭐)

# Mostrar logs das últimas 2 horas
docker logs --since 2h app

# Mostrar logs de um horário específico
docker logs --since "2024-01-15T03:00:00" app

# Mostrar logs entre dois timestamps
docker logs --since "2024-01-15T03:00:00" --until "2024-01-15T04:00:00" app

▶ Exemplo: Limite de linhas --tail (Dificuldade: ⭐)

# Mostrar últimas 100 linhas
docker logs --tail 100 app

# Acompanhar últimas 100 linhas em tempo real
docker logs -f --tail 100 app

▶ Exemplo: Monitoramento em tempo real com docker stats (Dificuldade: ⭐⭐)

# Estatísticas de recursos em tempo real para todos os contêineres
docker stats

# Snapshot único (sem streaming)
docker stats --no-stream

# Estatísticas para contêineres específicos
docker stats app db --no-stream

# Formato personalizado
docker stats --format "table {{.Name}}\t{{.CPUPerc}}\t{{.MemUsage}}"

NAME   CPU %   MEM USAGE / LIMIT
app    2.35%   150MiB / 512MiB
db     0.50%   85MiB / 256MiB

▶ Exemplo: Rastreamento de Eventos com Docker Events (Dificuldade: ⭐⭐)

# Transmitir eventos do daemon Docker
docker events

# Filtrar por tipo de evento
docker events --filter type=container

# Filtrar por evento específico
docker events --filter event=oom --filter event=die

# Filtrar por intervalo de tempo
docker events --since "2024-01-15T03:00:00" --until "2024-01-15T04:00:00"

2024-01-15T03:24:15Z container oom 67890... (name=app, image=myapp)
2024-01-15T03:24:15Z container die 67890... (exitCode=137, name=app)
2024-01-15T03:24:25Z container start 67890... (name=app, image=myapp)

5. Estratégia de Rotação de Logs

(1) Rotação de logs para arquivos JSON

▶ Exemplo: Configuração de Rotação de Logs (Dificuldade: ⭐⭐)

# Configurar rotação de logs na inicialização do contêiner
docker run -d \
  --log-driver json-file \
  --log-opt max-size=10m \
  --log-opt max-file=3 \
  --name app myapp:1.0

(1) Configuração de Logging no Compose

services:
  api:
    image: myapp:1.0
    logging:
      driver: json-file
      options:
        max-size: "10m"
        max-file: "3"

6. Solução de Coleta Centralizada de Logs

(1) Comparação das Três Opções

7. Exemplo Completo: Configurando Rotação de Logs e Monitoramento

# ============================================
# Passo a passo completo: Rotação de logs + monitoramento
# Abrange: rotação de logs, stats, events, diagnóstico OOM
# ============================================

# 1. Iniciar app com rotação de logs
docker run -d \
  --name app \
  --log-driver json-file \
  --log-opt max-size=10m \
  --log-opt max-file=3 \
  --memory=256m \
  --restart=on-failure:5 \
  -p 5000:5000 \
  myapp:1.0

# 2. Monitorar uso de recursos
docker stats app --no-stream

# 3. Simular: acionar OOM excedendo a memória
docker exec app python -c "
import numpy as np
x = np.zeros((50000, 50000))  # Tentar alocar ~20GB
"

# 4. Capturar o evento OOM
docker events --filter event=oom --since 1m

# 5. Encontrar OOM nos logs com timestamp
docker logs --since 5m --tail 200 app 2>&1 | grep -i "oom\|memory\|killed"

# 6. Verificar código de saída
docker inspect app --format='ExitCode: {{.State.ExitCode}}, OOMKilled: {{.State.OOMKilled}}'

# 7. Exportar últimas 1000 linhas para análise
docker logs --tail 1000 app > app-debug.log 2>&1

# 8. Verificar se a rotação de logs está funcionando
ls -la /var/lib/docker/containers/$(docker inspect app --format='{{.Id}}')/

❓ Perguntas Frequentes

P: Um arquivo de log muito grande pode afetar o disco? R: Sim. Por padrão, o driver json-file não faz rotação de logs, então o arquivo de log cresce indefinidamente. Já vi casos em ambientes de produção onde o arquivo de log de um único contêiner atingiu 50 GB. Você deve configurar --log-opt max-size=10m --log-opt max-file=3 na inicialização ou definir a rotação padrão globalmente no daemon.json.

P: Como configuro a rotação de logs? R: Existem duas maneiras: ① Use --log-opt max-size=10m --log-opt max-file=3 ao iniciar o contêiner; ② Configure "log-opts": {"max-size": "10m", "max-file": "3"} na configuração global /etc/docker/daemon.json. Recomendamos usar a configuração global em um ambiente de produção para evitar omissões.

P: Como posso coletar centralizadamente logs de vários contêineres? R: Use o driver de log gelf ou syslog para enviar todos os logs dos contêineres para uma plataforma centralizada ELK/Loki. Uma abordagem mais recomendada: Mantenha o driver json-file e use Filebeat/Promtail para coletar os arquivos de log; dessa forma, docker logs ainda funcionará.

P: Os logs ainda estão lá após o contêiner reiniciar? R: Sim. Reiniciar o contêiner não exclui os arquivos de log. No entanto, docker rm exclui os logs quando o contêiner é excluído. Para persistir logs: ① Grave-os em arquivos da aplicação e monte como volume; ② Use uma plataforma de logging centralizada para coleta em tempo real.

P: A memória mostrada pelo docker stats se refere ao contêiner ou ao processo? R: Ao contêiner. docker stats exibe o uso total de memória de todos os processos dentro do cgroup do contêiner. LIMIT é o limite superior definido por --memory. Se --memory não estiver definido, LIMIT exibe a memória total do host.

📖 Resumo

• Quatro drivers de log: json-file (padrão), journald, syslog e gelf — a rotação de logs deve ser configurada em ambientes de produção
• Filtragem Avançada com docker logs: Filtro de Tempo --since/--until, Limite de Linhas --tail, Rastreamento em Tempo Real -f
• docker stats Monitoramento em tempo real de CPU, memória e I/O; --no-stream Snapshot único
• docker events Rastreia eventos do ciclo de vida do contêiner, incluindo eventos críticos como OOM, die e restart
• Rotação de Logs: max-size=10m max-file=3 Evita que os logs preencham o disco
• Logging centralizado: ELK (nível empresarial) ou Loki+Grafana (leve/nativo da nuvem)

📝 Exercícios

1. Exercício Básico (Dificuldade: ⭐): Inicie o contêiner e configure --log-opt max-size=5m --log-opt max-file=2, depois use docker logs para visualizar os logs e verifique se a rotação entrou em vigor.
2. Exercício Avançado (Dificuldade: ⭐⭐): Use docker stats para monitorar um contêiner durante um teste de carga e registre o pico de uso de CPU e memória.
3. Desafio (Dificuldade: ⭐⭐⭐): Use docker events para capturar um evento OOM de um contêiner e combine com docker logs --since para identificar a requisição ou operação que acionou o OOM.

Equipe Técnica Web-Tutorial

Uma plataforma de tutoriais mantida por diversos desenvolvedores. Cada tutorial é escrito e revisado por profissionais da área correspondente. Trabalhamos para manter nosso conteúdo preciso e confiável — se encontrar algum problema, avise-nos.

Sobre Nós