# Como rastrear o código TypeScript 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).
+ [SdK do AWS X-Ray para 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.
+ [Powertools para AWS Lambda (TypeScript)](https://docs.aws.amazon.com/powertools/typescript/latest/): kit de ferramentas para desenvolvedores para implementar as práticas recomendadas da 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 (TypeScript) e do AWS SAM para rastreamento](#typescript-tracing-sam)
+ [Uso do Powertools para AWS Lambda (TypeScript) e do AWS CDK para rastreamento](#typescript-tracing-cdk)
+ [Interpretar um rastreamento do X-Ray](#typescript-tracing-interpretation)
## Uso do Powertools para AWS Lambda (TypeScript) e do AWS SAM para rastreamento
Siga as etapas abaixo para baixar, criar e implantar um exemplo de aplicação Hello World TypeScript com os módulos integrados do [Powertools para AWS Lambda (TypeScript)](https://docs.powertools.aws.dev/lambda-typescript) 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 `hello world`.
**Pré-requisitos**
Para executar as etapas desta seção, você deve ter o seguinte:
+ Node.js
+ [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-typescript --name sam-app --package-type Zip --runtime nodejs24.x --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:
```
XRay Event [revision 1] at (2023-01-31T11:29:40.527000) with id (1-11a2222-111a222222cb33de3b95daf9) and duration (0.483s)
- 0.425s - sam-app/Prod [HTTP: 200]
- 0.422s - Lambda [HTTP: 200]
- 0.406s - sam-app-HelloWorldFunction-Xyzv11a1bcde [HTTP: 200]
- 0.172s - sam-app-HelloWorldFunction-Xyzv11a1bcde
- 0.179s - Initialization
- 0.112s - Invocation
- 0.052s - ## app.lambdaHandler
- 0.001s - ### MySubSegment
- 0.059s - 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 Powertools para AWS Lambda (TypeScript) e do AWS CDK para rastreamento
Siga as etapas abaixo para baixar, criar e implantar um exemplo de aplicação Hello World TypeScript com os módulos integrados do [Powertools para AWS Lambda (TypeScript)](https://docs.powertools.aws.dev/lambda-typescript) usando o AWS CDK. 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 `hello world`.
**Pré-requisitos**
Para executar as etapas desta seção, você deve ter o seguinte:
+ Node.js
+ [AWS CLI versão 2](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html)
+ [AWS CDK versão 2](https://docs.aws.amazon.com/cdk/v2/guide/getting_started.html#getting_started_prerequisites)
+ [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 Cloud Development Kit (AWS CDK)**
1. Crie um diretório de projeto para sua aplicação.
```
mkdir hello-world
cd hello-world
```
1. Inicialize a aplicação.
```
cdk init app --language typescript
```
1. Adicione o pacote [@types/aws-lambda](https://www.npmjs.com/package/@types/aws-lambda) como uma dependência de desenvolvimento.
```
npm install -D @types/aws-lambda
```
1. Instale o [Utilitário Tracer](https://docs.aws.amazon.com/powertools/typescript/latest/features/tracer/) do Powertools.
```
npm install @aws-lambda-powertools/tracer
```
1. Abra o diretório **lib**. Você deverá ver um arquivo chamado **hello-world-stack.ts**. Crie novos dois novos arquivos neste diretório: **hello-world.function.ts** e **hello-world.ts**.
1. Abra o **hello-world.function.ts** e adicione o código a seguir ao arquivo. Este é o código da função Lambda.
```
import { APIGatewayEvent, APIGatewayProxyResult, Context } from 'aws-lambda';
import { Tracer } from '@aws-lambda-powertools/tracer';
const tracer = new Tracer();
export const handler = async (event: APIGatewayEvent, context: Context): Promise => {
// Get facade segment created by Lambda
const segment = tracer.getSegment();
// Create subsegment for the function and set it as active
const handlerSegment = segment.addNewSubsegment(`## ${process.env._HANDLER}`);
tracer.setSegment(handlerSegment);
// Annotate the subsegment with the cold start and serviceName
tracer.annotateColdStart();
tracer.addServiceNameAnnotation();
// Add annotation for the awsRequestId
tracer.putAnnotation('awsRequestId', context.awsRequestId);
// Create another subsegment and set it as active
const subsegment = handlerSegment.addNewSubsegment('### MySubSegment');
tracer.setSegment(subsegment);
let response: APIGatewayProxyResult = {
statusCode: 200,
body: JSON.stringify({
message: 'hello world',
}),
};
// Close subsegments (the Lambda one is closed automatically)
subsegment.close(); // (### MySubSegment)
handlerSegment.close(); // (## index.handler)
// Set the facade segment as active again (the one created by Lambda)
tracer.setSegment(segment);
return response;
};
```
1. Abra o **hello-world.ts** e adicione o código a seguir ao arquivo. Ele contém a [estrutura NodeJSFunction](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_lambda_nodejs-readme.html), que cria a função do Lambda, configura variáveis de ambiente para o Powertools e define a retenção de logs para uma semana. Também inclui a [estrutura LambdaRestAPI](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_apigateway.LambdaRestApi.html), que cria a API REST.
```
import { Construct } from 'constructs';
import { NodejsFunction } from 'aws-cdk-lib/aws-lambda-nodejs';
import { LambdaRestApi } from 'aws-cdk-lib/aws-apigateway';
import { CfnOutput } from 'aws-cdk-lib';
import { Tracing } from 'aws-cdk-lib/aws-lambda';
export class HelloWorld extends Construct {
constructor(scope: Construct, id: string) {
super(scope, id);
const helloFunction = new NodejsFunction(this, 'function', {
environment: {
POWERTOOLS_SERVICE_NAME: 'helloWorld',
},
tracing: Tracing.ACTIVE,
});
const api = new LambdaRestApi(this, 'apigw', {
handler: helloFunction,
});
new CfnOutput(this, 'apiUrl', {
exportName: 'apiUrl',
value: api.url,
});
}
}
```
1. Abra o **hello-world-stack.ts**. Este é o código que define sua [pilha do AWS CDK](https://docs.aws.amazon.com/cdk/v2/guide/stacks.html). Substitua o código pelo seguinte:
```
import { Stack, StackProps } from 'aws-cdk-lib';
import { Construct } from 'constructs';
import { HelloWorld } from './hello-world';
export class HelloWorldStack extends Stack {
constructor(scope: Construct, id: string, props?: StackProps) {
super(scope, id, props);
new HelloWorld(this, 'hello-world');
}
}
```
1. Implante o aplicativo.
```
cd ..
cdk deploy
```
1. Obtenha o URL da aplicação implantada:
```
aws cloudformation describe-stacks --stack-name HelloWorldStack --query 'Stacks[0].Outputs[?ExportName==`apiUrl`].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:
```
XRay Event [revision 1] at (2023-01-31T11:50:06.997000) with id (1-11a2222-111a222222cb33de3b95daf9) and duration (0.449s)
- 0.350s - HelloWorldStack-helloworldfunction111A2BCD-Xyzv11a1bcde [HTTP: 200]
- 0.157s - HelloWorldStack-helloworldfunction111A2BCD-Xyzv11a1bcde
- 0.169s - Initialization
- 0.058s - Invocation
- 0.055s - ## index.handler
- 0.000s - ### MySubSegment
- 0.099s - Overhead
```
1. Este é um endpoint de API pública que é acessado pela Internet. Recomendamos excluir o endpoint após o teste.
```
cdk destroy
```
## Interpretar um rastreamento do X-Ray
Após configurar o rastreamento ativo, você pode observar solicitações específicas por meio da aplicação. O [mapa de rastreamento do X-Ray](https://docs.aws.amazon.com/xray/latest/devguide/xray-console-servicemap.html) fornece informações sobre a aplicação e todos os seus componentes. O seguinte exemplo mostra um rastreamento do exemplo de aplicação:
![\[\]](http://docs.aws.amazon.com/pt_br/lambda/latest/dg/images/sample-typescript-servicemap.png)