Logs do Kubernetes: tipos, comandos e 6 boas práticas

O que é logging no Kubernetes?

No Kubernetes, os logs são o principal meio de observar o comportamento das aplicações e investigar problemas no cluster. Como os pods são efêmeros, o Kubernetes gerencia os logs capturando os streams stdout e stderr dos containers e armazenando-os como arquivos temporários no node.

Arquitetura de logging:

O Kubernetes não oferece uma solução nativa de armazenamento persistente para logs; ele se apoia em três padrões arquiteturais principais:

• Logging no nível do node: o container runtime captura a saída padrão e a armazena em /var/log/pods/ no node host.
• Containers sidecar para encaminhamento de logs: um container secundário dentro do pod coleta os logs da aplicação e os envia para o próprio stdout ou diretamente para um backend de logging.
• Logging no nível do cluster: um agente especializado (como Fluentd, Fluent Bit ou Filebeat) roda como DaemonSet em cada node. Ele coleta os arquivos de log locais e os encaminha para um sistema de armazenamento centralizado, como Elasticsearch, Grafana Loki ou serviços específicos de cada nuvem, como AWS CloudWatch, Google Cloud Logging (usado pelo GKE) ou Azure Monitor.

Tipos de logs do Kubernetes — cada um detalhado abaixo:

• Logs de aplicação: o tipo mais comum, gerado pelo seu código em execução nos pods.
• Logs de componentes do sistema: gerados por serviços essenciais do Kubernetes, como o API server, o scheduler e o kubelet.
• Logs de auditoria: registros de cada chamada feita ao API server do Kubernetes, usados principalmente para segurança e compliance.
• Eventos: tecnicamente não são logs, mas registros com timestamp de mudanças de estado no cluster (por exemplo, falha na inicialização de um pod), visualizados com kubectl get events.

Neste artigo:

• Entendendo a arquitetura de logging do Kubernetes
• Tipos de logs do Kubernetes
• Comandos essenciais do kubectl logs
• Casos de uso comuns de logging no Kubernetes
• Boas práticas de logging no Kubernetes

Entendendo a arquitetura de logging do Kubernetes

Logging no nível do node

O logging no nível do node no Kubernetes consiste em capturar logs na máquina host, onde o container runtime armazena os logs de todos os containers em execução naquele node. Por padrão, os nodes do Kubernetes usam o mecanismo de logging do container runtime, como o driver de logging JSON do Docker, que grava os streams stdout e stderr de cada container em arquivos de log em um local padrão, por exemplo, /var/log/containers/.

Vantagens:

• Essa abordagem garante que os logs sejam preservados no node mesmo que um container tenha vida curta ou trave.
• Oferece uma fonte local para troubleshooting.

Limitações:

• Não é recomendável depender apenas do logging no nível do node.
• Quando os nodes são deletados ou quando os logs sofrem rotação ou são apagados, é possível perder dados.
• Os logs no nível do node também ficam isolados, o que dificulta correlacionar eventos entre nodes ou agregar logs para análise centralizada.
• O logging no nível do node não oferece visibilidade além de um único node — ele não responde a perguntas sobre a saúde dos workloads em todo o cluster, sobre tendências de uso de recursos ao longo do tempo ou sobre a relação entre um evento de log e um pico de CPU em outro node.

Em ambientes de produção, as organizações costumam complementar o logging no nível do node com soluções que abrangem todo o cluster e que coletam e exportam logs para sistemas externos para retenção, busca e análise.

Containers sidecar para encaminhamento de logs

Containers sidecar são um padrão arquitetural do Kubernetes em que um container adicional roda ao lado do container principal da aplicação dentro do mesmo pod. No contexto de logging, o papel do sidecar é especificamente encaminhar logs: ele lê os arquivos de log ou streams gerados pelo container principal da aplicação e os envia para um backend de logging externo. Isso é diferente de simplesmente gravar logs a partir de um container sidecar como você faria com qualquer outro container. Esse design separa a lógica de logging do código da aplicação e permite que as equipes padronizem a coleta de logs entre workloads.

Vantagens:

• Usar containers sidecar para logging oferece flexibilidade e consistência.
• O sidecar pode cuidar de tarefas como rotação de logs, formatação, enriquecimento com metadados e transmissão segura para o armazenamento centralizado de logs.
• Essa abordagem é útil quando as aplicações não dão suporte nativo a logging estruturado ou quando os logs precisam ser enviados para múltiplos destinos.

Limitações:

• Introduz overhead de recursos e complexidade operacional.
• Cada pod precisa ser configurado e gerenciar o ciclo de vida de seus containers sidecar.
• O padrão sidecar resolve a coleta de logs, não a análise. Mesmo com os logs sendo encaminhados perfeitamente, correlacionar o que aconteceu em um container com eventos no nível do cluster — decisões de scheduling, pressão sobre recursos, condições do node — ainda exige ferramentas adicionais.

Logging no nível do cluster

O logging no nível do cluster agrega logs de todos os nodes, pods e componentes de um cluster Kubernetes e os exporta para um sistema centralizado. Normalmente isso é feito implantando agentes de coleta de logs, como Fluentd, Logstash ou Filebeat, como DaemonSets, que rodam em cada node e coletam logs dos arquivos de log dos containers ou do sistema journald. Os logs coletados são então encaminhados para plataformas externas, como Elasticsearch, Splunk, ou serviços de logging em nuvem para armazenamento, indexação e consulta.

Esse é o padrão que os serviços gerenciados de Kubernetes implementam por default. No GKE, o Google Cloud Logging (antigo Stackdriver) já vem habilitado, com a implantação de um agente baseado em Fluent Bit como DaemonSet que envia logs para o Cloud Logging. No EKS, a AWS oferece uma configuração semelhante por meio do add-on AWS for Fluent Bit, que encaminha para o CloudWatch Logs. Se você está rodando em um serviço gerenciado de Kubernetes, é quase certo que já está usando logging no nível do cluster — a questão é o quão bem você está aproveitando isso.

Vantagens:

• O logging no nível do cluster resolve os desafios de nodes e pods efêmeros, garantindo que os logs sejam preservados mesmo quando os workloads são reagendados ou a infraestrutura muda.
• Permite busca, correlação e análise entre componentes do cluster, facilitando o monitoramento da saúde das aplicações, a depuração de incidentes e o atendimento a requisitos de compliance.
• Implementar o logging no nível do cluster é considerado boa prática para ambientes Kubernetes de produção, pois fornece uma base escalável para observabilidade.

Limitações:

• Mesmo com o logging no nível do cluster em funcionamento, os logs sozinhos não contam a história toda. Eles capturam o que uma aplicação reportou, mas não por que um pod foi reagendado, se um node estava sob pressão de memória ou como o consumo de recursos vem evoluindo ao longo do tempo. Correlacionar eventos de log com métricas de infraestrutura geralmente exige ferramentas adicionais além do que um pipeline de agregação de logs oferece.

Tipos de logs do Kubernetes

1. Logs de aplicação

Os logs de aplicação são gerados pelo código em execução dentro dos containers. Esses logs capturam a saída dos processos da aplicação, como mensagens informativas, erros, avisos e mensagens de debug. Os desenvolvedores se apoiam nos logs de aplicação para entender o comportamento em tempo de execução, rastrear requisições e diagnosticar problemas relacionados à lógica de negócio ou a dependências de terceiros. Os logs de aplicação normalmente são gravados em stdout e stderr, o que os torna acessíveis aos mecanismos de logging do Kubernetes.

Considerações:

• Gerenciar logs de aplicação no Kubernetes traz desafios por causa da natureza dinâmica dos containers. Se os logs não forem coletados e persistidos fora do container, informações podem se perder quando os pods são encerrados ou reagendados.
• As organizações devem emitir logs em formato estruturado, como JSON, e evitar gravar arquivos de log dentro dos containers.
• Soluções de logging centralizadas conseguem reter e pesquisar logs para troubleshooting e monitoramento.
• Os logs de aplicação revelam o que seu código fez — mas não por que o Kubernetes encerrou o pod, se o node estava sob pressão de recursos ou o que mudou no cluster no mesmo momento. Para análise de causa raiz, os logs de aplicação são um ponto de partida, não o quadro completo.

2. Logs de componentes do sistema

Os logs de componentes do sistema são produzidos pela infraestrutura central de um cluster Kubernetes. Isso inclui logs do kubelet, kube-apiserver, kube-controller-manager, kube-scheduler e do container runtime. Esses logs dão visibilidade sobre a operação do control plane do Kubernetes e dos agentes do node, capturando eventos como decisões de scheduling, health checks, tentativas de autenticação e condições de erro dentro da plataforma.

Considerações:

• Acessar e analisar os logs de componentes do sistema é fundamental para operadores e administradores de cluster.
• Esses logs costumam ser armazenados no sistema de arquivos do host ou acessados via systemd journald, dependendo da configuração do cluster.
• Centralizar os logs de componentes do sistema junto com os logs de aplicação ajuda a correlacionar eventos no nível da infraestrutura com problemas de aplicação, viabilizando análise de causa raiz e monitoramento proativo do ambiente Kubernetes.
• Em serviços gerenciados como GKE e EKS, a maioria dos logs dos componentes do control plane está disponível na plataforma de logging do provedor de nuvem — o GKE expõe os logs do kube-apiserver, kube-scheduler e controller-manager diretamente no Cloud Logging. Isso elimina a preocupação com o acesso direto ao sistema de arquivos, mas não elimina a necessidade de monitorar e consultar esses logs ativamente.

3. Logs de auditoria

Os logs de auditoria no Kubernetes registram todas as requisições ao API server, capturando detalhes sobre quem executou qual ação, quando e de onde. Esses logs dão suporte a investigações de segurança, compliance e forenses, pois fornecem uma trilha à prova de adulteração da atividade de usuários e do sistema. O logging de auditoria é configurável no Kubernetes, permitindo que administradores controlem quais eventos são registrados e em que extensão, com base em políticas que definem a granularidade e a retenção dos dados de auditoria.

Considerações:

• Os logs de auditoria diferem dos logs de aplicação e do sistema por focarem em interações com a API e eventos de controle de acesso.
• Eles ajudam as organizações a detectar acessos não autorizados, monitorar operações sensíveis e comprovar compliance regulatório.
• Armazenar os logs de auditoria em um storage seguro e imutável e integrá-los a plataformas SIEM ou de analytics de segurança são práticas recomendadas para manter a segurança em ambientes Kubernetes.
• No GKE, os logs de auditoria são gerenciados via Cloud Audit Logs e habilitados por padrão para atividades administrativas. No EKS, o CloudTrail captura a atividade do API server. Nos dois casos, o provedor cuida da coleta — mas análise, alertas e política de retenção ainda exigem configuração deliberada.

Eventos

Os eventos do Kubernetes são registros com timestamp de ocorrências relevantes dentro do cluster, como criação de pods, falhas de scheduling, reinicializações ou violações de quota de recursos. Os eventos não são logs tradicionais, mas funcionam como notificações que ajudam os usuários a entender transições de estado e mudanças no ciclo de vida dos objetos do Kubernetes. Os eventos podem ser visualizados com kubectl get events e são úteis para debug em tempo real e visibilidade operacional.

Considerações:

• Os eventos são efêmeros e normalmente retidos por um curto período no API server do Kubernetes; o padrão é uma hora.
• Embora forneçam contexto para troubleshooting, os eventos não devem ser usados como única fonte de informação para auditoria ou diagnóstico.
• Para uma visibilidade mais ampla, os eventos devem ser coletados e exportados para sistemas externos de monitoramento ou logging, onde podem ser correlacionados com logs de aplicação e do sistema.

Comandos essenciais do kubectl logs

O comando kubectl logs é a ferramenta padrão para obter logs de containers a partir do seu terminal.

Ver logs de pods

O comando kubectl logs é a forma principal de visualizar logs de um pod no Kubernetes. Ele recupera logs dos streams stdout e stderr do container, permitindo que operadores e desenvolvedores inspecionem o comportamento da aplicação pela linha de comando. O uso mais simples é:

kubectl logs <pod-name>

Esse comando exibe os logs do container padrão no pod especificado. Se o pod tiver apenas um container, o Kubernetes o seleciona automaticamente. Visualizar logs de pods é útil para investigar erros de aplicação, falhas de inicialização ou comportamentos inesperados sem acesso direto ao node que hospeda o container.

Acompanhar/transmitir logs em tempo real

O Kubernetes suporta streaming de logs em tempo real usando a flag -f ou --follow. O comportamento é parecido com o do comando tail -f do Linux e exibe continuamente as novas entradas de log à medida que o container as gera.

kubectl logs -f <pod-name>

O streaming de logs é útil durante sessões de depuração ou no monitoramento de deployments e processos de inicialização de aplicações. Ele permite que operadores observem eventos ao vivo, detectem falhas e verifiquem se as aplicações estão funcionando corretamente após mudanças de configuração ou código.

Logs de um container específico

Quando um pod tem múltiplos containers, o Kubernetes exige o nome do container para identificar quais logs exibir. Isso é comum em pods que usam containers sidecar para logging, proxies ou agentes de monitoramento.

kubectl logs <pod-name> -c <container-name>

A flag -c especifica o container alvo dentro do pod. Sem essa opção, o Kubernetes pode retornar um erro se houver múltiplos containers. Esse comando ajuda a isolar logs de um componente específico em arquiteturas de pods com múltiplos containers.

Logs de um pod que travou/anterior

O Kubernetes consegue recuperar logs de um container encerrado anteriormente usando a flag --previous. Isso é útil quando containers travam e reiniciam antes que os administradores consigam inspecionar os logs originais.

kubectl logs --previous <pod-name>

Para pods com múltiplos containers, o nome do container também pode ser especificado com -c. Acessar logs anteriores ajuda a diagnosticar crash loops, falhas de inicialização e erros transitórios da aplicação que podem não aparecer na instância atual do container.

Limitar a saída

Arquivos de log grandes podem ser difíceis de analisar, então o Kubernetes oferece opções para limitar o volume de saída retornado. A flag --tail exibe apenas as linhas mais recentes do log.

kubectl logs --tail=100 <pod-name>

Esse comando retorna as últimas 100 linhas de logs, ajudando os usuários a focar em eventos recentes sem precisar rolar por uma saída excessiva.

Filtrar por tempo

O Kubernetes permite filtrar logs por tempo usando as flags --since e --since-time. Essas opções ajudam a restringir a saída de logs a uma janela de tempo relevante durante investigações de incidentes.

kubectl logs --since=1h <pod-name>

O exemplo acima retorna os logs gerados na última hora. O Kubernetes também suporta timestamps exatos:

kubectl logs --since-time=2026-05-28T10:00:00Z <pod-name>

A filtragem por tempo é útil para correlacionar logs com deployments, indisponibilidades ou alertas.