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:

{
  "recordType": "DurableExecutionTelemetry",
  "schemaVersion": "1.0",
  "executionArn": "arn:aws:lambda:us-east-1:111122223333:function:order-processor:$LATEST/durable-execution/abc123/inv456",
  "executionName": "abc123",
  "functionName": "order-processor",
  "status": "SUCCEEDED",
  "startTime": "2026-06-16T17:00:22.100Z",
  "endTime": "2026-06-16T17:00:27.514Z",
  "durationMs": 5414,
  "input": { "orderId": "order-12345", "customerId": "cust-789" },
  "output": { "orderId": "order-12345", "status": "completed", "charged": 99.99 },
  "operations": [
    { "name": "validate-order",  "type": "STEP", "status": "SUCCEEDED", "durationMs": 250 },
    { "name": "check-inventory", "type": "STEP", "status": "SUCCEEDED", "durationMs": 350 },
    { "name": "cool-down",       "type": "WAIT", "status": "SUCCEEDED", "durationMs": 5000 },
    { "name": "charge-payment",  "type": "STEP", "status": "SUCCEEDED", "durationMs": 80 }
  ]
}

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:

npm install @aws/durable-execution-sdk-js-telemetry-exporter

Em seguida, passe-o para withDurableExecution:

import { DurableContext, withDurableExecution } from "@aws/durable-execution-sdk-js";
import { durableExecutionTelemetry } from "@aws/durable-execution-sdk-js-telemetry-exporter";

const handler = async (event: OrderEvent, context: DurableContext) => {
  const order = await context.step("validate-order", async () =>
    validateOrder(event.orderId),
  );

  const inventory = await context.step("check-inventory", async () =>
    reserveInventory(order),
  );

  await context.wait({ seconds: 30 });

  return await context.step("charge-payment", async () =>
    chargeCustomer(order, inventory),
  );
};

export const lambdaHandler = withDurableExecution(handler, {
  plugins: [durableExecutionTelemetry({})],
});

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:

fields executionName, status, durationMs
| filter recordType = "DurableExecutionTelemetry" and status = "FAILED"
| sort durationMs desc

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:

import {
  durableExecutionTelemetry,
  S3Exporter,
  DynamoDBExporter,
  EventBridgeExporter,
} from "@aws/durable-execution-sdk-js-telemetry-exporter";

const telemetry = durableExecutionTelemetry({
  emitMode: "on-complete",
  samplingRate: 1.0,
  exporters: [
    new S3Exporter({ bucket: string }), // Use valid bucket name you own
    new DynamoDBExporter({ tableName: "durable-execution-telemetry-live" }),
    new EventBridgeExporter({}),
  ],
});

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:

SELECT op.name, COUNT(*) AS failures, AVG(op.durationms) AS avg_ms
FROM durable_execution_telemetry
CROSS JOIN UNNEST(operations) AS t(op)
WHERE status = 'FAILED' AND year = '2026' AND month = '06'
GROUP BY op.name
ORDER BY failures DESC;

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:

const telemetry = durableExecutionTelemetry({
  samplingRate: 0.1,
  content: {
    input: (event) => ({ orderId: event.orderId }),
    output: (result) => ({ status: result.status }),
  },
});

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:

kiro-cli mcp add \
  --name durable-telemetry \
  --command npx \
  --args "-y,@aws/durable-execution-sdk-js-telemetry-mcp" \
  --env DURABLE_TELEMETRY_DESTINATION_TYPE=dynamodb \
  --env DURABLE_TELEMETRY_DYNAMODB_TABLE_NAME=durable-execution-telemetry-live \
  --env DURABLE_TELEMETRY_REGION=us-east-1 \
  --scope workspace

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_destination executa 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_schema retorna 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_executions filtra por status, nome da função e intervalo de tempo, sem nenhuma linguagem de consulta envolvida. Isso resolve a maioria das perguntas.
  • get_execution busca um registro pelo ARN da execução.
  • query trata 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:

{
  "source": ["aws.lambda"],
  "detail-type": ["Lambda Durable Execution State Change"],
  "detail": { "status": ["STOPPED", "TIMED_OUT"] }
}

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