LambdaComunidade
Nível de dificuldade: Intermediário (3 de 5)
Lambda durable functions ganham comando para pausar e retomar execuções durante falhas externas
Desde 17 de novembro de 2026, o Lambda tem PauseDurableExecution: um freio de emergência para parar execuções de durable functions no checkpoint e retomá-las depois, sem perder estado nem reiniciar do zero.
Nota da redação: quase todo o comportamento específico descrito neste artigo (modelo de status PAUSING/PAUSED, o que continua rodando durante a pausa, cobrança, cota, efeitos do DeleteDurableExecution, versão de função no resume e a sintaxe dos comandos CLI de resume e delete) vem exclusivamente de um post de terceiro publicado no DEV Community e em sascha-ms.de, sem documentação oficial da AWS entre as fontes consultadas. Datas, citação direta, nome do autor e exemplos de código batem com essa fonte, mas os detalhes de funcionamento do recurso não puderam ser confirmados de forma independente. Confirme no console ou na documentação oficial da AWS antes de usar este runbook num incidente real.
Desde 17 de novembro de 2026, o Lambda tem PauseDurableExecution: um freio de emergência para parar execuções de durable functions no checkpoint e retomá-las depois, sem perder estado nem reiniciar do zero.
Desde 17 de novembro de 2026, o Lambda tem PauseDurableExecution: um freio de emergência para parar execuções de durable functions no checkpoint e retomá-las depois, sem perder estado nem reiniciar do zero.
Se você mantém funções Lambda com durable functions em produção, já viveu essa cena: um provedor de pagamento começa a devolver erro 500 numa terça à tarde, e dezenas de workflows de pedido ficam presos no meio do caminho. Até 17 de novembro de 2026, as opções eram ruins: deixar as execuções queimarem as tentativas de retry, ou encerrá-las de vez e limpar a bagunça na mão quando o provedor voltasse. Nenhuma das duas serve para uma instabilidade de vinte minutos.
O relato que origina este tutorial é de Odinaka Robert Nnamani, publicado na DEV Community e expandido no artigo completo 'How to pause durable functions in AWS Lambda', em sascha-ms.de. Aqui a ideia é condensar o essencial em algo executável: um runbook de pausa e retomada que você testa antes do incidente, não durante ele.
Vale um aviso: os detalhes de comportamento do recurso reunidos a seguir (o modelo de status PAUSING/PAUSED, o que acontece com waits, callbacks e execuções filhas durante a pausa, cobrança, cota e o que o DeleteDurableExecution apaga) vêm desse relato de terceiro, não de documentação oficial da AWS consultada por esta redação. Trate-os como o relato de quem testou o recurso na prática e confirme no console ou na documentação da AWS antes de se apoiar neles durante um incidente real.
Em números
- 366 dias é o teto de prorrogação do deadline de uma execução pausada, segundo o relato da fonte (o Lambda estende o prazo pelo tempo em pausa, até esse limite contado a partir do início da execução)
- 100 execuções por página é o tamanho usado no exemplo de paginação com
paginateListDurableExecutionsByFunction, o que importa quando você precisa varrer centenas de execuções sem levar throttling - 300 é o número de chamadas de pausa que você precisaria disparar, uma por uma, se tivesse 300 pedidos em andamento: segundo a fonte, a pausa é por execução, não existe um interruptor que congele a função inteira
O que você vai construir
Este tutorial monta um runbook de emergência para durable functions do Lambda: um script que lista as execuções em andamento de uma função específica, corta a entrada de novos pedidos, pausa em lote o que já está rodando e, depois que a dependência externa volta, retoma tudo do último checkpoint. No fim, você também aprende a apagar execuções finalizadas antigas sem deixar rastro de dados sensíveis.
O exemplo usa como referência a função fictícia bookshop-orders, citada no artigo original, representando um fluxo de pedidos que depende de um provedor de pagamento externo.
Pré-requisitos
- Conta AWS com o recurso de durable functions do Lambda habilitado na função alvo
- AWS SDK for JavaScript v3 (pacote
@aws-sdk/client-lambda) em versão atualizada, que já reconheça os comandosPauseDurableExecutioneDeleteDurableExecution - Node.js 18 ou superior e TypeScript, se for seguir o exemplo de código
- AWS CLI v2 atualizada, caso prefira rodar os comandos direto no terminal
- Permissões IAM mínimas, de preferência separadas por papel:
lambda:ListDurableExecutionsByFunctionelambda:PauseDurableExecutionpara quem está de plantãolambda:ResumeDurableExecutionpara retomar depois do incidentelambda:DeleteDurableExecutionisolada numa role à parte, reservada para limpeza e pedidos de exclusão (o artigo original recomenda justamente essa separação entre a role de plantão e a de deleção)- Acesso para desabilitar a origem de eventos da função (por exemplo, o event source mapping de uma fila SQS) durante o teste
Passo a passo
1. Corte a entrada antes de tocar no que já está rodando
Pausar execuções não impede que execuções novas comecem: todo pedido fresco, com um nome novo, continua indo direto contra a dependência quebrada. Por isso o freio de emergência sempre precisa de duas alavancas, e a primeira é cortar a entrada:
aws lambda update-event-source-mapping --uuid <uuid-do-mapping> --enabled falseSe os pedidos chegam por outro caminho (uma API síncrona, por exemplo), pare os chamadores nesse ponto antes de seguir.
2. Liste as execuções em andamento, com paginação
Com centenas de execuções simultâneas, listar tudo de uma vez não é opção. O exemplo abaixo usa o paginador do SDK para varrer a função bookshop-orders filtrando só o que está RUNNING:
const pages = paginateListDurableExecutionsByFunction(
{ client, pageSize: 100 },
{ FunctionName: "bookshop-orders", Statuses: ["RUNNING"] },
);3. Pause em lote, com concorrência limitada e token de idempotência
O núcleo do freio de emergência é um loop que chama PauseDurableExecutionCommand para cada execução encontrada:
for await (const page of pages) {
for (const e of page.DurableExecutions ?? []) {
await client.send(new PauseDurableExecutionCommand({
DurableExecutionArn: e.DurableExecutionArn,
Reason: "Payment provider outage",
}));
}
}Esse trecho é simplificado de propósito. A versão completa, no artigo original, adiciona:
- um pool de concorrência para não estourar limite de chamadas à API
- um
ClientTokenidempotente em cada pausa, para poder reexecutar o script sem efeito colateral - tratamento de
ResourceConflictException, que aparece quando a execução já mudou de estado entre a listagem e a chamada - um modo dry-run, para simular o lote antes de aplicar de verdade
- uma CLI própria com subcomandos
pause,resumeepurge
4. Verifique o status real da pausa, não confie na resposta imediata
Segundo o relato da fonte, o modelo de status tem uma etapa intermediária que costuma pegar gente de surpresa. Se a execução está ociosa (parada num context.wait(), aguardando um callback ou numa pausa de retry), ela vai direto para PAUSED. Se uma invocação está em andamento, ela entra primeiro em PAUSING e continua rodando até o próximo checkpoint, só então encerra.
A diferença entre PAUSING e PAUSED é o que importa. Um passo longo pode atrasar a pausa até o timeout da função, então o freio não é instantâneo.
PAUSING versus PAUSED is the gap that counts. A long step can delay the pause up to the function timeout, so the brake is not instant.Odinaka Robert Nnamani, desenvolvedor backend e autor de rootmail.io e drizzle-pg-extras
Três consequências práticas, relatadas pela fonte:
- um passo longo pode adiar a pausa efetiva em até o tempo total de timeout da função
- uma execução que termina antes do próximo checkpoint simplesmente completa e nunca chega a ser pausada
- logo depois da chamada à API, o status ainda pode aparecer como
RUNNING: é preciso checar de novo
5. Espere a dependência voltar e retome do checkpoint
Seguindo a mesma convenção de nomenclatura da API já documentada (PauseDurableExecution, ListDurableExecutionsByFunction, DeleteDurableExecution), a chamada de retomada é a contrapartida natural, exposta na CLI como:
aws lambda resume-durable-execution --durable-execution-arn <arn>Segundo a fonte, no resume a execução continua na mesma versão de função que estava rodando antes da pausa: um deploy feito durante a pausa não trocaria o código por baixo dela. Vale lembrar também o que, de acordo com o mesmo relato, não para enquanto a execução está pausada:
| Comportamento | Continua rodando durante a pausa? |
|---|---|
Contagem de waits (context.wait()) | Sim, continua contando |
| Callbacks externos chegando ou expirando | Sim |
| Execuções filhas disparadas por invoke encadeado | Sim, não são pausadas junto com a execução pai |
| Deadline de timeout da execução | Por padrão, pausa junto e estende o prazo pelo tempo parado |
Tudo isso aparece de uma vez na primeira invocação depois do resume, e o código precisa estar pronto para lidar com callback vencido ou filho que já terminou sozinho.
6. Decida entre pause e desabilitar o gatilho
O artigo completo traz um guia de decisão entre pause, stop e desabilitar o gatilho, mas a versão condensada usada como fonte aqui não detalha o comportamento do "stop" o suficiente para reproduzi-lo com segurança. O que dá para confirmar nessa fonte é a diferença entre pausar e simplesmente cortar a entrada de novas execuções:
| Ação | O que acontece com o que já está rodando | O que acontece com execuções novas | Estado é preservado? |
|---|---|---|---|
| Pause | Pausa no próximo checkpoint, mantém histórico | Não afeta, continuam entrando normalmente | Sim, retoma do último checkpoint |
| Desabilitar o gatilho (event source mapping) | Não afeta quem já está rodando | Bloqueia a entrada de novas execuções | Não se aplica |
Na prática, o freio de emergência completo é a combinação das duas: desabilitar o gatilho para estancar a entrada e pausar o que já está em voo. Para a comparação completa com "stop", vale consultar o artigo original.
Testando
Não escreva esse script durante o incidente de verdade: valide num ambiente de teste antes.
- Suba uma função de teste com durable functions habilitado e uma dependência externa simulada (um endpoint que você controla e pode fazer falhar de propósito)
- Dispare algumas dezenas de execuções e deixe-as em andamento
- Rode o script de pausa em modo dry-run primeiro, para conferir quantas execuções seriam afetadas sem tocar em nada
- Rode de verdade e confira o status com
ListDurableExecutionsByFunctionfiltrandoStatuses: ["PAUSED"], comparando o total com o que esperava - Simule a volta da dependência, chame o resume e confira nos logs se a execução retomou do checkpoint certo, sem repetir passos já concluídos
- Verifique propositalmente um caso de callback que expirou durante a pausa, para ver como seu código reage na primeira invocação após o resume
Limpando os recursos
Pausar não é de graça para sempre, e testar deixa resíduo que custa dinheiro se ficar esquecido. Segundo o relato da fonte:
- Não há cobrança de invocação enquanto a execução está pausada, mas os dados armazenados da execução continuam sendo cobrados normalmente
- Toda execução pausada continua contando para a sua cota de execuções durable abertas, então pausar em excesso pode empurrar você contra o limite da conta
- Depois dos testes, resuma ou pare explicitamente todas as execuções de teste para não deixá-las penduradas indefinidamente (o teto automático relatado pela fonte é de 366 dias a partir do início)
- Para remover de vez uma execução já finalizada (
SUCCEEDED,FAILED,STOPPEDouTIMED_OUT), useDeleteDurableExecution:
aws lambda delete-durable-execution --durable-execution-arn <arn>- De acordo com a fonte, isso apaga histórico, checkpoints, input e output da execução, útil para pedidos de apagamento de dados (LGPD) ou limpeza depois de um bug. Mas logs, métricas, registros do CloudTrail e qualquer dado que seus passos tenham gravado em outro serviço continuam existindo
- Ainda segundo o relato, deletar execuções antes da hora não reduz a cobrança de armazenamento: se o objetivo é economizar, encurte o período de retenção configurado na função em vez de apagar manualmente
- Reative o event source mapping que você desligou no passo 1 do runbook, e revogue as credenciais de teste usadas na role separada de deleção
Próximos passos
O artigo completo de Odinaka Robert Nnamani, 'How to pause durable functions in AWS Lambda' em sascha-ms.de, cobre pontos que ficaram de fora deste resumo: o modelo de status inteiro (incluindo stop e o estado assíncrono DELETING), comandos AWS CLI passo a passo para listar, pausar, checar e retomar, uma implementação TypeScript completa do freio de emergência com testes e a política IAM já separada entre a role de plantão e a de deleção, além de uma lista de erros comuns: callbacks que expiram durante a pausa, execuções filhas esquecidas e versões desatualizadas do SDK que ainda não reconhecem os comandos novos.
O conselho prático que fica: não escreva esse freio durante o incidente. Coloque no runbook agora, pratique uma vez em ambiente de teste, e quando o próximo provedor externo cair numa terça à tarde, o único trabalho será apertar o botão que já está pronto.
Fonte: DEV Community — #aws
Serviços neste textoLambda
Na dúvida sobre qual usar?ECS, EKS ou Lambda?Três perguntas, a comparação e a nossa recomendaçãoLeve para a sua IA
Decida com o seu assistente, com o contexto deste texto já montado.
1. O que você quer saber
Ver o prompt
Li no AWS Hub: "Lambda durable functions ganham comando para pausar e retomar execuções durante falhas externas" (https://awshub.com.br/comunidade/lambda-durable-functions-ganham-comando-para-pausar-e-retomar-execucoes-durante). Resumo: Desde 17 de novembro de 2026, o Lambda tem PauseDurableExecution: um freio de emergência para parar execuções de durable functions no checkpoint e retomá-las depois, sem perder estado nem reiniciar do zero. Serviços: Lambda Minha stack: [descreva em uma linha: serviços, linguagem, volume, região] Isso muda alguma coisa na minha arquitetura? O que eu faria diferente a partir de amanhã?