# Instrumentar o código C \$1 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)](https://aws.amazon.com/otel): uma distribuição segura, pronta para produção e com suporte na AWS do SDK OpenTelemetry (OTel). + [AWS X-Ray SDK for .NET](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-dotnet.html) – um SDK para geração e envio de dados de rastreamento ao X-Ray. + [Powertools para AWS Lambda (.NET)](https://docs.aws.amazon.com/powertools/dotnet/): 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](https://docs.aws.amazon.com/xray/latest/devguide/xray-instrumenting-your-app.html#xray-instrumenting-choosing). **Topics** + [Uso do Powertools para AWS Lambda (.NET) e do AWS SAM para rastreamento](#dotnet-tracing-sam) + [Uso do SDK do X-Ray para instrumentar suas funções do .NET](#dotnet-xray-sdk) + [Ativar o rastreamento com o console do Lambda](#dotnet-tracing-console) + [Ativar o rastreamento com a API do Lambda](#dotnet-tracing-api) + [Ativar o rastreamento com o CloudFormation](#dotnet-tracing-cloudformation) + [Interpretar um rastreamento do X-Ray](#dotnet-tracing-interpretation) ## 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\$1 Hello World com os módulos integrados do [Powertools para AWS Lambda (.NET)](https://docs.powertools.aws.dev/lambda-dotnet) usando o AWS SAM. Esta aplicação implementa um backend 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 8 + [AWS CLI versão 2](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) + [AWS SAM CLI versão 1.75 ou posterior](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/serverless-sam-cli-install.html). Se você tiver uma versão mais antiga da CLI do AWS SAM, consulte [Atualizando a CLI do AWS SAM](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/manage-sam-cli-versions.html#manage-sam-cli-versions-upgrade). **Implantar uma aplicação de exemplo do AWS SAM** 1. 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 ``` 1. Crie a aplicação. ``` cd sam-app && sam build ``` 1. Implante o aplicativo. ``` sam deploy --guided ``` 1. 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`. 1. Obtenha o URL da aplicação implantada: ``` aws cloudformation describe-stacks --stack-name sam-app --query 'Stacks[0].Outputs[?OutputKey==`HelloWorldApi`].OutputValue' --output text ``` 1. Invoque o endpoint da API: ``` curl ``` Se tiver êxito, você verá esta resposta: ``` {"message":"hello world"} ``` 1. Para obter os rastreamentos da função, execute [sam traces](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/sam-cli-command-reference-sam-traces.html). ``` 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 ``` 1. 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. Você não pode 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. ``` net8.0 true Lambda ``` 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](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-dotnet.html) 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 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** 1. Abra a [página Funções](https://console.aws.amazon.com/lambda/home#/functions) do console do Lambda. 1. Escolha uma função. 1. Escolha **Configuration** (Configuração) e depois **Monitoring and operations tools** (Ferramentas de monitoramento e operações). 1. Em **Ferramentas de monitoramento adicionais**, selecione **Editar**. 1. Em **CloudWatch Application Signals e AWS X-Ray**, escolha **Habilitar** para **Rastreamentos do serviço Lambda**. 1. Escolha **Salvar**. ## Ativar o rastreamento com a API do Lambda Configure o rastreamento na sua função do Lambda com a AWS CLI ou o AWS SDK, usando as seguintes operações de API: + [UpdateFunctionConfiguration](https://docs.aws.amazon.com/lambda/latest/api/API_UpdateFunctionConfiguration.html) + [GetFunctionConfiguration](https://docs.aws.amazon.com/lambda/latest/api/API_GetFunctionConfiguration.html) + [CreateFunction](https://docs.aws.amazon.com/lambda/latest/api/API_CreateFunction.html) 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 CloudFormation Para ativar o rastreamento ativo em um recurso `AWS::Lambda::Function` em um modelo do CloudFormation, use a propriedade `TracingConfig`. **Example [function-inline.yml](https://github.com/awsdocs/aws-lambda-developer-guide/blob/master/templates/function-inline.yml): configuração de rastreamento** ``` Resources: function: Type: [AWS::Lambda::Function](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-lambda-function.html) Properties: TracingConfig: Mode: Active ... ``` Para um recurso do AWS Serverless Application Model (AWS SAM) `AWS::Serverless::Function`, use a propriedade `Tracing`. **Example [template.yml](https://github.com/awsdocs/aws-lambda-developer-guide/tree/main/sample-apps/blank-nodejs/template.yml): configuração de rastreamento** ``` Resources: function: Type: [AWS::Serverless::Function](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/sam-resource-function.html) 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](lambda-intro-execution-role.md) da função. Caso contrário, adicione a política [AWSXRayDaemonWriteAccess](https://console.aws.amazon.com/iam/home#/policies/arn:aws:iam::aws:policy/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](https://docs.aws.amazon.com/xray/latest/devguide/aws-xray.html#xray-concepts-servicegraph) exibe informações sobre sua aplicação e todos os componentes. O exemplo a seguir mostra uma aplicação 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. ![\[\]](http://docs.aws.amazon.com/pt_br/lambda/latest/dg/images/sample-errorprocessor-servicemap.png) 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. Você não pode configurar a taxa de amostragem do X-Ray para suas funções. No X-Ray, um *rastreamento* registra informações sobre uma solicitação que é processada por um ou mais *serviços*. O Lambda registra dois segmentos por rastreamento, o que cria dois nós no gráfico de serviços. A imagem a seguir destaca esses dois nós: ![\[\]](http://docs.aws.amazon.com/pt_br/lambda/latest/dg/images/xray-servicemap-function.png) 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`. Se o segmento `AWS::Lambda` mostrar um erro, o serviço Lambda teve um problema. Se o segmento `AWS::Lambda::Function` mostrar um erro, sua função teve um problema. ![\[\]](http://docs.aws.amazon.com/pt_br/lambda/latest/dg/images/V2_sandbox_images/my-function-2-v1.png) Este exemplo expande o segmento `AWS::Lambda::Function` para mostrar seus três subsegmentos. **nota** A AWS atualmente está implementando alterações no serviço Lambda. Devido a essas alterações, você pode ver pequenas diferenças entre a estrutura e o conteúdo das mensagens de log do sistema e os segmentos de rastreamento emitidos por diferentes funções do Lambda na sua Conta da AWS. O exemplo de rastreamento mostrado aqui ilustra o segmento de função no estilo antigo. As diferenças entre os segmentos no estilo antigo e no estilo novo são descritas nos próximos parágrafos. Essas alterações serão implementadas durante as próximas semanas, e todas as funções em todas as Regiões da AWS, exceto nas regiões China e GovCloud, passarão a usar o novo formato de mensagens de log e segmentos de rastreamento. O segmento de função no estilo antigo contém os seguintes subsegmentos: + **Inicialização**: representa o tempo gasto carregando a função e executando o [código de inicialização](foundation-progmodel.md). 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. O segmento de função no estilo novo não contém um subsegmento `Invocation`. Em vez disso, os subsegmentos dos clientes são anexados diretamente ao segmento da função. Para obter mais informações sobre a estrutura dos segmentos de função no estilo antigo e no estilo novo, consulte [Noções básicas sobre rastreamentos do X-Ray](services-xray.md#services-xray-traces). 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](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-dotnet.html) no *Guia do desenvolvedor do AWS X-Ray*. **Preços** 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çoAWS X-Ray](https://aws.amazon.com/xray/pricing/).