Uso do Powertools para AWS Lambda (.NET) e do AWS SAM para rastreamento Uso do SDK do X-Ray para instrumentar suas funções do .NET Ativar o rastreamento com o console do Lambda Ativar o rastreamento com a API do Lambda Ativar o rastreamento com o AWS CloudFormation Interpretar um rastreamento do X-Ray

Instrumentar o código C # no AWS Lambda

O Lambda se integra ao AWS X-Ray para ajudar você a rastrear, depurar e otimizar aplicações do Lambda. É possível usar o X-Ray para rastrear uma solicitação enquanto ela atravessa recursos na aplicação, o que pode incluir funções Lambda e outros produtos da AWS.

Para enviar dados de rastreamento ao X-Ray, é possível usar uma das três bibliotecas SDK:

AWS Distro for OpenTelemetry (ADOT): uma distribuição segura, pronta para produção e com suporte na AWS do SDK OpenTelemetry (OTel).
AWS X-Ray SDK for .NET: um SDK para geração e envio de dados de rastreamento ao X-Ray.
Powertools para AWS Lambda (.NET): um kit de ferramentas para desenvolvedores para implementar práticas recomendadas de tecnologia sem servidor e aumentar a velocidade do desenvolvedor.

Cada um dos SDKs oferece maneiras de enviar dados de telemetria ao serviço do X-Ray. Em seguida, é possível usar o X-Ray para visualizar, filtrar e obter insights sobre as métricas de performance da aplicação para identificar problemas e oportunidades de otimização.

Importante

Os SDKs do X-Ray e do Powertools para AWS Lambda fazem parte de uma solução de instrumentação totalmente integrada oferecida pela AWS. As camadas do Lambda para ADOT fazem parte de um padrão em todo o setor para instrumentação de rastreamento que coleta mais dados em geral, mas pode não ser adequado para todos os casos de uso. É possível implementar o rastreamento de ponta a ponta no X-Ray usando ambas as soluções. Para saber mais sobre como escolher entre elas, consulte Como escolher entre os SDKs do AWS Distro para OpenTelemetry e do X-Ray.

Seções

Uso do Powertools para AWS Lambda (.NET) e do AWS SAM para rastreamento
Uso do SDK do X-Ray para instrumentar suas funções do .NET
Ativar o rastreamento com o console do Lambda
Ativar o rastreamento com a API do Lambda
Ativar o rastreamento com o AWS CloudFormation
Interpretar um rastreamento do X-Ray

Uso do Powertools para AWS Lambda (.NET) e do AWS SAM para rastreamento

Siga as etapas abaixo para baixar, criar e implantar um exemplo de aplicação C# Hello World com os módulos integrados do Powertools para AWS Lambda (.NET) usando o AWS SAM. Esta aplicação implementa um back-end de API básico e usa o Powertools para emitir logs, métricas e rastreamentos. Consiste em um endpoint do Amazon API Gateway e uma função do Lambda. Quando você envia uma solicitação GET ao endpoint do API Gateway, a função do Lambda invoca, envia logs e métricas usando o formato de métricas incorporadas ao CloudWatch e envia rastreamentos ao AWS X-Ray. A função retorna uma mensagem de hello world.

Pré-requisitos

Para executar as etapas desta seção, você deve ter o seguinte:

.NET 6 ou .NET 8
AWS CLI versão 2
AWS SAM CLI versão 1.75 ou posterior. Se você tiver uma versão mais antiga da CLI do AWS SAM, consulte Atualizando a CLI do AWS SAM.

Implantar uma aplicação de exemplo do AWS SAM

Inicialize a aplicação usando o modelo Hello World TypeScript.


sam init --app-template hello-world-powertools-dotnet --name sam-app --package-type Zip --runtime dotnet6 --no-tracing

Crie a aplicação.
```
cd sam-app && sam build
```
Implante o aplicativo.
```
sam deploy --guided
```
Siga as instruções na tela. Para aceitar as opções padrão fornecidas na experiência interativa, pressione Enter.

nota
Em HelloWorldFunction pode não ter autorização definida, tudo bem?, certifique-se de inserir y.

Obtenha o URL da aplicação implantada:


aws cloudformation describe-stacks --stack-name sam-app --query 'Stacks[0].Outputs[?OutputKey==`HelloWorldApi`].OutputValue' --output text

Invoque o endpoint da API:
```
curl <URL_FROM_PREVIOUS_STEP>
```
Se tiver êxito, você verá esta resposta:
```
{"message":"hello world"}
```

Para obter os rastreamentos da função, execute sam traces.


sam traces

A saída de rastreamento se parece com:


New XRay Service Graph
  Start time: 2023-02-20 23:05:16+08:00
  End time: 2023-02-20 23:05:16+08:00
  Reference Id: 0 - AWS::Lambda - sam-app-HelloWorldFunction-pNjujb7mEoew - Edges: [1]
   Summary_statistics:
     - total requests: 1
     - ok count(2XX): 1
     - error count(4XX): 0
     - fault count(5XX): 0
     - total response time: 2.814
  Reference Id: 1 - AWS::Lambda::Function - sam-app-HelloWorldFunction-pNjujb7mEoew - Edges: []
   Summary_statistics:
     - total requests: 1
     - ok count(2XX): 1
     - error count(4XX): 0
     - fault count(5XX): 0
     - total response time: 2.429
  Reference Id: 2 - (Root) AWS::ApiGateway::Stage - sam-app/Prod - Edges: [0]
   Summary_statistics:
     - total requests: 1
     - ok count(2XX): 1
     - error count(4XX): 0
     - fault count(5XX): 0
     - total response time: 2.839
  Reference Id: 3 - client - sam-app/Prod - Edges: [2]
   Summary_statistics:
     - total requests: 0
     - ok count(2XX): 0
     - error count(4XX): 0
     - fault count(5XX): 0
     - total response time: 0

XRay Event [revision 3] at (2023-02-20T23:05:16.521000) with id (1-63f38c2c-270200bf1d292a442c8e8a00) and duration (2.877s)
 - 2.839s - sam-app/Prod [HTTP: 200]
   - 2.836s - Lambda [HTTP: 200]
 - 2.814s - sam-app-HelloWorldFunction-pNjujb7mEoew [HTTP: 200]
 - 2.429s - sam-app-HelloWorldFunction-pNjujb7mEoew
   - 0.230s - Initialization
   - 2.389s - Invocation
     - 0.600s - ## FunctionHandler
       - 0.517s - Get Calling IP
   - 0.039s - Overhead

Este é um endpoint de API pública que é acessado pela Internet. Recomendamos excluir o endpoint após o teste.
```
sam delete
```

O X-Ray não rastreia todas as solicitações para sua aplicação. O X-Ray aplica um algoritmo de amostragem para garantir que o rastreamento seja eficiente, enquanto ainda fornece uma amostra representativa das solicitações. A taxa de amostragem é uma solicitação por segundo e 5% de solicitações adicionais.

nota

Não é possível configurar a taxa de amostragem do X-Ray para suas funções.

Uso do SDK do X-Ray para instrumentar suas funções do .NET

É possível instrumentar seu código de função para gravar metadados e rastrear chamadas downstream. Para registrar detalhes sobre as chamadas que a função faz para outros recursos e serviços, use o AWS X-Ray SDK for .NET. Para obter o SDK, adicione os pacotes AWSXRayRecorder ao arquivo do projeto.


<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net8.0</TargetFramework>
    <GenerateRuntimeConfigurationFiles>true</GenerateRuntimeConfigurationFiles>
    <AWSProjectType>Lambda</AWSProjectType>
  </PropertyGroup>
  <ItemGroup>
    <PackageReference Include="Amazon.Lambda.Core" Version="2.1.0" />
    <PackageReference Include="Amazon.Lambda.SQSEvents" Version="2.1.0" />
    <PackageReference Include="Amazon.Lambda.Serialization.Json" Version="2.1.0" />
    <PackageReference Include="AWSSDK.Core" Version="3.7.103.24" />
    <PackageReference Include="AWSSDK.Lambda" Version="3.7.104.3" />
    <PackageReference Include="AWSXRayRecorder.Core" Version="2.13.0" />
    <PackageReference Include="AWSXRayRecorder.Handlers.AwsSdk" Version="2.11.0" />
  </ItemGroup>
</Project>

Há uma variedade de pacotes Nuget que fornecem auto-instrumentação automática para os SDKs da AWS, Entity Framework e solicitações HTTP. Para ver o conjunto completo de opções de configuração, consulte AWS X-Ray SDK for .NET no AWS X-Ray Developer Guide.

Depois de adicionar os pacotes Nuget desejados, configure a instrumentação automática. A prática recomendada é realizar essa configuração fora da função de manipulador da função. Isso permite que você aproveite a reutilização do ambiente de execução para melhorar o desempenho da função. No exemplo de código a seguir, o método RegisterXRayForAllServices é chamado no construtor da função para adicionar instrumentação a todas as chamadas do SDK da AWS.


[assembly: LambdaSerializer(typeof(Amazon.Lambda.Serialization.SystemTextJson.DefaultLambdaJsonSerializer))]

namespace GetProductHandler;

public class Function
{
    private readonly IDatabaseRepository _repo;
    
    public Function()
    {
        // Add auto instrumentation for all AWS SDK calls
        // It is important to call this method before initializing any SDK clients
        AWSSDKHandler.RegisterXRayForAllServices();
        this._repo = new DatabaseRepository();
    }
    
    public async Task<APIGatewayProxyResponse> FunctionHandler(APIGatewayProxyRequest request)
    {
        var id = request.PathParameters["id"];
        
        var databaseRecord = await this._repo.GetById(id);
        
        return new APIGatewayProxyResponse 
        {
            StatusCode = (int)HttpStatusCode.OK,
            Body = JsonSerializer.Serialize(databaseRecord)
        };
    }
}

Ativar o rastreamento com o console do Lambda

Para alternar o rastreamento ativo na sua função do Lambda usando o console, siga as etapas abaixo:

Para ativar o rastreamento ativo

Abra a página Funções do console do Lambda.
Escolha uma função.
Escolha Configuration (Configuração) e depois Monitoring and operations tools (Ferramentas de monitoramento e operações).
Selecione a opção Editar.
Em X-Ray, ative a opção Active tracing (Rastreamento ativo).
Escolha Salvar.

Ativar o rastreamento com a API do Lambda

Configure o rastreamento na sua função do Lambda com aAWS CLI ou o AWS SDK, usando as seguintes operações de API:

O exemplo de comando da AWS CLI a seguir habilita o rastreamento ativo em uma função chamada my-function.


aws lambda update-function-configuration --function-name my-function \
--tracing-config Mode=Active

O modo de rastreamento faz parte da configuração específica da versão quando você publica uma versão da função. Não é possível alterar o modo de rastreamento em uma versão publicada.

Ativar o rastreamento com o AWS CloudFormation

Para ativar o rastreamento ativo em um recurso AWS::Lambda::Function em um modelo do AWS CloudFormation, use a propriedade TracingConfig.

exemplo function-inline.yml: configuração de rastreamento


Resources:
  function:
    Type: AWS::Lambda::Function
    Properties:
      TracingConfig:
        Mode: Active
      ...

Para um recurso do AWS Serverless Application Model (AWS SAM) AWS::Serverless::Function, use a propriedade Tracing.

exemplo template.yml: configuração de rastreamento


Resources:
  function:
    Type: AWS::Serverless::Function
    Properties:
      Tracing: Active
      ...

Interpretar um rastreamento do X-Ray

Sua função precisa de permissão para carregar dados de rastreamento no X-Ray. Quando você ativa o rastreamento ativo no console do Lambda, o Lambda adiciona as permissões necessárias à função de execução da função. Caso contrário, adicione a política AWSXRayDaemonWriteAccess à função de execução.

Após configurar o rastreamento ativo, você pode observar solicitações específicas por meio da aplicação. O grafo de serviço do X-Ray exibe informações sobre sua aplicação e todos os componentes. O exemplo a seguir do aplicativo de exemplo processador de erros mostra um aplicativo com duas funções. A função principal processa eventos e, às vezes, retorna erros. A segunda função de cima para baixo processa erros que aparecem no primeiro grupo de logs e usa o AWS SDK para chamar o X-Ray, o Amazon Simple Storage Service (Amazon S3) e o Amazon CloudWatch Logs.

Um diagrama que mostra duas aplicações separadas e seus respectivos mapas de serviço no X-Ray

nota

Não é possível configurar a taxa de amostragem do X-Ray para suas funções.

Ao usar o rastreamento ativo, o Lambda registra dois segmentos por rastreamento, o que cria dois nós no grafo de serviços. A imagem a seguir destaca estes dois nós para a função primária da exemplo de aplicação do processador de erros.

Um mapa de serviço do X-Ray com uma única função.

O primeiro nó à esquerda representa o serviço do Lambda, que recebe a solicitação de invocação. O segundo nó representa a sua função do Lambda específica. O exemplo a seguir mostra um rastreamento com esses dois segmentos. Ambos têm o nome my-function, mas um tem a origem AWS::Lambda e o outro, a origem AWS::Lambda::Function.

Um rastreamento do X-Ray que mostra latência em cada subsegmento de uma invocação específica do Lambda.

Este exemplo expande o segmento de função para mostrar seus três subsegmentos:

Inicialização: representa o tempo gasto carregando a função e executando o código de inicialização. Esse subsegmento aparece somente para o primeiro evento que cada instância da função processa.
Invocação: representa o tempo gasto na execução do código do manipulador.
Sobrecarga: representa o tempo gasto pelo runtime do Lambda preparando-se para lidar com o próximo evento.

Você também pode instrumentar clientes HTTP, registrar consultas SQL e criar subsegmentos personalizados com anotações e metadados. Para obter mais informações, consulte AWS X-Ray SDK for .NET no Guia do desenvolvedor do AWS X-Ray.

Definição de preço

Você pode usar o rastreamento do X-Ray gratuitamente todos os meses até determinado limite como parte do nível gratuito da AWS. Além do limite, o X-Ray cobra por armazenamento e recuperação de rastreamento. Para obter mais informações, consulte Definição de preços do AWS X-Ray.

Atenção O Javascript está desativado ou não está disponível no seu navegador.

Para usar a documentação da AWS, o Javascript deve estar ativado. Consulte as páginas de Ajuda do navegador para obter instruções.

Convenções do documento

Erros

Testar