PerfectScale

Kubernetes Events: como visualizar, filtrar e depurar

Esta página também está disponível em English, Deutsch, Español, Français, Italiano e 日本語.

By Josh Palmer Jun 11, 202613 min read

O que são Kubernetes Events?

Resumo: Kubernetes Events são recursos de API efêmeros e em tempo real, gerados sempre que ocorre uma mudança de estado, erro ou atividade relevante no seu cluster. Eles ajudam a depurar problemas e auditar a saúde do cluster. Os events registram detalhes como o que aconteceu, qual objeto foi afetado, o momento da ocorrência e uma breve descrição em linguagem natural.

Principais características:

Tipos: geralmente classificados como Normal (mudanças padrão, do dia a dia) ou Warning (indicando falhas como back-off loops ou problemas de scheduling).
Retenção: os events são efêmeros. Por padrão, ficam armazenados no etcd por até uma hora antes de serem removidos pelo garbage collector.
Atributos principais: cada event traz Last Seen, Type, Reason, Object (por exemplo, Pod/web-server) e um Message detalhando a transição de estado.

Como visualizar events:

Use o comando nativo kubectl events para inspecionar e acompanhar events direto do terminal:

Ver todos os events recentes no namespace padrão: kubectl events
Ver events em todos os namespaces: kubectl events --all-namespaces
Acompanhar events em tempo real de um recurso específico: kubectl events --for pod/<pod-name> --watch
Ver events recentes em formato YAML: kubectl events -o yaml

Este artigo faz parte de uma série sobre troubleshooting no Kubernetes.

Neste artigo:

Principais características dos Kubernetes Events
Kubernetes Events vs. logs vs. métricas
Como visualizar Kubernetes Events
Como filtrar Kubernetes Events
Tipos e razões comuns de Kubernetes Events
Troubleshooting com Kubernetes Events
Boas práticas para usar Kubernetes Events

Principais características dos Kubernetes Events

1. Tipos

Os Kubernetes Events são classificados em dois tipos principais: normal e warning:

Events normais sinalizam operações bem-sucedidas ou esperadas, como a criação de um pod ou o scheduling bem-sucedido pelo control plane. São informativos e ajudam o usuário a acompanhar o funcionamento normal dos recursos.
Events de warning apontam condições inesperadas ou problemáticas, como falhas de scheduling ou erros ao baixar imagens. Esses warnings são essenciais para identificar e reagir rápido a problemas antes que virem quedas maiores ou interrupções de serviço.

Os dois tipos servem a propósitos distintos, mas são igualmente importantes para a observabilidade do cluster. Events normais permitem confirmar que os recursos estão se comportando conforme o esperado, enquanto events de warning funcionam como um alerta antecipado para erros ou configurações incorretas.

2. Retenção

Os Kubernetes Events ficam armazenados no datastore etcd do cluster, mas não são retidos indefinidamente. Por padrão, ficam guardados por uma hora, mas esse período pode ser ajustado nas configurações do API server.

Essa janela curta foi pensada para minimizar o impacto no desempenho do cluster e evitar que o etcd fique sobrecarregado com dados de events transitórios ou repetitivos. Por outro lado, isso exige que os operadores ajam rápido caso queiram analisar ou exportar events para uma investigação mais aprofundada.

Como a retenção é limitada, não é recomendável depender só do armazenamento interno do cluster para auditorias de longo prazo ou análises post-mortem. Em ambientes que precisam de um histórico maior, a boa prática é exportar os events para um sistema externo de logging ou monitoramento.

3. Atributos principais

Cada Kubernetes Event traz vários atributos que dão contexto sobre o que aconteceu e onde. Entre os principais estão:

O objeto envolvido (como um Pod ou Node)
O tipo do event (Normal ou Warning)
Um código de razão que resume a causa
Uma mensagem em linguagem natural
Timestamps de quando o event ocorreu pela primeira e pela última vez

Esses atributos estruturados facilitam a filtragem, a busca e a correlação com outros dados de observabilidade. Entendê-los é fundamental para um troubleshooting eficaz. Por exemplo, os campos reason e message costumam dar pistas imediatas sobre o problema, enquanto os timestamps ajudam a determinar a sequência dos events relacionados. Já a referência ao objeto envolvido permite investigar o recurso afetado em detalhes.

Kubernetes Events vs. logs vs. métricas

Kubernetes Events, logs e métricas têm propósitos diferentes na observabilidade do cluster:

Events capturam mudanças de estado de alto nível e ações relevantes nos recursos do Kubernetes, como o scheduling ou falhas de Pod.
Logs trazem registros detalhados e com timestamp da atividade da aplicação ou do sistema, dando visibilidade profunda do que acontece dentro dos containers ou dos próprios componentes do Kubernetes.
Métricas são medições numéricas coletadas ao longo do tempo, como uso de CPU ou consumo de memória, usadas para monitorar tendências e disparar alertas.

Os events são úteis para rastrear o ciclo de vida dos recursos do cluster e identificar a causa de mudanças repentinas; os logs se encaixam melhor para depurar o comportamento da aplicação e diagnosticar problemas complexos. As métricas permitem acompanhar a saúde e o desempenho dos recursos em escala, dando suporte ao planejamento de capacidade e ao autoscaling.

Como visualizar Kubernetes Events

O Kubernetes oferece várias formas de visualizar events direto na linha de comando, com o kubectl. O método mais comum é o kubectl get events, que retorna a lista de events do namespace atual. A saída inclui detalhes como o tipo do event, a razão, o objeto envolvido e a mensagem.

Para ver events em todos os namespaces, basta adicionar a flag --all-namespaces.

kubectl get events

kubectl get events --all-namespaces

Como os events são sensíveis ao tempo, ordená-los por timestamp costuma ser útil no troubleshooting. O Kubernetes permite ordenar pelo horário de criação com a opção --sort-by. Isso ajuda a entender a sequência de ações que ocorreram antes de uma falha ou problema no deploy.

kubectl get events --sort-by=.metadata.creationTimestamp

Também dá para inspecionar events relacionados a um recurso específico com o comando kubectl describe. Ao descrever um Pod, por exemplo, você vê os detalhes do recurso junto com uma seção dedicada a Events no final. Essa é uma das formas mais rápidas de identificar problemas como falhas de scheduling, crashes de container ou erros ao baixar imagens.

kubectl describe pod my-pod

Em ambientes de produção, os events costumam ser integrados a plataformas centralizadas de observabilidade, como Elasticsearch, Loki ou ferramentas de monitoramento nativo da nuvem. Isso permite retenção mais longa, buscas avançadas e correlação com logs e métricas, tornando o troubleshooting muito mais eficiente em escala.

Como filtrar Kubernetes Events

Filtrar Kubernetes Events ajuda a focar nas informações mais relevantes durante o troubleshooting. Como os clusters podem gerar grandes volumes de events, filtrar por namespace, objeto, tipo ou razão facilita identificar problemas rapidamente.

1. A abordagem mais simples é limitar os resultados a um namespace específico.

kubectl get events -n production

2. Os field selectors oferecem filtragem mais avançada. Você pode filtrar events pelo nome do objeto envolvido, pelo kind, pela razão ou pelo tipo do event. O comando a seguir, por exemplo, mostra só events de Warning, que costumam estar associados a falhas ou condições anormais.

kubectl get events --field-selector type=Warning

3. Para ver events relacionados a um pod específico, basta filtrar pelo nome do objeto.

kubectl get events --field-selector involvedObject.name=my-pod

Filtrar por razão também é útil ao diagnosticar problemas recorrentes. Dá para buscar, por exemplo, falhas de scheduling em todo o cluster.

kubectl get events --field-selector reason=FailedScheduling

4. Os Kubernetes Events também podem ser exibidos em streaming em tempo real com a flag --watch. Isso é valioso durante deploys ou respostas a incidentes, já que mostra continuamente os novos events à medida que acontecem.

kubectl get events --watch

Para workflows mais avançados, os events costumam ser exportados para plataformas de monitoramento e logging, onde dá para aplicar consultas complexas, dashboards e alertas. Isso permite que as equipes automatizem a detecção de incidentes e correlacionem events com logs e métricas para uma análise de causa raiz mais ágil.

Tipos e razões comuns de Kubernetes Events

Events normais

Os events normais representam operações esperadas ou bem-sucedidas no cluster Kubernetes. Alguns exemplos: criação de pods, pulls de imagem bem-sucedidos ou nodes entrando no cluster. Eles confirmam que o control plane e os recursos estão funcionando como esperado. Ao revisar events normais, dá para verificar se fluxos como deploys ou autoscaling estão progredindo sem erros e se o cluster está rodando tranquilo.

Importância: Apesar de informativos, os events normais também ajudam no troubleshooting e na auditoria. Ao investigar um problema, confirmar a presença ou ausência de events normais ajuda a apontar onde os processos podem ter saído do caminho esperado. Por exemplo, a ausência de um event "Scheduled" durante a criação de um pod pode indicar um problema de scheduling, mesmo que nenhum warning tenha sido gerado.

Events de warning

Os events de warning indicam problemas ou condições inesperadas no cluster Kubernetes. Sinalizam questões como falhas de scheduling, erros ao baixar imagens ou violações de restrição de recursos. São gerados quando o control plane ou os componentes subjacentes encontram situações que exigem atenção, mas que não levam, necessariamente, a uma falha imediata do recurso.

Importância: Monitorar events de warning é fundamental para uma gestão proativa do cluster. Como esses events evidenciam desvios da operação normal, costumam ser o primeiro sinal de configurações incorretas, escassez de recursos ou problemas de infraestrutura.

Troubleshooting com Kubernetes Events

1. Pod travado em Pending

Um pod que fica preso no estado Pending geralmente indica que o Kubernetes não consegue colocá-lo em um node ou concluir uma das etapas de inicialização necessárias antes da partida. Os events costumam ser o caminho mais rápido para identificar a causa raiz, já que trazem feedback direto do scheduler e do kubelet. Entre as causas comuns estão CPU ou memória insuficientes, PersistentVolumeClaims ausentes, taints nos nodes ou regras de affinity não atendidas.

Para inspecionar os events relacionados ao pod, use:

kubectl describe pod my-pod

Na seção Events, o Kubernetes pode exibir mensagens como FailedScheduling com detalhes explicando por que nenhum Node adequado foi encontrado. Um event pode indicar, por exemplo, que os nodes não têm recursos disponíveis ou que taints estão impedindo o scheduling. Essas mensagens direcionam o troubleshooting rapidamente, sem exigir uma análise profunda dos logs do scheduler.

Outra abordagem útil é filtrar events de scheduling em todo o cluster:

kubectl get events --field-selector reason=FailedScheduling

Ao revisar esses events, dá para entender se o problema está isolado em um único workload ou se afeta vários pods do cluster. Resolver Pods em Pending costuma envolver escalar os recursos do cluster, ajustar requests, corrigir dependências de armazenamento ou atualizar restrições de scheduling.

2. ImagePullBackOff ou ErrImagePull

Os events ImagePullBackOff e ErrImagePull ocorrem quando o Kubernetes não consegue baixar uma imagem de container de um registry. Em geral, isso acontece por causa de nomes de imagem incorretos, tags ausentes, falhas de autenticação ou problemas de conectividade. Os events trazem mensagens detalhadas explicando por que o pull falhou, sendo essenciais para diagnosticar problemas de deploy.

A forma mais rápida de investigar é descrevendo o Pod afetado:

kubectl describe pod my-pod

A seção Events costuma trazer mensagens como Failed to pull image ou Back-off pulling image. Elas podem revelar erros como referências de imagem inválidas, acesso negado ao registry ou credenciais ausentes. Se o registry exigir autenticação, o Kubernetes também pode indicar que o image pull secret configurado é inválido ou está indisponível.

Verifique o nome e a tag da imagem na especificação do pod, confirme se o registry está acessível e garanta que os secrets necessários existem no namespace correto. Uma vez corrigido o problema, o Kubernetes tenta automaticamente baixar a imagem de novo e inicia o container com sucesso.

3. CrashLoopBackOff

Um event CrashLoopBackOff indica que um container inicia com sucesso, mas trava repetidamente logo em seguida. O Kubernetes continua tentando reiniciá-lo, aumentando o intervalo entre as tentativas a cada falha. Em geral, isso é causado por erros na aplicação, configuração inválida, dependências ausentes ou falhas nos health checks.

Os events ajudam a identificar o padrão de reinicialização e as falhas associadas:

kubectl describe pod my-pod

A saída pode mostrar events como Back-off restarting failed container. Eles revelam o comportamento de reinicialização, mas a causa detalhada do crash costuma estar nos logs do container.

Por isso, é comum combinar a análise dos events com a inspeção dos logs:

kubectl logs my-pod

Events frequentes de reinicialização também podem apontar para falhas em liveness probes ou esgotamento de recursos, como out-of-memory kills. Nesses casos, vale revisar as configurações das probes e os limits de recursos do container.

4. FailedScheduling

Os events de FailedScheduling ocorrem quando o scheduler do Kubernetes não consegue atribuir um pod a nenhum node disponível. Estão entre os warning events mais comuns em clusters de produção e normalmente indicam escassez de recursos ou regras de scheduling restritivas. O scheduler gera mensagens detalhadas descrevendo por que a alocação falhou.

Para visualizar events relacionados ao scheduling:

kubectl get events --field-selector reason=FailedScheduling

As mensagens típicas mencionam CPU ou memória insuficientes, incompatibilidades de node affinity, conflitos de taints ou restrições de topologia de volume. Um event pode informar, por exemplo, que nenhum node atende aos requests do pod ou que todos estão marcados com taints que o pod não tolera.

Entender a mensagem do event é fundamental, porque FailedScheduling é um sintoma, não a causa raiz em si. Resolver o problema pode envolver adicionar capacidade ao cluster, ajustar requests, atualizar regras de affinity ou configurar tolerations corretamente. Como problemas de scheduling podem afetar muitos workloads ao mesmo tempo, monitorar esses events ajuda a detectar cedo questões de capacidade ou configuração em todo o cluster.

Boas práticas para usar Kubernetes Events

A seguir, algumas práticas relacionadas a events que valem a pena considerar ao usar o Kubernetes.

1. Consulte os events logo no início do troubleshooting

Os Kubernetes Events devem ser um dos primeiros lugares a checar quando você diagnostica problemas de cluster ou de aplicação. Eles dão visibilidade sobre mudanças de estado recentes, falhas e ações do control plane.

Comandos como kubectl describe ou kubectl get events --sort-by=.metadata.creationTimestamp podem expor falhas de scheduling, reinicializações de container ou problemas ao baixar imagens. Revisar os events cedo ajuda a identificar se o problema vem da infraestrutura Kubernetes, da configuração do workload ou da própria aplicação.

Como são cronológicos, os events ajudam a reconstruir a sequência de ações que precederam uma falha. Isso é útil durante deploys, rollouts ou respostas a incidentes.

2. Combine events com logs e métricas

Os events dão contexto, mas ficam ainda mais úteis quando usados em conjunto com logs e métricas. Os events explicam o que aconteceu no nível dos recursos do Kubernetes, enquanto os logs revelam o comportamento detalhado da aplicação ou dos componentes. As métricas acrescentam dados de desempenho e utilização de recursos ao longo do tempo.

Um event CrashLoopBackOff, por exemplo, pode indicar reinicializações repetidas do container, mas normalmente são os logs da aplicação que dizem por que ele travou. As métricas podem revelar esgotamento de memória ou throttling de CPU que contribuíram para a falha. Correlacionar esses sinais ajuda a sair da detecção de sintomas e chegar à análise da causa raiz.

Plataformas de observabilidade costumam integrar events, logs e métricas em um dashboard unificado. Isso permite que as equipes rastreiem problemas em várias camadas do stack.

3. Exporte os events para retenção

Os Kubernetes Events são, por design, temporários e normalmente ficam armazenados por pouco tempo no etcd. Por causa dessa retenção limitada, informações de diagnóstico podem desaparecer rápido após um incidente. Exportar os events para um sistema externo garante que o histórico continue disponível para análise e auditoria.

Muitas organizações encaminham events para plataformas centralizadas de observabilidade, como Elasticsearch, Loki, Splunk ou serviços de monitoramento nativo da nuvem. Esses sistemas oferecem retenção mais longa, consultas avançadas, dashboards e correlação com logs e métricas.

Manter o histórico de events é útil para investigações post-mortem e para identificar padrões operacionais recorrentes.

4. Alerte apenas em events de alto sinal

Nem todo Kubernetes Event precisa virar alerta. Clusters grandes produzem volumes enormes de events informativos, e alertar em todos cria ruído e leva à fadiga de alertas. O foco deve estar em warning events de alto sinal, que apontam problemas operacionais ou risco ao serviço.

Alguns exemplos: FailedScheduling repetidos, CrashLoopBackOff, ImagePullBackOff ou Warning events relacionados a nodes. Filtrar os alertas por tipo, razão, frequência ou recursos afetados ajuda a reduzir notificações desnecessárias.

Um alerting eficaz para events deve priorizar sinais acionáveis em vez do volume bruto.

5. Evite depender do texto exato das mensagens

As mensagens dos Kubernetes Events foram pensadas para leitura humana e podem mudar entre versões ou implementações do Kubernetes. Depender do texto exato em scripts, automações ou regras de monitoramento cria workflows frágeis, que quebram depois de upgrades ou mudanças de plataforma.

Em vez de bater a mensagem completa, use campos estruturados como reason, type, objeto envolvido ou labels. Esses campos são mais estáveis e foram pensados para filtragem programática e automação. Bater no reason FailedScheduling, por exemplo, é bem mais confiável do que buscar uma string de erro do scheduler.

Indo além dos events: detectando e resolvendo problemas no Kubernetes com PerfectScale

Os Kubernetes Events dizem o que deu errado, mas agir em cima deles num ambiente grande ainda significa triagem manual constante. O PerfectScale, da DoiT, fecha essa lacuna ao detectar e remediar de forma autônoma os problemas de resiliência e desempenho que os events expõem — como OOM kills, CPU throttling, evictions e reinicializações repetidas de pods — e ao mesmo tempo faz o right-sizing contínuo dos workloads para manter os clusters estáveis e entregar até 99,99% de disponibilidade.

Principais recursos do PerfectScale:

Remediação automática de problemas: identifica e corrige na hora riscos de resiliência como out-of-memory kills, CPU throttling, evictions e reinicializações de pods, maximizando o uptime e eliminando latência.
Prevenção de erros de configuração: detecta configurações incorretas, como ausência de requests ou limits de CPU e memória, suspeitas de memory leak e workloads que atingiram o número máximo de réplicas antes que esses pontos virem incidentes.
Hardening da infraestrutura: oferece visibilidade holística dos seus nodes para identificar de forma proativa problemas como over-commitment de nodes e affinities ou taints inadequados, que levam a evictions e falhas de scheduling.
Priorização por impacto: classifica os problemas em tempo real e alinha o alerting aos seus SLAs e SLOs, para que as equipes foquem no que mais afeta a consistência do serviço.
Alertas e ticketing integrados: envia notificações instantâneas via Slack, MS Teams ou Datadog e permite escalar qualquer problema para um ticket em um clique.

Saiba mais sobre como o PerfectScale aumenta de forma autônoma a resiliência e o desempenho do seu Kubernetes.