Com o avanço da utilização de AI para escrita de código, tenho percebido nos últimos meses vários novos empreendedores (ou builders), se posso chamá-los assim, prototipando e construindo sistemas e aplicações em velocidade assustadora.

Não me entendam mal, eu sou totalmente a favor da AI, utilizo muito no trabalho e também dou risada e concordo com alguns rants do Kelsey Hightower no Linkedin, porque acho que ele tem bons pontos.

É com esse gancho que eu inicio esse texto. Não para criticar o mercado, nem os builders, mas para reforçar que velocidade sem fundamento técnico tem prazo de validade e essa é a real. Seu sistema pode nascer rápido, mas sem uma base sólida, ele não sobrevive por muito tempo.

Uma das grandes “vulnerabilidades” (além as de segurança) hoje em dia é como lidar com falhas. Quanto maior o sistema, ou a quantidade de microsserviços você tem, maior a probabilidade que eles falhem. Novamente, precisamos dessa base fundamental, pois sem ela meu amigo, você está lascado para lidar com falhas sem que seu sistema fique instável.

O que são Falhas em Cascata

Considere um serviço que você administra, ele possui dependências e outros serviços dependem dele.

O que acontece caso uma das dependências falhe? Se você não implementar nenhum mecanismo de segurança, provavelmente o seu serviço irá falhar.

Agora se o seu serviço falha, essa falha pode fazer com que os Serviços A e B também falhem, causando um caos em toda sua aplicação. Muito prazer, o nome disso é falha em cascata.

E o que podemos fazer para prevenir isso? Na real é que às vezes não podemos fazer nada, outras vezes um erro em uma dependência crítica simplesmente não tem contorno. Imagine um cenário onde o banco de dados principal está fora do ar, por exemplo, não há mágica que salve uma operação de escrita e seu serviço não vai conseguir realizar o que precisa porque essa dependência falhou, porém, nem sempre esse é o caso e existem várias maneiras de “salvar” seus serviços em caso de uma falha de dependência.

Respondendo a Falhas

Quando um serviço que você depende falha, como você deve responder? A resposta para uma falha de dependência deve ser, previsível, de fácil entendimento e adequada para a situação. Vamos entrar em mais detalhes.

Previsibilidade

Previsibilidade é uma das características mais importantes que um serviço pode ter. Dado um conjunto específico de circunstâncias e requisições, o seu serviço deve sempre produzir respostas que os consumidores consigam antecipar e tratar. Sem isso, cada falha de dependência se transforma em uma surpresa para quem consome o seu serviço, e surpresas são exatamente o combustível das falhas em cascata.

Assim, se uma de suas dependências downstream falhar você consegue gerar uma resposta previsível, que pode tranquilamente ser uma mensagem de erro.

Vale ressaltar que uma resposta de erro não é o mesmo que uma resposta imprevisível. Uma resposta imprevisível é aquela que os serviços consumidores não esperam receber. Já uma resposta de erro é uma resposta válida, informando que não foi possível executar a operação solicitada. Isso são coisas fundamentalmente diferentes.

Imagine o cenário: se o seu serviço de pagamentos recebe uma requisição para cobrar R$50 de um cliente, é esperado que ele retorne uma confirmação com o ID da transação. Essa é uma resposta previsível. Se esse mesmo serviço recebe uma requisição com um ID de cliente inexistente, uma resposta previsível seria um 404 Not Found ou 400 Bad Request. Ambas são respostas previsíveis, pois o serviço que fez a requisição saberá como interpretá-las e reagir.

Agora, uma resposta imprevisível seria se esse mesmo serviço, ao receber uma requisição com um ID de cliente inexistente, retornasse uma confirmação de cobrança com um ID de transação gerado aleatoriamente, como se o pagamento tivesse sido processado com sucesso. Ou pior, retornasse os dados de outro cliente. O consumidor não tem como se preparar para esse tipo de resposta porque ela não faz parte de nenhum cenário esperado. É o tipo de comportamento que transforma uma falha simples em um problema silencioso que só vai ser descoberto dias depois, numa conciliação financeira.

Fácil Entendimento

Aqui é mais simples e direto, fácil entendimento é formatar uma estrutura acordada entre o serviço e os serviços consumidores, ou seja, um contrato onde as respostas devem respeitar seus limites, mesmo quando uma dependência se comporta de forma inesperada.

Violar esse contrato da sua API com seus consumidores só porque uma dependência violou o contrato dela com você é um super anti-pattern. Ao invés disso, garanta que você cobriu todas as possibilidades de resposta do seu serviço, incluindo cenários de falha nas suas dependências.

Um exemplo clássico de violação de contrato é retornar 200 OK quando algo deu errado.

Voltando ao serviço de pagamentos, se o gateway de cobrança começa a falhar e o seu serviço responde 200 OK com uma mensagem de erro no body, o consumidor pode registrar a cobrança como concluída quando ela nunca aconteceu. Um 502 Bad Gateway ou 503 Service Unavailable seria uma resposta compreensível, onde o serviço que fez a requisição saberia exatamente o que fazer.

Respostas Adequadas

As respostas devem refletir o que de fato está acontecendo com o seu serviço, mesmo quando as dependências estão falhando, a resposta precisa fazer sentido dentro do domínio da operação. Retornar “não foi possível processar a cobrança” ou “tente novamente mais tarde” são respostas razoáveis. Retornar um ID de transação fictício ou um valor aleatório, não são.

Isso parece óbvio, mas respostas absurdas causam problemas com mais frequência do que se imagina. Considere o seguinte cenário onde um serviço de conciliação financeira consulta o serviço de pagamentos para obter a lista de todas as cobranças pendentes que precisam ser estornadas. Em condições normais, o serviço retorna a lista correta e os estornos são processados sem problema.

Agora imagine que o serviço de pagamentos está com uma dependência falhando e, em vez de retornar um erro, retorna uma lista vazia, ou pior, retorna a lista completa de transações, sem filtrar as que são pendentes. E o resultado é puro caos! O serviço de conciliação confia nessa resposta e executa estornos em massa, incluindo cobranças que já foram liquidadas. O resultado é um desastre financeiro enorme causado não por uma falha visível, mas por uma resposta que parecia razoável à primeira vista.

Outro cenário perigoso é quando a operação é concluída com sucesso, mas a resposta indica falha. Imagine que o serviço de pagamentos cobra os R$ 50,00 do cliente, o valor é debitado, mas na hora de retornar a confirmação algo dá errado e o serviço responde com um 500 Internal Server Error. O consumidor interpreta que a cobrança não aconteceu e faz um retry. Resultado: o cliente é cobrado duas, três, cinco vezes pelos mesmos R$ 50,00.

Esse é um caso clássico onde a resposta não é adequada ao que de fato aconteceu. A cobrança foi bem-sucedida, mas a resposta disse o contrário. Aqui, mecanismos como idempotência, onde o consumidor envia uma chave única por requisição e o serviço garante que a mesma operação não será executada duas vezes são essenciais para evitar esse tipo de estrago.

Determinando Falhas

Agora que sabemos o básico do básico de como responder a falhas, precisamos determinar quando uma dependência começa a falhar em primeiro lugar. E isso depende de como a falha aconteceu, vou dar alguns exemplos:

Garbled Responses (ou Respostas Confusas)

Direto ao ponto, a resposta foi dada em um formato irreconhecível pelo serviço consumidor, exemplo, você aguarda um array e a resposta chegou em string.

Respostas indicando erro fatal

Aqui a resposta já foi parseada corretamente, indicando um problema ocorreu durante o processamento da requisição. Geralmente, não é uma falha na camada de comunicação, mas com o serviço em si.

No contexto do serviço de pagamentos, seria o equivalente a enviar uma requisição de cobrança com um payload inválido, por exemplo, sem o valor da transação ou com um formato de moeda que o serviço não reconhece. A resposta 400 Bad Request ou 500 Internal Server Error é perfeitamente compreensível, algo deu errado e o serviço consumidor sabe que não deve confiar em nenhum resultado dessa operação.

Resposta compreensível, mas com resultados inesperados

A resposta é compreensível e indica que a operação foi executada sem erros graves, mas os dados retornados não correspondem ao esperado. No serviço de pagamentos, seria como solicitar o extrato de cobranças de um cliente e receber as cobranças de outro. A resposta está bem formatada, o status code é 200 OK, mas o conteúdo está errado. Esse tipo de falha é perigoso porque passa despercebido por validações superficiais.

Resultado fora dos limites esperados

A resposta é compreensível pelo serviço consumidor, a operação foi executada com sucesso, e os dados estão em um formato “razoável”, mas os valores em si não fazem sentido. Usando nosso exemplo de serviço de pagamentos é retornado o total de cobranças pendentes de um cliente e o valor é R$ 9.999,99 para uma assinatura mensal de R$ 49,90. A resposta é válida, parseável e não indica erro, mas está claramente fora dos limites esperados. Sem uma validação de limites no consumidor, esse valor poderia ser cobrado de fato.

A resposta não chegou

A requisição foi enviada, mas nenhuma resposta foi recebida. Isso pode acontecer por um problema de rede, uma falha no serviço ou uma indisponibilidade total. No caso do serviço de pagamentos, o chamador fica sem saber se a cobrança foi efetuada ou não, ou seja, um cenário que exige estratégias como idempotência e retry com backoff para ser tratado de forma segura.

E quando a resposta demorou pra chegar?

A requisição foi enviada e a resposta chegou válida, útil e dentro dos limites esperados. Porém, levou muito mais tempo que o normal. Isso costuma ser um sinal de que o serviço ou a rede está sobrecarregada. No serviço de pagamentos, uma resposta lenta pode significar que o gateway de cobrança está sob uma pressão muito alta. Se o serviço consumidor não tiver um timeout adequado, essa lentidão se propaga para cima, degradando toda a cadeia, o cenário clássico de início de uma falha em cascata.

Uma resposta que demora a chegar de um serviço (ao invés de nunca chegar) é talvez a mais difícil de ser detectada, pois o problema começa em determinar o quão lento é lento e aqui o bicho pega por que, usando timeouts ou circuit breakers é geralmente insuficiente para lidar com a situação, porque uma resposta lenta às vezes pode ser rápida o suficiente, gerando resultados erráticos.

Vale lembrar que previsibilidade da resposta é uma característica bem importante para seu serviço e a dependência que falha de forma não previsível vai complicar a sua habilidade de criar respostas previsíveis para suas dependências. É complicado entender de início, mas depois fica fácil.

Tomando ações

Beleza, agora que você já entende como falhas acontecem e como responder a elas, é hora de falar sobre as ações que o seu serviço pode tomar quando uma dependência falha.

Graceful Degradation

Se uma dependência falha, o seu serviço consegue continuar operando sem a resposta dessa dependência? Consegue executar ao menos uma parte do trabalho esperado? Se sim, isso é um exemplo de Graceful Degradation, ou usando um termo em português “degradação graciosa”.

Graceful Degradation é quando um serviço reduz o mínimo possível a quantidade de trabalho que realiza diante da indisponibilidade de uma dependência.

Graceful Backoff

Existe um ponto em que a degradação não é mais suficiente, simplesmente não há resultados disponíveis o bastante para que a resposta seja útil. A requisição precisa falhar. Mas em vez de apenas retornar um erro, será que o seu serviço consegue realizar alguma ação alternativa que ainda entregue valor ao consumidor?

Mudar o que o serviço faz de forma a oferecer algum valor, mesmo quando não é possível completar a requisição original, é um exemplo de Graceful Backoff.

No serviço de pagamentos, imagine que o gateway principal de cobrança e o gateway secundário estão ambos fora do ar. Não há como processar o pagamento. Em vez de simplesmente retornar um 503 e deixar o cliente sem resposta, o serviço poderia registrar a intenção de compra e responder com algo como “não conseguimos processar seu pagamento agora, mas salvamos seu carrinho, você receberá um aviso assim que o pagamento puder ser concluído”. O pedido não foi finalizado, mas o cliente não perdeu a seleção de produtos, e o serviço preservou a possibilidade de conversão futura.

Falhe o Mais Rápido Possível

E quando não for possível continuar operando sem a resposta da dependência que falhou? Se não existe uma funcionalidade reduzida ou um graceful backoff que faça sentido? Sem aquela resposta, o serviço simplesmente não consegue fazer nada útil. Nesse caso, a única opção é falhar a requisição, e quando isso acontece, é fundamental falhar o mais rápido possível. Não continue executando outras etapas da requisição original depois de saber que ela vai falhar.

No serviço de pagamentos, se o serviço de antifraude está indisponível e a política da empresa exige validação de fraude antes de qualquer cobrança, não há como prosseguir. Nesse cenário, não faz sentido validar o cartão, reservar estoque ou gerar um ID de transação, tudo isso será descartado. O serviço deve retornar imediatamente um erro claro e liberar os recursos.

Aqui você pode realizar o máximo de validações possíveis logo no início da requisição. Verifique campos obrigatórios, limites de valor, formato do cartão e permissões do cliente antes de acionar qualquer dependência externa. Assim, quando o serviço avançar para as etapas mais custosas, há uma boa chance de que a requisição será concluída com sucesso, e as falhas evitáveis já foram eliminadas antes de consumir recursos desnecessários.

Agora, por que falhar cedo?

Conservar Recursos

Se uma requisição vai falhar, qualquer trabalho realizado antes de identificar essa falha é trabalho desperdiçado. No serviço de pagamentos, imagine processar uma cobrança sem antes verificar se o cliente existe. O serviço consulta o gateway de antifraude, valida o cartão, reserva estoque, e só então descobre que o ID do cliente é inválido. Todas essas chamadas para dependências externas consumiram recursos à toa, apenas para resultar em um erro.

Responsividade

Quanto antes o serviço determinar que uma requisição vai falhar, antes poderá devolver essa informação ao serviço consumidor. No serviço de pagamentos, se o valor da cobrança é negativo, rejeitar imediatamente com um 400 Bad Request permite que o consumidor corrija e reenvie a requisição em milissegundos ao invés de esperar segundos por um timeout de uma dependência que nem precisava ser acionada.

Complexidade do erro

Às vezes, permitir que uma requisição que vai falhar avance pelo fluxo só ficará mais difícil de debugar e entender onde está o problema.

No serviço de pagamentos, considere uma cobrança com valor zero. É possível detectar isso imediatamente e rejeitar a requisição. Mas se o serviço seguir adiante e enviar essa cobrança ao gateway, o comportamento pode ser imprevisível, o gateway pode retornar um erro genérico, travar em um loop de retry interno, ou até registrar uma transação fantasma que depois precisará ser conciliada manualmente.

Uma falha simples se transforma em um problema operacional muito mais difícil de resolver.

Se liga aí que é hora da revisão!

Falhas em cascata não começam com uma explosão. Elas começam com uma resposta lenta que ninguém notou, um timeout mal configurado, ou um serviço que retornou 200 OK quando deveria ter retornado um erro. O estrago acontece de forma silenciosa, dependência por dependência, até que o sistema inteiro caia e aí já é tarde demais.

A boa notícia é que a maioria dessas falhas é fácil de prevenir. Respostas previsíveis, contratos bem definidos, circuit breakers, graceful degradation e a disciplina de falhar cedo são padrões que existem há anos, o desafio é aplicá-las de forma consistente.

Novamente, construir rápido é ótimo. A AI está possibilitando isso todos os dias, mas construir rápido e de forma resiliente é o que separa um protótipo de um sistema production-ready.

Imagina o seguinte cenário: você trabalha em um e-commerce com alto volume de tráfego e logo no início do ano a diretoria comercial junto ao marketing decide realizar uma mega promoção de queima de estoque de produtos que não venderam na Black Friday, com desconto agressivo e prazo curto.

Tudo no ar, campanhas rodando em redes sociais, tráfego subindo, todo mundo animado. Até que percebem que um cálculo errado de preço está sendo aplicado em parte do catálogo, afetando diretamente alguns dos produtos da promoção.

Não tem muito o que discutir, é preciso corrigir. A única saída é um novo deploy para sanar o problema.

Seu time faz a correção, o CI passa, o deploy começa. Minutos depois, o time de atendimento dispara no Slack dizendo que vários clientes não conseguiram finalizar compras nos últimos 5 minutos, exatamente o tempo que levou para o rollout da nova versão. Carrinhos abandonados, pagamentos falhando, reclamações públicas. Climão.

Você começa a investigar e percebe que diversas requisições simplesmente não foram concluídas durante o deploy. Algumas morreram no meio do caminho. Outras nunca receberam resposta.

O que aconteceu? Sua aplicação morreu no meio de transações ativas. Pedidos sendo processados foram abortados. Pagamentos ficaram em estados inconsistentes. Workers processando emails de confirmação morreram deixando eventos órfãos no Kafka.

E agora? Como evitar que isso aconteça de novo?

É aqui que entra o Graceful Shutdown, uma forma de encerrar uma aplicação de maneira controlada, garantindo que requisições em andamento sejam concluídas antes do processo morrer.

O que é Graceful Shutdown de verdade?

Graceful Shutdown é um contrato operacional entre sua aplicação e o ambiente onde ela roda. Para satisfazer esse contrato, você precisa garantir três coisas:

1. Não aceitar novas requests e workloads: Encerrar o recebimento de novas requisições HTTP; Parar de consumir mensagens de filas (Kafka, RabbitMQ, SQS); Sem derrubar conexões já estabelecidas com banco de dados ou cache;

2. Completar todo processamento: Aguardar que todas as requisições ativas sejam concluídas; Processar mensagens que já foram retiradas da fila; Se ultrapassar um tempo aceitável, responder com erro previsível, não timeout genérico.

3. Liberar recursos: Encerrar conexões com bancos de dados; Commitar offsets do Kafka; Liberar locks de arquivos; Finalizar qualquer comunicação ativa com sistemas externos.

Neste artigo, vou mostrar como implementar isso em Go, mas o conceito vale para qualquer linguagem, runtime ou plataforma de orquestração.

Como processos sabem que devem morrer?

Antes de nos aprofundarmos em Graceful Shutdown, é importante entender como processos são “avisados” de que precisam parar. Vamos voltar ao cenário do e-commerce, quando você fez o deploy, o que exatamente aconteceu do ponto de vista do processo rodando no container?

Sinais

Em sistemas Unix-like, processos são notificados através de sinais. Sinais são interrupções enviadas pelo sistema operacional (ou por outro processo) para notificar que algo relevante aconteceu e uma ação precisa ser tomada.

Quando um sinal é entregue, o fluxo normal de execução do processo é interrompido para que ele possa reagir a esse evento.

Porém, nem todo processo reage da mesma forma a um sinal, e nem todo sinal permite reação.

Existem três comportamentos possíveis:

Signal handler

Um signal handler é uma função registrada pela aplicação para lidar com um sinal específico. Quando o sinal é recebido, o processo não morre automaticamente. Em vez disso, o handler é executado, permitindo que a aplicação:

• Pare de aceitar novas requisições;

• Aguarde requisições em andamento;

• Libere recursos;

• Finalize de forma controlada.

Ação padrão (default action)

Se a aplicação não define um handler, o sistema operacional executa a ação padrão associada ao sinal e dependendo do sinal, essa ação pode ser:

• Encerrar o processo imediatamente;

• Ignorar o sinal;

• Parar (suspender) o processo.

Unblockable signals (sinais que não podem ser tratados)

Alguns sinais não podem ser interceptados ou ignorados, independentemente do que a aplicação faça. Os mais conhecidos são SIGKILL e o SIGSTOP. Quando um desses sinais é enviado, o processo morre imediatamente, sem chance de cleanup, sem handler, sem tempo de reagir.

E em ambientes conteinerizados?

No Kubernetes, o processo normalmente recebe um SIGTERM antes de qualquer coisa mais agressiva. Esse é como se fosse um último aviso educado para a aplicação.

Se a aplicação não trata SIGTERM ou demora mais do que o tempo configurado, o orquestrador envia um SIGKILL e a sua aplicação cai.

Voltando ao cenário do deploy com bug de preço

15:29:58 - Deploy iniciado
15:30:00 - Kubernetes envia SIGTERM para Pod antigo
15:30:00 - Sua aplicação IGNORA o sinal (não tem handler)
15:30:00 - Runtime do Go encerra processo imediatamente
15:30:00 - 47 requisições HTTP ativas abortadas
15:30:00 - 12 mensagens Kafka meio processadas
15:30:00 - 3 workers gerando relatórios mortos
15:30:01 - Time de atendimento começa a receber reclamações

O erro comum

Muitos times acham que “Graceful Shutdown é coisa do Kubernetes” ou do load balancer, a real é que não é.

O Graceful Shutdown começa dentro da aplicação, no momento em que ela decide o que fazer ao receber um sinal.

Lidando com sinais em Go

Quando uma aplicação Go inicia, antes mesmo da função main rodar, o runtime registra handlers para vários sinais do sistema operacional. Esses handlers existem para garantir que o processo termine de forma previsível.

Porém, para Graceful Shutdown, quase tudo é ruído. Na prática, três sinais concentram 99% dos cenários reais:

• SIGTERM: Indica que o processo deve encerrar. É o sinal enviado por orquestradores como Kubernetes durante deploys, scale down ou evictions. Ele pode e deve ser tratado pela aplicação;

• SIGINT: Normalmente enviado quando alguém pressiona Ctrl+C no terminal. O comportamento esperado é encerrar de forma limpa, assim como no SIGTERM;

• SIGHUP: Historicamente é um sinal utilizado para indicar fechamento de terminal. Hoje em dia, ele costuma ser usado para recarregar configs.

Por padrão, ao receber qualquer um desses sinais, o runtime do Go encerra o processo imediatamente. Isso significa que:

• Requisições em andamento são abortadas;

• Conexões são fechadas sem aviso;

• O sistema externo que chamou sua aplicação não vai receber a resposta.

Para mudar esse comportamento, é necessário interceptar os sinais usando o pacote os/signal.

Basicamente, signal.NotifyContext (disponível desde o Go 1.16) faz com que o runtime notifique os sinais para um contexto ao invés de executar o comportamento padrão, permitindo que você configure a melhor forma de prevenir que a aplicação termine de forma abrupta.

Timeout não é detalhe

Graceful Shutdown não acontece no seu tempo, acontece no tempo que o ambiente permite.

Quando sua aplicação recebe um sinal de encerramento, existe um relógio invisível rodando. Se ele zerar antes do seu cleanup terminar, o sistema simplesmente mata o processo.

No Kubernetes, por exemplo, o comportamento padrão é o seguinte:

• Ao iniciar um deploy, scale down ou eviction, o Pod recebe um SIGTERM;

• A partir desse momento, começa a contar o valor que é especificado no terminationGracePeriodSeconds, que por padrão são 30 segundos - doc;

• Se o processo ainda estiver vivo ao final desse período, o Kubernetes envia um SIGKILL.

E aqui não tem negociação, o SIGKILL não pode ser interceptado, tratado ou ignorado. O processo morre imediatamente, no estado em que estiver.

Isso significa que toda a sua lógica de shutdown precisa caber dentro dessa janela:

• Concluindo requisições em andamento;

• Respondendo erros controlados se necessário;

• Liberando conexões;

• Finalizar goroutines e workers.

No cenário do e-commerce, se você tem:

• Requisições HTTP de checkout que levam 5-8 segundos (validação de estoque, pagamento, nota fiscal);

• Workers processando emissão de Notas Fiscais que levam 10-15 segundos;

• Consumidor Kafka commitando offsets em batch a cada 30 segundos.

Você tem um baita de um problema. O shutdown padrão de 30s não vai dar conta.

Parando de receber requisições: HTTP Server

Vamos começar pelo básico, fazer o servidor HTTP parar de aceitar novas requisições.

O pacote net/http possui o método http.Server.Shutdown(ctx) que implementa Graceful Shutdown nativamente. Ele para de aceitar novas conexões, aguarda as requisições em andamento completarem (respeitando o contexto passado) e então fecha as conexões idle. Veja um exemplo aqui.

Se você usa Gin, ele não possui método próprio, você usa o http.Server.Shutdown diretamente, já que Gin é apenas um wrapper em cima do net/http. Exemplo aqui.

Já se você usa o Fiber (minha escolha pessoal), ele tem seu próprio método, o app.ShutdownWithContext(ctx) porque usa o fasthttp por baixo e não o net/http. Exemplo.

Comportamento comum aos três

Independte da implemente, framework, o comportamento é o mesmo:

• Param de aceitar novas conexões imediatamente;

• Aguardam requisições ativas finalizarem (com timeout do contexto);

• Fecham conexões idle;

• Porém, não garantem que requisições vão completar se o timeout do contexto expirar.

O problema do Kubernetes

Já no Kubernetes, mesmo após o Pod ser marcado para termination, o kube-proxy pode demorar alguns segundos (~5-10s) para atualizar as regras de iptables e remover o Pod dos endpoints do Service.

Durante essa janela, você ainda pode receber tráfego. O que acontece:

15:30:00 - SIGTERM enviado 
15:30:00 - app.Shutdown() chamado imediatamente 
15:30:00 - Servidor para de aceitar conexões 
15:30:01 - Cliente tenta conectar → Connection refused 
15:30:02 - Cliente tenta conectar → Connection refused 
15:30:05 - kube-proxy finalmente atualiza iptables 
15:30:05 - Agora sim, tráfego para de chegar

O resultado são clientes recebendo erros 5xx.

Uma boa solução é implementar um delay antes de chamar o Shutdown:

E agora o fluxo ficaria algo assim:

15:30:00 - SIGTERM recebido
15:30:00 - Aplicação aguarda 10s (delay intencional)
15:30:05 - kube-proxy atualiza iptables
15:30:10 - app.Shutdown() chamado
15:30:10 - Servidor para de aceitar conexões (mas não chega mais tráfego)
15:30:12 - Requisições ativas completadas
15:30:12 - Servidor encerrado 

O que você esqueceu de desligar

Você implementou http.Server.Shutdown, testou localmente, fez deploy em produção. Tudo funcionando. Até que numa terça-feira às 3 da manhã você recebe um alerta: mensagens duplicadas no Kafka, jobs incompletos no banco, relatórios corrompidos.

O que aconteceu? Seu servidor HTTP morreu corretamente com Graceful Shutdown, mas o resto da aplicação morreu no meio do caminho.

O problema real

Aplicações não são só servidores HTTP. Elas têm:

• Consumidores de fila processando eventos assíncronos;

• Workers em background gerando relatórios, enviando emails, processando uploads;

• Jobs agendados fazendo limpeza, sincronização, cálculos periódicos;

• Conexões persistentes com bancos, caches, message brokers.

Quando você faz Graceful Shutdown apenas do servidor HTTP, esses componentes continuam rodando até o SIGKILL chegar (~30s depois no Kubernetes). O resultado:

15:30:00 - SIGTERM recebido
15:30:00 - HTTP server para de aceitar requests
15:30:02 - HTTP server finaliza últimas requisições
15:30:02 - HTTP server encerrado 
15:30:02 - Kafka consumer ainda processando pedido #8472
           ↳ Validando estoque, reservando produtos...
15:30:15 - Worker ainda gerando nota fiscal do pedido #8480
           ↳ PDF 70% completo, gravando no S3...
15:30:20 - Job de sincronização com ERP ainda rodando
           ↳ Atualizando 4.823 produtos de 10.000...
15:30:30 - SIGKILL → tudo morre abruptamente
           ↳ Pedido #8472: estoque reservado mas não commitado no Kafka
           ↳ Nota fiscal #8480: PDF corrompido no S3
           ↳ Sincronização ERP: estado inconsistente

A sequência de shutdown também é importante. Você precisa respeitar as dependências entre componentes:

Fase 1

Primeiro você impede que novos processamentos ocorram no sistema:

1. HTTP Server para de aceitar requisições;

2. Kafka Consumer para de consumir novos eventos;

3. Jobs agendados devem ser cancelados.

A ideia de fazer nessa ordem é porque o servidor HTTP pode enfileirar eventos no Kafka, e o Kafka pode disparar jobs. Se você parar o Kafka antes do HTTP, requisições vão falhar ao tentar publicar os eventos.

Fase 2

Aqui a ideia é finalizar todo processamento que está em andamento:

1. Requisições HTTP ativas, por exemplo: checkout, pagamento;

2. Kafka Consumers: Finaliza processamento, commita offsets;

3. Workers: Completa geração de Notas Fiscais, envio de e-mails;

4. Jobs: Termina sincronização com ERP.

Fase 3

Por fim, você a aplicação deve liberar conexões com recursos externos:

1. Fecha conexões com o Kafka, tanto de producer quanto consumer;

2. Encerra conexão com o banco de dados;

3. Encerra conexão com o Redis, memcached ou qualquer outro sistema de cache;

4. Libera locks de arquivos.

Essa ordem importa, por que se você fechar a conexão com o banco de dados enquanto os workers ainda estão salvando Notas Fiscais, você verá um connection closed do nada. Se fechar a conexão com o Kafka antes de commitar os offsets, vai ter que reprocessar mensagens.

Exemplo:

Goroutines também precisam saber a hora de morrer

Outro ponto ignorado com frequência: goroutines não morrem sozinhas.

Quando o processo recebe um SIGTERM:

• O runtime não cancela goroutines automaticamente;

• Loops infinitos continuam rodando;

• Workers bloqueados continuam bloqueados.

Se você não tem um mecanismo claro de cancelamento (normalmente via context.Context), você está acreditando que o processo vai morrer rápido o suficiente, ou o orquestrador vai mandar SIGKILL.

Nenhuma das duas opções é uma boa estratégia.

Uma boa aqui é utilizar context-aware goroutine, exemplo. Agora caso você tem várias goroutines, use sync.WaitGroup para aguardar todas finalizarem, exemplo.

Toda goroutine de longa duração deveria responder a cancelamento. Se ela não sabe quando parar, ela é provavelmente é um leak.

Shutdown precisa ser previsível, não best effort

Muita gente implementa shutdown como algo “best effort”, tenta fechar tudo e torce para dar tempo e isso é frágil.

O shutdown precisa ter:

• Ordem clara, o que encerra antes do quê;

• Limites de tempo explícitos;

  • Lembra das fases que citei acima?

• Fallback bem definido. O que acontece se algo não for encerrado conforme esperado?

Esses tempos precisam ser mensurados e testados. Uma dica aqui é adicionar uma gordura. Voltando ao nosso cenário:

Vamos relembrar que o terminationGracePeriodSeconds por padrão no Kubernetes são 30 segundos, mas a soma das nossas fases dá ~35s. Isso é intencional, você quer que todas fases termine antes do SIGKILL.

Você pode muito bem configurar o lifecycle do seu Deployment/Pod através do parâmetro terminationGracePeriodSeconds e utilizar o preStop hook.

Observe o shutdown como um evento crítico

Outro erro recorrente, o shutdown não é observado.

Em produção, você deveria conseguir responder:

• Quanto tempo o shutdown levou?

• Q que demorou mais?

• Quantas requisições foram abortadas?

• Houve timeout?

Sem logs claros e métricas, o shutdown vira um buraco negro. Quando algo dá errado, ninguém sabe o real motivo.

Talvez esse seja o grande ponto de reflexão do meu post, Graceful Shutdown é um evento operacional importante, não um detalhe de implementação.

Dicas para mensurar

• Através métricas para mensurar o tempo de duração do shutdown;;

• Através de logs contendo duração, quantas requests estavam ativas, quantos jobs estavam pendentes;

• Crie uma dashboard para monitorar esses tempos, com duração do shutdown, quantos shutdowns foram bem sucedidos, a duração por fase e quantas requests foram abortadas;

• Alerte apenas em casos críticos. Quando o shutdown está próximo dos 30s ou do valor que você definir do terminationGracePeriodSeconds.

Não teste só quando dá problema

Shutdown precisa ser testado:

• Localmente durante desenvolvimento;

• Em staging antes de subir pra produção;

• Sob carga com tráfego real;

• Com latência que possa simular dependências lentas;

• Com dependências como banco de dados e Kafka falhando.

Quanto antes você falhar, mais barato é corrigir.

Conclusão

Graceful Shutdown não é uma feature opcional nem um detalhe de infraestrutura.
Ele é parte do contrato da aplicação com o ambiente onde ela roda.

Se você ignora:

• Sinais do sistema operacional;

• Limites de tempo impostos pelo orquestrador;

• Requisições em andamento;

• Goroutines e workers;

O sistema vai continuar funcionando, até o dia em que o deploy custar dinheiro, reputação ou ambos.

Próximos passos

Se você ainda não tem Graceful Shutdown:

1. Comece pelo básico interceptando SIGTERM e SIGINT;

2. Implemente shutdown do servidor HTTP;

3. Identifique todos os componentes concorrentes (Kafka, workers, jobs);

4. Implemente shutdown coordenado respeitando dependências;

5. Adicione logs e métricas;

6. Teste localmente com Ctrl+C;

7. Teste em staging sob carga;

8. Faça rollout gradual em produção;

9. Monitore e ajuste timeouts baseado em dados reais.

Se você já tem Graceful Shutdown:

1. Revise a ordem, ela respeita dependências?;

2. Meça os timeouts;

3. Adicione observabilidade;

4. Teste sob condições adversas;

5. Configure alertas;

6. Documente.

Fiquem a vontade para comentar suas soluções, como vocês implementam ou se possuem dúvidas sobre o tema.

Até mais!

Compartilhar