# Instrumentação do código Node.js 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, você pode usar uma das duas 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 Node.js](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-nodejs.html) – um SDK para geração e envio de dados de rastreamento ao X-Ray. 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** + [Usar o ADOT para instrumentar funções do Node.js](#nodejs-adot) + [Usar o SDK do X-Ray para instrumentar suas funções Node.js](#nodejs-xray-sdk) + [Ativar o rastreamento com o console do Lambda](#nodejs-tracing-console) + [Ativar o rastreamento com a API do Lambda](#nodejs-tracing-api) + [Ativar o rastreamento com o CloudFormation](#nodejs-tracing-cloudformation) + [Interpretar um rastreamento do X-Ray](#nodejs-tracing-interpretation) + [Armazenar dependências de runtime em uma camada (SDK do X-Ray)](#nodejs-tracing-layers) ## Usar o ADOT para instrumentar funções do Node.js O ADOT fornece [camadas](chapter-layers.md) do Lambda totalmente gerenciadas que empacotam tudo o que você precisa para coletar dados de telemetria usando o SDK do OTel. Ao consumir essa camada, é possível instrumentar suas funções Lambda sem precisar modificar nenhum código de função. Você também pode configurar sua camada para fazer a inicialização personalizada do OTel. Para obter mais informações, consulte [Custom configuration for the ADOT Collector on Lambda](https://aws-otel.github.io/docs/getting-started/lambda#custom-configuration-for-the-adot-collector-on-lambda) (Configuração personalizada para o ADOT Collector no Lambda) na documentação do ADOT. Para runtimes Node.js, você pode adicionar a **camada do Lambda gerenciada pela AWS para ADOT Javascript** a fim de instrumentar suas funções automaticamente. Para obter instruções detalhadas sobre como adicionar essa camada, consulte [Suporte do AWS Distro for OpenTelemetry Lambda para JavaScript](https://aws-otel.github.io/docs/getting-started/lambda/lambda-js), na documentação do ADOT. ## Usar o SDK do X-Ray para instrumentar suas funções Node.js Para registrar detalhes sobre as chamadas feitas pela sua função do Lambda para outros recursos na sua aplicação, você também pode usar o AWS X-Ray SDK for Node.js. Para obter o SDK, adicione o pacote `aws-xray-sdk-core` às dependências do aplicativo. **Example [blank-nodejs/package.json](https://github.com/awsdocs/aws-lambda-developer-guide/tree/main/sample-apps/blank-nodejs/package.json)** ``` { "name": "blank-nodejs", "version": "1.0.0", "private": true, "devDependencies": { "jest": "29.7.0" }, "dependencies": { "@aws-sdk/client-lambda": "3.345.0", "aws-xray-sdk-core": "3.5.3" }, "scripts": { "test": "jest" } } ``` Para instrumentar clientes do AWS SDK no [AWS SDK para JavaScript v3](https://docs.aws.amazon.com/sdk-for-javascript/v3/developer-guide/welcome.html), envolva a instância do cliente com o método `captureAWSv3Client`. **Example [blank-nodejs/function/index.js](https://github.com/awsdocs/aws-lambda-developer-guide/tree/main/sample-apps/blank-nodejs/function/index.js): rastrear um cliente do AWS SDK** ``` const AWSXRay = require('aws-xray-sdk-core'); const { LambdaClient, GetAccountSettingsCommand } = require('@aws-sdk/client-lambda'); // Create client outside of handler to reuse const lambda = AWSXRay.captureAWSv3Client(new LambdaClient()); // Handler exports.handler = async function(event, context) { event.Records.forEach(record => { ... ``` O runtime do Lambda define algumas variáveis de ambiente para configurar o X-Ray SDK. Por exemplo, o Lambda define `AWS_XRAY_CONTEXT_MISSING` como `LOG_ERROR` para evitar lançar erros de runtime no X-Ray SDK. Para definir uma estratégia de contexto ausente personalizada, substitua a variável de ambiente na configuração da função para que ela não tenha valores e, depois, defina a estratégia de contexto ausente de forma programática. **Example Exemplo de código de inicialização** ``` const AWSXRay = require('aws-xray-sdk-core'); // Configure the context missing strategy to do nothing AWSXRay.setContextMissingStrategy(() => {}); ``` Para obter mais informações, consulte [Trabalhar com variáveis de ambiente no Lambda](configuration-envvars.md). Depois de adicionar as dependências corretas e fazer as devidas mudanças de código, ative o rastreamento na configuração da sua função usando o console do Lambda ou a API. ## 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 Node.js](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-nodejs.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 [Preços do AWS X-Ray](https://aws.amazon.com/xray/pricing/). ## Armazenar dependências de runtime em uma camada (SDK do X-Ray) Se você usar o X-Ray SDK para instrumentar os clientes do AWS SDK com seu código de função, seu pacote de implantação poderá se tornar bastante grande. Para evitar o upload de dependências de runtime todas as vezes que você atualizar seu código de função, empacote o SDK do X-Ray em uma [camada do Lambda](chapter-layers.md). O exemplo a seguir mostra um recurso `AWS::Serverless::LayerVersion` que armazena o AWS X-Ray SDK for Node.js. **Example [template.yml](https://github.com/awsdocs/aws-lambda-developer-guide/tree/main/sample-apps/blank-nodejs/template.yml): camada de dependências** ``` Resources: function: Type: [AWS::Serverless::Function](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/sam-resource-function.html) Properties: CodeUri: function/. Tracing: Active Layers: - !Ref libs ... libs: Type: [AWS::Serverless::LayerVersion](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/sam-resource-layerversion.html) Properties: LayerName: blank-nodejs-lib Description: Dependencies for the blank sample app. ContentUri: lib/. CompatibleRuntimes: - nodejs24.x ``` Com essa configuração, você atualizará a camada de biblioteca somente se alterar as dependências de runtime. Já que o pacote de implantação de função inclui apenas o seu código, isso pode ajudar a reduzir o tempo de upload. A criação de uma camada de dependências requer alterações de compilação para gerar o arquivo da camada antes da implantação. Para obter um exemplo funcional, consulte o aplicativo de exemplo [blank-nodejs](https://github.com/awsdocs/aws-lambda-developer-guide/tree/main/sample-apps/blank-nodejs) .