Comando docker logs: 7 dicas para diagnosticar problemas em contêineres

Você executa docker logs payment-service e, ao pressionar Enter, milhares de linhas de INFO começam a rolar pela tela. O serviço de pagamentos acabou de cair em produção: em que parte desse fluxo está aquela mensagem de ERROR que pode salvar o diagnóstico?

Excesso de logs na tela, monitoramento em tempo real, filtro por intervalo e localização rápida de mensagens de erro são problemas mais difíceis de resolver do que parecem justamente nos momentos críticos. Este artigo apresenta 7 dicas práticas de docker logs, do básico ao avançado, para ajudar você a diagnosticar rapidamente problemas em contêineres.

Consulta básica de logs

1. A forma mais simples de consultar logs

Vamos começar pelo uso básico. Você certamente já viu este comando:

docker logs <nome-do-contêiner>
# Ou use o ID do contêiner
docker logs abc123def456

Esse comando envia ao terminal todos os logs gerados desde a inicialização do contêiner. Parece ótimo, mas, na prática, eles rolam pela tela como uma cachoeira e fica quase impossível enxergar alguma coisa.

Quando encontrei esse problema pela primeira vez, o contêiner já estava em execução havia três dias e acumulava dezenas de milhares de linhas. O terminal rolava sem parar; fiquei olhando por um bom tempo e nem consegui localizar um ERROR. Só depois descobri que, nesse cenário, não fazia sentido usar o comando sem nenhum filtro.

Quando vale a pena usar o comando básico?

Na verdade, há apenas duas situações:

• O contêiner acabou de iniciar e ainda tem poucos logs
• Você precisa exportar todos os logs para um arquivo de backup

Nos demais casos, evite. Há opções melhores.

2. Exibir as últimas N linhas

Esta é uma das opções mais úteis no dia a dia:

docker logs --tail 50 my-container

O parâmetro --tail mostra apenas as últimas N linhas. Costumo começar com 50 ou 100: é suficiente para perceber o problema sem se afogar em informação.

Cenário real:

Na semana passada, nosso serviço de API ficou lento de repente. Minha primeira reação foi executar:

docker logs --tail 100 api-server

Nas 100 linhas mais recentes, encontrei imediatamente um aviso de timeout na conexão com o banco de dados. O escopo do problema diminuiu na hora: não era o código, e sim algo no banco.

A ideia central é: consulte primeiro os logs mais recentes para entender a direção geral do problema. Se não encontrar nenhuma pista, aprofunde a investigação com outros métodos.

Railway - Plataforma de deploy moderna, sem ops complexas, no ar em minutos

Começar agora →Anúncio

Se você quer diagnosticar o problema, mas não sabe quantas linhas deve consultar, recomendo começar com 50. Se não bastar, passe para 100 e depois para 200. Aumentar aos poucos é muito mais eficiente do que exibir tudo logo de início.

Monitoramento em tempo real

3. Acompanhar o fluxo de logs em tempo real

Esta opção é especialmente útil durante uma depuração. Ela funciona como o comando tail -f do Linux e acompanha as atualizações do log em tempo real:

docker logs -f my-container

Com o parâmetro -f, abreviação de follow, os logs continuam sendo exibidos, e cada nova linha aparece imediatamente na tela.

Costumo usá-lo nestes cenários:

1. Monitorar a inicialização de um contêiner
   Depois de implantar um serviço, inicio o contêiner e acompanho os logs com -f. Se houver um erro no arquivo de configuração, ele aparece na hora, sem precisar esperar que o serviço pare para começar a investigar.

2. Capturar o problema enquanto ele é reproduzido
   Existe um bug que só aparece depois de uma ação específica? Primeiro deixo docker logs -f em execução e depois reproduzo a ação. Os logs são atualizados em tempo real e capturam o erro no momento em que ele acontece.

Há ainda uma combinação mais prática:

docker logs -f --tail 100 my-container

Assim, você vê as 100 linhas anteriores e continua acompanhando as novas. Ao iniciar o monitoramento, consegue entender o que acabou de acontecer e observar o que virá em seguida.

Isso me lembra um colega que gostava de usar -f para depurar problemas em contêineres. Ele ficou meia hora olhando para a tela sem receber uma única linha nova. Tinha esquecido que o contêiner já havia parado e, por isso, não produzia novos logs. Antes de usar -f, confirme se ele está em execução com docker ps.

Filtros precisos

4. Filtrar por intervalo de tempo

Este é um dos meus recursos favoritos. Imagine que o sistema de monitoramento avise que “o serviço apresentou um erro às 3h da madrugada”, mas você só veja o alerta pela manhã, depois de milhares de novas linhas. Como localizar rapidamente os logs daquele horário?

Use os parâmetros --since e --until:

# Exibe os logs posteriores a um horário específico
docker logs --since "2025-12-18T03:00:00" my-container

# Exibe os logs de um intervalo específico
docker logs --since "2025-12-18T03:00:00" --until "2025-12-18T04:00:00" my-container

O horário segue o padrão ISO 8601, mas você não precisa ficar preso a esse formato: o Docker também aceita durações relativas.

# Logs da última hora
docker logs --since 1h my-container

# Logs dos últimos 30 minutos
docker logs --since 30m my-container

# Logs das últimas 24 horas
docker logs --since 24h my-container

Caso real:

Certa vez, nosso serviço de pedidos caiu às 4h. Quando comecei a investigar às 9h, já havia cinco horas de logs acumulados. Executei diretamente:

docker logs --since "2025-12-18T03:30:00" --until "2025-12-18T04:30:00" order-service

Ao consultar apenas a hora anterior e posterior ao problema, encontrei imediatamente o stack trace de falta de memória. Se tivesse lido todos os logs, provavelmente levaria muito mais tempo.

5. Exibir carimbos de data e hora

Às vezes você encontra um ERROR, mas não sabe quando ele ocorreu e não consegue relacioná-lo aos dados do sistema de monitoramento. Nesse caso, adicione o carimbo de data e hora:

docker logs -t my-container

O parâmetro -t adiciona um carimbo de data e hora no início de cada linha, assim:

2025-12-18T10:23:45.123456789Z [INFO] Server started
2025-12-18T10:23:47.234567890Z [ERROR] Database connection failed

Dessa forma, você sabe exatamente quando cada registro foi gerado. Em geral, combino esse parâmetro com outros:

# Exibe os logs dos últimos 30 minutos com carimbos de data e hora
docker logs -t --since 30m my-container

# Acompanha os logs em tempo real com carimbos de data e hora
docker logs -f -t my-container

Os carimbos de data e hora são especialmente úteis ao analisar problemas de desempenho. Você consegue ver com precisão quanto tempo uma requisição levou desde a entrada até a conclusão e identificar qual etapa ficou lenta.

6. Filtrar palavras-chave com grep

Os logs estão cheios de INFO, mas você quer ver apenas ERROR? Use grep:

docker logs my-container | grep "ERROR"

O comando mostra somente as linhas que contêm “ERROR”. Mas há uma armadilha importante:

Às vezes o filtro com grep não funciona.

Quando isso aconteceu comigo pela primeira vez, fiquei confuso: os logs do contêiner claramente tinham ERROR, mas grep não encontrava nada. Depois descobri que o contêiner podia estar enviando os logs para stderr, o fluxo de erro padrão, em vez de stdout, o fluxo de saída padrão. O pipe | processa apenas stdout por padrão.

Vultr - Servidor cloud NVMe de alto desempenho, 32 locais globais, deploy Docker com um clique

Ver preços →Anúncio

A solução é redirecionar stderr para stdout:

docker logs my-container 2>&1 | grep "ERROR"

2>&1 redireciona stderr, o descritor de arquivo 2, para stdout, o descritor de arquivo 1. Assim, grep consegue capturar todos os logs.

Combinações ainda mais úteis:

# Exibe as 10 linhas anteriores e posteriores ao ERROR
docker logs my-container 2>&1 | grep -C 10 "ERROR"

# Pesquisa error sem diferenciar maiúsculas e minúsculas
docker logs my-container 2>&1 | grep -i "error"

# Localiza os 20 erros mais recentes
docker logs -t my-container 2>&1 | grep -i "error" | tail -20

O parâmetro -C 10 é especialmente útil porque mostra as 10 linhas anteriores e posteriores à correspondência. Muitas vezes, a linha de ERROR isolada não basta: você precisa do contexto para entender o fluxo completo do problema.

Técnicas avançadas

7. Localizar fisicamente o arquivo de log

Talvez você não saiba, mas os logs do contêiner ficam armazenados em um arquivo físico no host. Para descobrir onde ele está, use:

docker inspect --format='{{.LogPath}}' my-container

O resultado costuma ser:

/var/lib/docker/containers/abc123.../abc123...-json.log

Para que isso serve?

1. Consultar diretamente o arquivo de log
   Às vezes, docker logs sobrecarrega o Docker daemon, principalmente quando há muitos logs. Ler o arquivo diretamente pode ser mais rápido:

   sudo tail -f /var/lib/docker/containers/abc123.../abc123...-json.log

2. Fazer backup dos logs
   Precisa arquivá-los? Basta copiar o arquivo:

   sudo cp /var/lib/docker/containers/abc123.../abc123...-json.log ./backup/

3. Analisar com ferramentas mais avançadas
   Por exemplo, você pode abrir o arquivo no vim e aproveitar os recursos de busca do editor, que são mais flexíveis que grep.

Vale lembrar que esse arquivo usa o formato JSON: cada linha de log fica dentro de um objeto JSON, o que pode dificultar a leitura. Se você quer apenas ler texto simples, docker logs continua sendo mais conveniente.

Exportar logs para um arquivo:

Se quiser um backup em texto simples, use o redirecionamento:

docker logs my-container > container.log

O arquivo exportado será texto simples, facilitando a análise posterior ou o envio para outra pessoa.

Boas práticas para produção

8. Configurar a rotação de logs para evitar disco cheio

Sinceramente, esta é uma das configurações mais importantes e mais esquecidas em produção.

Um desastre real:

Já presenciei uma situação dolorosa. Um contêiner ficou em execução durante meses e o arquivo de log não parou de crescer, até ocupar todo o disco do host. Todos os contêineres do servidor caíram, o banco de dados não conseguia mais gravar e o site ficou fora do ar. Foram duas horas de investigação até descobrirmos que os logs haviam consumido todo o espaço.

Como evitar esse desastre?

Configure a rotação de logs. Adicione o seguinte ao arquivo /etc/docker/daemon.json:

{
  "log-driver": "json-file",
  "log-opts": {
    "max-size": "10m",
    "max-file": "3"
  }
}

Significado dos parâmetros:

• max-size: tamanho máximo de 10 MB para cada arquivo de log
• max-file: mantém no máximo 3 arquivos de log

Com essa configuração, os logs de cada contêiner ocupam no máximo 10 MB × 3 = 30 MB. Quando um arquivo chega a 10 MB, o Docker cria outro automaticamente. Depois de ultrapassar três arquivos, o mais antigo é excluído.

Como aplicar a configuração:

KiloClaw - OpenClaw gerenciado para empresas: orquestração de agentes IA e roteamento inteligente

Começar →Anúncio

Depois de editar daemon.json, reinicie o serviço do Docker:

sudo systemctl restart docker

Atenção: reiniciar o Docker também reinicia todos os contêineres. Em produção, escolha uma janela de manutenção adequada.

Configuração para um único contêiner:

Se você quer configurar a rotação apenas para um contêiner específico, informe as opções ao iniciá-lo:

docker run -d \
  --log-opt max-size=10m \
  --log-opt max-file=3 \
  my-image

Assim, os demais contêineres não são afetados.

9. Estratégia para gerenciar logs em produção

Depois de usar docker logs por algum tempo, você percebe um problema: com um volume muito grande de registros, o comando fica lento e pode até travar o terminal. Isso acontece porque docker logs pode gerar uma carga considerável no Docker daemon.

O equilíbrio em produção:

• Projetos pequenos (de 1 a 10 contêineres):

  • docker logs + rotação configurada costuma ser suficiente
  • É uma solução simples e direta, sem infraestrutura adicional

• Projetos médios e grandes (mais de 10 contêineres ou arquitetura de microsserviços):

  • É necessário adotar um sistema centralizado de logs
  • Solução comum: ELK (Elasticsearch + Logstash + Kibana)
  • Outras opções: Loki, Fluentd e Splunk

Por que projetos grandes não devem depender apenas de docker logs?

1. Desempenho: consultar logs de vários contêineres ao mesmo tempo sobrecarrega o Docker daemon
2. Agregação: em uma arquitetura de microsserviços, uma única requisição pode atravessar 10 serviços. Com os logs espalhados por 10 contêineres, como acompanhar toda a execução?
3. Consultas históricas: docker logs só mostra os logs do contêiner atual; depois que ele reinicia, os logs antigos desaparecem
4. Colaboração da equipe: não é realista exigir que operações, desenvolvimento e testes acessem o servidor para executar comandos

Minha recomendação:

• Está começando a aprender Docker? Dominar docker logs já é suficiente
• Projeto pessoal ou equipe pequena? Configure bem a rotação e use docker logs
• Mais de 10 contêineres em produção? Considere seriamente uma solução centralizada
• Arquitetura de microsserviços? Logs centralizados não são um luxo, mas uma necessidade

Conclusão

Depois de tudo isso, vamos voltar ao cenário das 3h da madrugada mencionado no início. Se eu passasse por ele agora, faria o seguinte:

1. Começaria com docker logs --tail 100 payment-service para consultar rapidamente os logs recentes
2. Se não encontrasse nenhuma pista, filtraria por intervalo: docker logs --since "2025-12-18T03:00:00" --until "2025-12-18T03:30:00" payment-service
3. Depois, combinaria carimbos de data e hora com grep: docker logs -t payment-service 2>&1 | grep -i "error" | tail -20

Três etapas e, em no máximo dois minutos, o problema estaria localizado.

Esse é o valor de saber usar docker logs: não se trata de memorizar todos os parâmetros, e sim de entender qual combinação se encaixa em cada cenário.

Por fim, vale reforçar: se seus contêineres estão em produção, configure a rotação de logs agora mesmo. Não espere o disco ficar cheio para se arrepender. São apenas algumas linhas de configuração, mas elas podem salvar o ambiente.

Cartão de referência rápida

# Consulta básica
docker logs <nome-do-contêiner>                    # Exibe todos os logs
docker logs --tail 50 <nome-do-contêiner>         # Exibe as últimas 50 linhas

# Monitoramento em tempo real
docker logs -f <nome-do-contêiner>                # Acompanha em tempo real
docker logs -f --tail 100 <nome-do-contêiner>     # Exibe as últimas 100 linhas e continua acompanhando

# Filtro por horário
docker logs --since 1h <nome-do-contêiner>        # Última hora
docker logs --since "2025-12-18T03:00:00" <nome-do-contêiner>  # Posteriores ao horário indicado

# Busca precisa
docker logs -t <nome-do-contêiner>                           # Exibe carimbos de data e hora
docker logs <nome-do-contêiner> 2>&1 | grep -i "error"      # Pesquisa erros
docker logs <nome-do-contêiner> 2>&1 | grep -C 10 "error"   # Pesquisa e exibe o contexto

# Técnicas avançadas
docker inspect --format='{{.LogPath}}' <nome-do-contêiner>   # Mostra a localização do arquivo de log
docker logs <nome-do-contêiner> > log.txt                   # Exporta os logs

Salve este cartão de referência. Na próxima vez que um contêiner apresentar um problema, basta consultá-lo.