As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.
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:
-
AWSDistro for OpenTelemetry (ADOT)
— Uma distribuição segura, pronta para produção e AWS suportada do SDK (OTel). OpenTelemetry -
AWS X-Ray SDK for Node.js: 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. Você pode implementar o end-to-end rastreamento no X-Ray usando qualquer uma das 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
- Usar o ADOT para instrumentar funções do Node.js
- Usar o SDK do X-Ray para instrumentar suas funções Node.js
- 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
- Armazenar dependências de runtime em uma camada (SDK do X-Ray)
Usar o ADOT para instrumentar funções do Node.js
O ADOT fornece camadas 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
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 AWSDistro for OpenTelemetry Lambda JavaScript Support for
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.
exemplo blank-nodejs/package.json
{ "name": "blank-nodejs", "version": "1.0.0", "private": true, "devDependencies": { "aws-sdk": "2.631.0", "jest": "25.4.0" }, "dependencies": {
"aws-xray-sdk-core": "1.1.2"
}, "scripts": { "test": "jest" } }
Para instrumentar clientes do AWS SDK, encapsule a biblioteca aws-sdk
com o método captureAWS
.
exemplo blank-nodejs/function/index.js : rastrear um cliente do AWS SDK
const AWSXRay = require('aws-xray-sdk-core') const AWS = AWSXRay.captureAWS(require('aws-sdk'))
// Create client outside of handler to reuse const lambda = new AWS.Lambda() // 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.
exemplo 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 ter mais informações, consulte Como usar variáveis de ambiente do Lambda.
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
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 AWSXRayDaemonWriteAccess
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 na parte superior processa os erros que aparecem no grupo de registros da primeira e usa o AWS SDK para chamar o X-Ray, o Amazon Simple Storage Service (Amazon S3) e o Amazon Logs. CloudWatch
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.
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.
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
.
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 Node.js 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
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.
O exemplo a seguir mostra um recurso AWS::Serverless::LayerVersion
que armazena o AWS X-Ray SDK for Node.js.
exemplo template.yml : camada de dependências
Resources: function: Type: AWS::Serverless::Function Properties: CodeUri: function/. Tracing: Active
Layers: - !Ref libs
...libs: Type: AWS::Serverless::LayerVersion Properties: LayerName: blank-nodejs-lib Description: Dependencies for the blank sample app. ContentUri: lib/. CompatibleRuntimes: - nodejs16.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