O blog da AWS

Apresentando o AWS Lambda Powertools para .NET

Por Amir Khairalomoum, Arquiteto Sênior de Soluções.

Aplicações modernas são construídas com padrões arquiteturais modulares, modelos operacionais Serverless e processos ágeis de desenvolvimento. Elas permitem que você inove mais rapidamente, reduza riscos, acelere o tempo de lançamento no mercado e diminua seu custo total de propriedade (TCO). Uma arquitetura de microsserviços compreende muitas partes distribuídas que podem introduzir complexidade à observabilidade da aplicação. A observabilidade moderna deve responder a essa complexidade, à frequência aumentada de implantações de software e à natureza efêmera dos ambientes de execução do AWS Lambda.

O Serverless Applications Lens para o AWS Well-Architected Framework concentra-se em como projetar, implantar e arquitetar suas cargas de trabalho de aplicações Serverless na Nuvem AWS. O AWS Lambda Powertools para .NET traduz algumas das melhores práticas definidas no Serverless lens em um conjunto de utilitários. Você pode usá-los em sua aplicação para aplicar registro estruturado, rastreamento distribuído e monitoramento de métricas.

Seguindo a adoção contínua da comunidade do AWS Lambda Powertools para Python, Java e TypeScript, o AWS Lambda Powertools para .NET está agora disponível de forma geral.

Esta publicação mostra como usar a nova biblioteca Powertools de código aberto para implementar melhores práticas de observabilidade com codificação mínima. Ele percorre os primeiros passos, com os exemplos fornecidos disponíveis no repositório GitHub do Powertools.

Sobre o Powertools

O Powertools para .NET é um conjunto de utilitários que ajuda na implementação de melhores práticas de observabilidade sem a necessidade de escrever código personalizado adicional. Atualmente, ele suporta funções Lambda escritas em C#, com suporte para versões de runtime .NET 6 e mais recentes. O Powertools fornece três utilitários principais:

  • Tracing fornece uma maneira mais simples de enviar rastreamentos de funções para o AWS X-Ray. Ele fornece visibilidade sobre chamadas de função, interações com outros serviços AWS ou solicitações HTTP externas. Você pode adicionar atributos aos rastreamentos para permitir filtragem com base em informações-chave. Por exemplo, ao usar o atributo Tracing, ele cria uma anotação ColdStart. Você pode facilmente agrupar e analisar rastreamentos para entender o processo de inicialização.
  • Logging fornece um logger personalizado que produz JSON estruturado. Ele permite que você passe strings ou objetos mais complexos, e cuida da serialização da saída de log. O logger lida com casos de uso comuns, como registrar a carga útil do evento Lambda e capturar informações de cold start. Isso inclui anexar chaves personalizadas ao logger.
  • Metrics simplifica a coleta de métricas personalizadas de sua aplicação, sem a necessidade de fazer solicitações síncronas para sistemas externos. Essa funcionalidade permite capturar métricas de forma assíncrona usando o Amazon CloudWatch Embedded Metric Format (EMF), o que reduz latência e custo. Isso fornece funcionalidade conveniente para casos comuns, como validar métricas contra a especificação CloudWatch EMF e rastrear cold starts.

Primeiros passos

As etapas a seguir explicam como usar o Powertools para implementar registro estruturado, adicionar métricas personalizadas e habilitar rastreamento com o AWS X-Ray. A aplicação de exemplo consiste em um endpoint do Amazon API Gateway, uma função Lambda e uma tabela do Amazon DynamoDB. Ela usa o AWS Serverless Application Model (AWS SAM) para gerenciar a implantação.

Quando você envia uma solicitação GET para o endpoint do API Gateway, a função Lambda é invocada. Esta função chama uma API de localização para encontrar o endereço IP, armazena-o na tabela DynamoDB e o retorna com uma mensagem de saudação para o cliente.

Example application

Aplicação de exemplo

Os utilitários do AWS Lambda Powertools para .NET estão disponíveis como pacotes NuGet. Cada utilitário principal tem um pacote NuGet separado. Isso permite que você adicione apenas os pacotes necessários. Isso ajuda a tornar o tamanho do pacote Lambda menor, o que pode melhorar o desempenho.

Para implementar cada um desses utilitários principais em um exemplo separado, use as seções Globals do template AWS SAM para configurar as variáveis de ambiente do Powertools e habilitar rastreamento ativo para todas as funções Lambda e estágios do Amazon API Gateway.

Às vezes, recursos que você declara em um template AWS SAM têm configurações comuns. Em vez de duplicar essas informações em cada recurso, você pode declará-las uma vez na seção Globals e deixar seus recursos herdá-las.

Logging

As etapas a seguir explicam como implementar registro estruturado em uma aplicação. O exemplo de logging mostra como usar o recurso de registro.

Para adicionar a biblioteca de logging do Powertools ao seu projeto, instale os pacotes da galeria NuGet, do editor do Visual Studio ou usando o seguinte comando .NET CLI:

dotnet add package AWS.Lambda.Powertools.Logging

Use variáveis de ambiente nas seções Globals do template AWS SAM para configurar a biblioteca de logging:

  Globals:
    Function:
      Environment:
        Variables:
          POWERTOOLS_SERVICE_NAME: powertools-dotnet-logging-sample
          POWERTOOLS_LOG_LEVEL: Debug
          POWERTOOLS_LOGGER_CASE: SnakeCase

Decore o método handler da função Lambda com o atributo Logging no código. Isso habilita o utilitário e permite que você use a funcionalidade Logger para produzir logs estruturados passando mensagens como uma string. Por exemplo:

[Logging]
public async Task<APIGatewayProxyResponse> FunctionHandler
         (APIGatewayProxyRequest apigProxyEvent, ILambdaContext context)
{
  ...
  Logger.LogInformation("Getting ip address from external service");
  var location = await GetCallingIp();
  ...
}

O Lambda envia a saída para o Amazon CloudWatch Logs como uma linha formatada em JSON.

{
  "cold_start": true,
  "xray_trace_id": "1-621b9125-0a3b544c0244dae940ab3405",
  "function_name": "powertools-dotnet-tracing-sampl-HelloWorldFunction-v0F2GJwy5r1V",
  "function_version": "$LATEST",
  "function_memory_size": 256,
  "function_arn": "arn:aws:lambda:eu-west-2:286043031651:function:powertools-dotnet-tracing-sample-HelloWorldFunction-v0F2GJwy5r1V",
  "function_request_id": "3ad9140b-b156-406e-b314-5ac414fecde1",
  "timestamp": "2022-02-27T14:56:39.2737371Z",
  "level": "Information",
  "service": "powertools-dotnet-sample",
  "name": "AWS.Lambda.Powertools.Logging.Logger",
  "message": "Getting ip address from external service"
}

Outro caso de uso comum, especialmente ao desenvolver novas funções Lambda, é imprimir um log do evento recebido pelo handler. Você pode conseguir isso habilitando LogEvent no atributo Logging. Isso é desabilitado por padrão para evitar potencialmente vazar dados sensíveis do evento nos logs.

[Logging(LogEvent = true)]
public async Task<APIGatewayProxyResponse> FunctionHandler
         (APIGatewayProxyRequest apigProxyEvent, ILambdaContext context)
{
  ...
}

Com logs disponíveis como JSON estruturado, você pode realizar pesquisas nesses dados estruturados usando o CloudWatch Logs Insights. Para pesquisar todos os logs que foram produzidos durante um cold start do Lambda e exibir os campos-chave na saída, execute a seguinte consulta:

fields coldStart='true'
| fields @timestamp, function_name, function_version, xray_trace_id
| sort @timestamp desc
| limit 20
CloudWatch Logs Insights query for cold starts

Consulta do CloudWatch Logs Insights para cold starts

Tracing

Usando o atributo Tracing, você pode instruir a biblioteca a enviar rastreamentos e metadados da invocação da função Lambda para o AWS X-Ray usando o AWS X-Ray SDK para .NET. O exemplo de tracing mostra como usar o recurso de rastreamento.

Quando sua aplicação faz chamadas para serviços AWS, o SDK rastreia chamadas downstream em subsegmentos. Serviços AWS que suportam rastreamento e recursos que você acessa dentro desses serviços aparecem como nós downstream no mapa de serviço no console do X-Ray.

Você pode instrumentar todos os seus clientes AWS SDK para .NET chamando RegisterXRayForAllServices antes de criá-los.

public class Function
{
  private static IDynamoDBContext _dynamoDbContext;
  public Function()
  {
    AWSSDKHandler.RegisterXRayForAllServices();
    ...
  }
  ...
}

Para adicionar a biblioteca de tracing do Powertools ao seu projeto, instale os pacotes da galeria NuGet, do editor do Visual Studio ou usando o seguinte comando .NET CLI:

dotnet add package AWS.Lambda.Powertools.Tracing

Use variáveis de ambiente nas seções Globals do template AWS SAM para configurar a biblioteca de tracing.

  Globals:
    Function:
      Tracing: Active
      Environment:
        Variables:
          POWERTOOLS_SERVICE_NAME: powertools-dotnet-tracing-sample
          POWERTOOLS_TRACER_CAPTURE_RESPONSE: true
          POWERTOOLS_TRACER_CAPTURE_ERROR: true

Decore o método handler da função Lambda com o atributo Tracing para habilitar o utilitário. Para fornecer detalhes mais granulares para seus rastreamentos, você pode usar o mesmo atributo para capturar a invocação de outras funções fora do handler. Por exemplo:

[Tracing]
public async Task<APIGatewayProxyResponse> FunctionHandler
         (APIGatewayProxyRequest apigProxyEvent, ILambdaContext context)
{
  ...
  var location = await GetCallingIp().ConfigureAwait(false);
  ...
}

[Tracing(SegmentName = "Location service")]
private static async Task<string?> GetCallingIp()
{
  ...
}

Uma vez que o tráfego esteja fluindo, você verá um mapa de serviço gerado no console do AWS X-Ray. Decorar o método handler da função Lambda, ou qualquer outro método na cadeia com o atributo Tracing, fornece uma visão geral de todo o tráfego fluindo pela aplicação.

AWS X-Ray trace service view

Visualização de serviço de rastreamento do AWS X-Ray

Você também pode visualizar os rastreamentos individuais que são gerados, juntamente com uma visualização em cascata dos segmentos e subsegmentos que compõem seu rastreamento. Esses dados podem ajudá-lo a identificar a causa raiz de operações lentas ou erros dentro de sua aplicação.

AWS X-Ray waterfall trace view

Visualização em cascata de rastreamento do AWS X-Ray

Você também pode filtrar rastreamentos por anotação e criar mapas de serviço personalizados com grupos de rastreamento do AWS X-Ray. Neste exemplo, use a expressão de filtro annotation.ColdStart = true para filtrar rastreamentos com base na anotação ColdStart. O atributo Tracing adiciona estes automaticamente quando usado dentro do método handler.

View trace attributes

Visualizar atributos de rastreamento

Metrics

O CloudWatch oferece várias métricas incluídas para ajudar a responder perguntas gerais sobre a taxa de transferência, taxa de erro e utilização de recursos da aplicação. No entanto, para entender melhor o comportamento da aplicação, você também deve adicionar métricas personalizadas relevantes para sua carga de trabalho.

O utilitário de métricas cria métricas personalizadas de forma assíncrona registrando métricas na saída padrão usando o Amazon CloudWatch Embedded Metric Format (EMF).

Na aplicação de exemplo, você deseja entender com que frequência seu serviço está chamando a API de localização para identificar os endereços IP. O exemplo de metrics mostra como usar o recurso de métricas.

Para adicionar a biblioteca de metrics do Powertools ao seu projeto, instale os pacotes da galeria NuGet, do editor do Visual Studio ou usando o seguinte comando .NET CLI:

dotnet add package AWS.Lambda.Powertools.Metrics

Use variáveis de ambiente nas seções Globals do template AWS SAM para configurar a biblioteca de métricas:

  Globals:
    Function:
      Environment:
        Variables:
          POWERTOOLS_SERVICE_NAME: powertools-dotnet-metrics-sample
          POWERTOOLS_METRICS_NAMESPACE: AWSLambdaPowertools

Para criar métricas personalizadas, decore a função Lambda com o atributo Metrics. Isso garante que todas as métricas sejam adequadamente serializadas e enviadas para os logs quando a função terminar sua invocação.

Você pode então emitir métricas personalizadas chamando AddMetric ou enviar uma única métrica com um namespace, serviço e dimensões personalizados chamando PushSingleMetric. Você também pode habilitar o CaptureColdStart no atributo para criar automaticamente uma métrica de cold start.

[Metrics(CaptureColdStart = true)]
public async Task<APIGatewayProxyResponse> FunctionHandler
         (APIGatewayProxyRequest apigProxyEvent, ILambdaContext context)
{
  ...
  // Add Metric to capture the amount of time
  Metrics.PushSingleMetric(
        metricName: "CallingIP",
        value: 1,
        unit: MetricUnit.Count,
        service: "lambda-powertools-metrics-example",
        defaultDimensions: new Dictionary<string, string>
        {
            { "Metric Type", "Single" }
        });
  ...
}

Conclusão

O CloudWatch e o AWS X-Ray oferecem funcionalidade que fornece observabilidade abrangente para suas aplicações. O Lambda Powertools .NET está agora disponível de forma geral. A biblioteca ajuda a implementar observabilidade ao executar funções Lambda baseadas em .NET 6, reduzindo a quantidade de código personalizado.

Ele simplifica a implementação das melhores práticas de observabilidade definidas no Serverless Applications Lens para o AWS Well-Architected Framework para uma aplicação Serverless e permite que você concentre mais tempo na lógica de negócios.

Você pode encontrar a documentação completa e o código-fonte do Powertools no GitHub. Recebemos contribuições via pull request e encorajamos você a criar uma issue se tiver algum feedback para o projeto. Boa construção com o AWS Lambda Powertools para .NET.

Para mais recursos de aprendizado sobre Serverless, visite o Serverless Land.

Este conteúdo foi traduzido do post original do blog, que pode ser encontrado aqui.

Tradutores

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. Sua área de interesse são tecnologias serverless.
https://www.linkedin.com/in/nicolastarzia
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/