O blog da AWS
Observando as funções duráveis do AWS Lambda com o Durable Execution Telemetry Exporter
Por Pooya Paridel, na Amazon Web Services.
Uma função durável é uma função do AWS Lambda que pode ser executada por minutos, dias ou até um ano. Você cria essas funções com o Durable Execution SDK, que fornece operações como steps, waits e parallel. Uma única execução durável pode ser distribuída por muitas invocações do Lambda, com esperas e novas tentativas entre elas. Por isso, observar uma execução durável, composta por muitas invocações, exige ferramentas diferentes. A pergunta que você quer responder raramente é “o que esta invocação fez?”. Geralmente é “até onde minha execução durável chegou, qual step falhou, quantas vezes foi repetido e quanto tempo levou o processo todo?”
Depois que você executa milhares de execuções, as perguntas passam de uma única execução para todas elas. Algumas perguntas são operacionais. Qual step falha com mais frequência e com qual erro? Qual step causa mais novas tentativas? Um step ficou mais lento após a implantação da semana passada? Outras perguntas são sobre o negócio que o fluxo de trabalho executa. Quais clientes foram afetados pelas falhas de pagamento da noite passada? Quanto tempo leva cada etapa de aprovação manual? Dos pedidos que foram iniciados, quantos chegaram à etapa de pagamento e onde os demais pararam? Responder a essas perguntas exige dados de telemetria por execução que incluam informações relevantes, como status, tempo, steps e os campos de entrada e saída que você escolher emitir.
A observabilidade tradicional do Lambda funciona bem para uma única invocação. O Lambda grava um log stream por invocação; assim, uma execução durável que é suspensa quatro vezes grava em quatro log streams separados, intercalados com todas as outras execuções simultâneas. As métricas do Amazon CloudWatch informam a taxa de erros da função, mas não qual dos steps do seu fluxo de trabalho é o responsável. O rastreamento distribuído, como o AWS X-Ray ou o OpenTelemetry, mostra o tempo de uma execução. Ele não foi criado para responder a perguntas sobre muitas execuções, como qual step falhou com mais frequência nesta semana. Para isso, você precisa de um registro consultável por execução.
Hoje estamos apresentando o Durable Execution Telemetry Exporter, um plugin de observabilidade para as funções duráveis do AWS Lambda. Junto com ele, apresentamos o Durable Execution Telemetry MCP server, um servidor do Model Context Protocol (MCP) que permite que um agente de codificação de IA consulte os dados de telemetria. O exportador é de código aberto para TypeScript, Python, Java e Go, no repositório do Durable Execution SDK de cada linguagem. A AWS disponibiliza o servidor MCP como código aberto no repositório aws-durable-execution-sdk-js.
Com uma alteração de configuração de uma linha, você obtém um registro de cada execução, com todos os steps, waits, callbacks e invokes, incluindo tempo, tentativas de repetição, status e erros. O exportador o entrega a um destino de sua escolha. Não é necessário escrever instrumentação personalizada nem executar um agente separado.
Como funciona o Durable Execution Telemetry Exporter
O Durable Execution Telemetry Exporter é um plugin para o SDK de execução durável. Ele é executado dentro da sua função do Lambda, no mesmo processo do seu handler, e assina o ciclo de vida de instrumentação do SDK. Ele não é executado no caminho da sua requisição.
A cada invocação de uma execução durável, o plugin cria um snapshot cumulativo dessa execução, em vez de uma visão incremental ou por invocação. Como o SDK de execução durável reproduz (replay) o seu handler desde o início a cada retomada e o SDK passa o estado com checkpoint para o plugin, o plugin consegue reconstruir toda a execução até o momento a partir de qualquer invocação. Esse snapshot é um único documento JSON chamado DurableExecutionTelemetryRecord:
Cada registro é completo por si só. Uma linha em uma tabela é uma execução durável, ou seja, as perguntas que você faz (step mais lento, step com mais novas tentativas, execuções que falharam após a etapa de pagamento) se tornam consultas comuns, em vez de exigirem a correlação de logs entre streams.
Primeiros passos
Instale o plugin junto com o SDK de execução durável:
Em seguida, passe-o para withDurableExecution:
Essa é toda a integração. Sem nenhuma configuração, o LambdaLogExporter padrão grava os registros como JSON no grupo de logs do CloudWatch da própria função. Você não precisa criar nenhuma infraestrutura nem conceder permissões adicionais do AWS Identity and Access Management (IAM), porque sua função já grava seus próprios logs. Você pode consultar o resultado imediatamente com o Amazon CloudWatch Logs Insights:
Escolhendo para onde os registros vão
O plugin inclui 13 exportadores de destino para que você envie os registros para onde eles forem úteis:
| Destino | Exportador | Ideal para |
| Grupo de logs da própria função | LambdaLogExporter |
Primeiros passos, sem configuração |
| Qualquer grupo de logs do CloudWatch | CloudWatchLogsExporter |
Centralização de registros entre funções |
| Amazon Simple Storage Service (Amazon S3) | S3Exporter |
SQL no Amazon Athena, retenção de longo prazo |
| Amazon DynamoDB | DynamoDBExporter |
Consulta rápida por execução, dashboards em tempo real |
| Amazon Aurora | AuroraExporter |
Combinação de dados do fluxo de trabalho com dados de negócios |
| Amazon Redshift | RedshiftExporter |
Análises em grande escala entre funções |
| Amazon OpenSearch Service | OpenSearchExporter |
Pesquisa de texto completo, dashboards |
| Amazon EventBridge | EventBridgeExporter |
Alertas e remediação em caso de falha |
| Amazon Data Firehose | FirehoseExporter |
Fan-out para S3, Splunk ou terceiros |
| Amazon Simple Queue Service (Amazon SQS) | SQSExporter |
Processamento downstream desacoplado |
| Qualquer endpoint OTLP | OTelExporter |
Plataformas de observabilidade de terceiros |
| Qualquer endpoint HTTPS | HttpExporter |
Backends personalizados e webhooks |
| Sistema de arquivos ou Amazon Elastic File System (Amazon EFS) | FileExporter |
Desenvolvimento local, persistência no EFS |
O plugin envia registros a todos os exportadores configurados em paralelo. Isso permite que você direcione os dados para diferentes armazenamentos com base em suas características, como usar um armazenamento rápido para consultas em tempo real e um armazenamento de alta capacidade e menor custo para retenção de longo prazo:
Com o exportador do S3, o plugin grava registros em partições no estilo Hive (year=YYYY/month=MM/day=DD/) que um crawler do AWS Glue descobre automaticamente, de modo que as consultas do Athena funcionam sem modelagem adicional:
Controlando a frequência e o conteúdo
Três configurações determinam o custo e a exposição de uma implantação em produção.
emitMode determina quando o plugin envia um registro. O padrão, on-complete, emite uma vez quando uma execução atinge SUCCEEDED ou FAILED. Use on-failure para o menor overhead quando você se importa apenas com erros, ou on-change quando quiser acompanhar o progresso das execuções quase em tempo real.
samplingRate reduz a frequência. O plugin deriva a decisão de amostragem de um hash do ARN da execução. O ARN da execução é estável entre replays; por isso, a decisão é determinística: uma execução incluída na amostra emite todos os seus registros, e uma execução excluída não emite nenhum. Você nunca recebe um fluxo de trabalho parcialmente registrado.
content controla o que sai da sua função. Por padrão, o plugin inclui a entrada e a saída da execução como estão, o que é conveniente em desenvolvimento e frequentemente inaceitável em produção. Passe uma transformação para ocultar dados:
Cada destino oferece suporte a tamanhos de payload diferentes: eventos do CloudWatch Logs de 256 KB, itens do DynamoDB de 400 KB. Cada exportador tem um maxRecordSizeBytes e, quando um registro o excede, o plugin o trunca para um destino sem afetar os outros destinos: primeiro os resultados das operações, depois operações inteiras da mais antiga para a mais recente e, por último, a entrada e a saída da execução. O plugin nunca descarta os campos de identidade e de linha do tempo e marca um registro reduzido como truncated: true, de modo que um registro truncado seja sempre distinguível de um completo. Recomendamos usar transformações de content para limitar os payloads de forma deliberada, em vez de depender do truncamento.
Consultando o histórico de execuções a partir de um agente de IA
Responder “por que o lote da noite passada falhou” exige saber qual armazenamento de dados você configurou, qual dialeto de consulta ele usa e como é o esquema do registro. O PartiQL do DynamoDB, o SQL Trino do Athena, o Aurora PostgreSQL, o Amazon Redshift, o OpenSearch e o CloudWatch Logs Insights são todos diferentes.
O Durable Execution Telemetry MCP server elimina esse requisito. Ele é um servidor stdio local que expõe o destino configurado a qualquer agente compatível com MCP, incluindo Kiro, Claude Code e Cursor. Adicione-o com um comando:
A configuração é feita somente por variáveis de ambiente e as credenciais vêm da cadeia de provedores padrão do AWS SDK; assim, não há arquivo de estado nem segredo. O servidor expõe cinco ferramentas:
test_destinationexecuta verificações de conectividade somente leitura. Se uma variável obrigatória não estiver definida, ele informa o nome exato da variável e retorna sem fazer nenhuma chamada à AWS.describe_schemaretorna o esquema do registro, o dialeto de consulta e o limite de linhas do destino configurado. Os agentes devem chamá-lo antes de escrever uma consulta.list_executionsfiltra por status, nome da função e intervalo de tempo, sem nenhuma linguagem de consulta envolvida. Isso resolve a maioria das perguntas.get_executionbusca um registro pelo ARN da execução.querytrata de perguntas que os filtros não conseguem expressar.
Você faz uma pergunta e o agente escolhe as ferramentas:
Quais steps em order-processor falharam com mais frequência nas últimas 24 horas e qual foi a contagem média de novas tentativas?
Nos destinos SQL, escreva cada consulta como uma instrução SELECT ou como uma instrução WITH que termina em um SELECT. Essas são as únicas formas que o servidor executa. Ele verifica uma consulta antes de fazer qualquer chamada à AWS, de modo que uma instrução que alteraria dados nunca chega ao seu destino. Nos destinos do CloudWatch Logs, a linguagem de consulta do Logs Insights não tem instruções que gravem dados. Dessa forma, toda consulta feita por meio do servidor é somente leitura.
Práticas recomendadas e considerações
Escolha operationDetail deliberadamente. O padrão, top-level, registra apenas as operações de nível superior e produz o mesmo conjunto de operações independentemente de quando um registro é emitido. full-tree inclui os filhos de contextos, como itens de map e ramificações de parallel, mas, por padrão, o backend de execução durável remove os filhos dos contextos finalizados do estado passado às invocações posteriores. Para manter a árvore completa durante uma suspensão e retomada, defina também pluginsConfig.childOperationsDepth em withDurableExecution. Essa preservação tem um custo: ela força uma passagem de replay sobre cada contexto preservado na retomada; por isso, ative apenas a profundidade de que você precisa.
Escolha nomes de operação que seu destino consiga consultar. O plugin usa os nomes literalmente como chaves e identificadores e nunca os sanitiza. Um . em um nome é um separador de caminho de campo no CloudWatch Logs Insights e no OpenSearch. Letras, dígitos, - e _ são portáveis em qualquer lugar.
Entenda o que o plugin não consegue ver. O Durable Execution Telemetry Exporter é executado dentro da sua função; por isso, só pode emitir registros quando a função é invocada. Estados terminais que se originam no serviço Lambda sem uma invocação nunca chegam ao plugin: STOPPED, a partir de uma parada manual, e TIMED_OUT, quando o tempo limite da execução é excedido. Para uma cobertura completa do ciclo de vida, assine os eventos de ciclo de vida de execução durável do Lambda no barramento padrão do Amazon EventBridge e atualize seu destino a partir de um pequeno handler:
Considere o custo do destino. O plugin adiciona no máximo uma exportação cada vez que emite um registro, porque envia apenas a mais recente de quaisquer atualizações acumuladas. Cada registro é um snapshot completo, e o mais recente substitui todos os anteriores. Se as atualizações chegarem mais rápido do que um exportador consegue processar, o plugin descarta os snapshots intermediários. As cobranças que importam são as que o seu destino gera: ingestão do CloudWatch Logs, gravações no DynamoDB, capacidade do Aurora e assim por diante. Combine samplingRate e emitMode para controlá-las.
Conclusão
O Durable Execution Telemetry Exporter oferece às funções duráveis do AWS Lambda um modelo de observabilidade que corresponde à forma como elas são executadas: um registro completo por execução, enviado a um destino adequado à sua equipe. O Durable Execution Telemetry MCP server permite que um agente de IA responda a perguntas diretamente sobre esses dados.
Para começar a usar funções duráveis, consulte o AWS Lambda Developer Guide. Para obter a referência completa de exportadores do plugin, as opções de configuração e uma stack do AWS Cloud Development Kit (AWS CDK) que implanta todos os destinos para teste, consulte o README do pacote.
Este conteúdo foi traduzido da publicação original do blog, que pode ser encontrada aqui.
Biografia do Autores
![]() |
Pooya Paridel é Senior Software Development Engineer na Amazon Web Services. |
Biografia do tradutores
![]() |
Daniel Abib é Arquiteto de Soluções Sênior e Especialista em Amazon Bedrock na AWS, com mais de 25 anos trabalhando com gerenciamento de projetos, arquiteturas de soluções escaláveis, desenvolvimento de sistemas e CI/CD, microsserviços, arquitetura Serverless & Containers e especialização em Machine Learning. Ele trabalha apoiando Startups, ajudando-os em sua jornada para a nuvem. https://www.linkedin.com/in/danielabib/ |
![]() |
Nicolas Tarzia é Senior Technical Account Manager na AWS, com mais de 13 anos de experiência, com ampla experiência em arquitetura cloud, engenharia e design de software. Atualmente está habilitando empresas do ramo de ISV (Independent Software Vendors) simplificando a operação na nuvem e otimizando os custos em cloud. Sua área de interesse são tecnologias serverless. https://www.linkedin.com/in/nicolastarzia |


