# Registrar em log e monitorar funções do Lambda em TypeScript
O AWS Lambda monitora automaticamente as funções do Lambda e envia entradas de logs para o Amazon CloudWatch. Sua função do Lambda vem com um grupo de logs do CloudWatch Logs e uma transmissão de logs para cada instância de sua função. O ambiente de runtime do Lambda envia detalhes sobre cada invocação e outras saídas do código da função para o fluxo de logs. Para obter mais informações sobre o CloudWatch Logs, consulte [Enviar logs de função do Lambda para o CloudWatch Logs](monitoring-cloudwatchlogs.md).
Para exibir logs do código de função, você pode usar métodos no [objeto de console](https://nodejs.org/docs/latest-v18.x/api/console.html). Para um log mais detalhado, você pode usar qualquer biblioteca de registro em log que grava em `stdout` ou `stderr`.
**Topics**
+ [
## Usar bibliotecas e ferramentas de registro em log
](#typescript-tools-libraries)
+ [
## Uso do Powertools para AWS Lambda (TypeScript) e do AWS SAM para registro em log estruturado
](#typescript-logging-sam)
+ [
## Uso do Powertools para AWS Lambda (TypeScript) e do AWS CDK para registro em log estruturado
](#typescript-logging-cdk)
+ [
## Visualizar logs no console do Lambda
](#typescript-logging-console)
+ [
## Visualização de logs no console do CloudWatch
](#typescript-logging-cwconsole)
## Usar bibliotecas e ferramentas de registro em log
O [Powertools para AWS Lambda (TypeScript)](https://docs.aws.amazon.com/powertools/typescript/) é um kit de ferramentas para desenvolvedores para implementar as práticas recomendadas da tecnologia sem servidor e aumentar a velocidade do desenvolvedor. O [utilitário Logger](https://docs.powertools.aws.dev/lambda/typescript/latest/features/logger/) fornece um registrador otimizado para Lambda que inclui informações adicionais sobre o contexto da função em todas as suas funções com saída estruturada como JSON. Use esse utilitário para fazer o seguinte:
+ Capturar campos-chave do contexto do Lambda, inicialização a frio e estruturas registrando em log a saída como JSON
+ Registrar em log eventos de invocação do Lambda quando instruído (desativado por padrão)
+ Imprimir todos os logs somente para uma porcentagem das invocações por meio da amostragem de logs (desativado por padrão)
+ Anexar chaves adicionais ao log estruturado a qualquer momento
+ Use um formatador de log personalizado (Bring Your Own Formatter) para gerar logs em uma estrutura compatível com o RFC de logs da sua organização
## Uso do Powertools para AWS Lambda (TypeScript) e do AWS SAM para registro em log estruturado
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 20 ou posterior
+ [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
```
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 logs da função, execute [sam logs](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/sam-cli-command-reference-sam-logs.html). Para obter mais informações, consulte [Trabalhar com logs](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/serverless-sam-cli-logging.html) no *Guia do desenvolvedor do AWS Serverless Application Model*.
```
sam logs --stack-name sam-app
```
O resultado de saída do log se parece com:
```
2025/01/31/[$LATEST]4d53e8d279824834a1ccd35511a4949c 2025-08-31T09:33:10.552000 START RequestId: 70693159-7e94-4102-a2af-98a6343fb8fb Version: $LATEST
2025/01/31/[$LATEST]4d53e8d279824834a1ccd35511a4949c 2025-08-31T09:33:10.594000 2025-08-31T09:33:10.557Z 70693159-7e94-4102-a2af-98a6343fb8fb INFO {"_aws":{"Timestamp":1661938390556,"CloudWatchMetrics":[{"Namespace":"sam-app","Dimensions":[["service"]],"Metrics":[{"Name":"ColdStart","Unit":"Count"}]}]},"service":"helloWorld","ColdStart":1}
2025/01/31/[$LATEST]4d53e8d279824834a1ccd35511a4949c 2025-08-31T09:33:10.595000 2025-08-31T09:33:10.595Z 70693159-7e94-4102-a2af-98a6343fb8fb INFO {"level":"INFO","message":"This is an INFO log - sending HTTP 200 - hello world response","service":"helloWorld","timestamp":"2025-08-31T09:33:10.594Z"}
2025/01/31/[$LATEST]4d53e8d279824834a1ccd35511a4949c 2025-08-31T09:33:10.655000 2025-08-31T09:33:10.655Z 70693159-7e94-4102-a2af-98a6343fb8fb INFO {"_aws":{"Timestamp":1661938390655,"CloudWatchMetrics":[{"Namespace":"sam-app","Dimensions":[["service"]],"Metrics":[]}]},"service":"helloWorld"}
2025/01/31/[$LATEST]4d53e8d279824834a1ccd35511a4949c 2025-08-31T09:33:10.754000 END RequestId: 70693159-7e94-4102-a2af-98a6343fb8fb
2025/01/31/[$LATEST]4d53e8d279824834a1ccd35511a4949c 2025-08-31T09:33:10.754000 REPORT RequestId: 70693159-7e94-4102-a2af-98a6343fb8fb Duration: 201.55 ms Billed Duration: 202 ms Memory Size: 128 MB Max Memory Used: 66 MB Init Duration: 252.42 ms
XRAY TraceId: 1-630f2ad5-1de22b6d29a658a466e7ecf5 SegmentId: 567c116658fbf11a Sampled: true
```
1. Este é um endpoint de API pública que é acessado pela Internet. Recomendamos excluir o endpoint após o teste.
```
sam delete
```
### Gerenciar a retenção de logs
Os grupos de logs não são excluídos automaticamente excluídos quando você exclui uma função. Para evitar armazenar logs por tempo indeterminado, exclua o grupo de logs ou configure um período de retenção após o qual o CloudWatch excluirá os logs automaticamente. Para configurar a retenção de logs, adicione o seguinte ao seu modelo do AWS SAM:
```
Resources:
HelloWorldFunction:
Type: AWS::Serverless::Function
Properties:
# Omitting other properties
LogGroup:
Type: AWS::Logs::LogGroup
Properties:
LogGroupName: !Sub "/aws/lambda/${HelloWorldFunction}"
RetentionInDays: 7
```
## Uso do Powertools para AWS Lambda (TypeScript) e do AWS CDK para registro em log estruturado
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 20 ou posterior
+ [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 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 logger](https://docs.aws.amazon.com/powertools/typescript/latest/features/logger/) do Powertools.
```
npm install @aws-lambda-powertools/logger
```
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 do Lambda.
```
import { APIGatewayEvent, APIGatewayProxyResult, Context } from 'aws-lambda';
import { Logger } from '@aws-lambda-powertools/logger';
const logger = new Logger();
export const handler = async (event: APIGatewayEvent, context: Context): Promise => {
logger.info('This is an INFO log - sending HTTP 200 - hello world response');
return {
statusCode: 200,
body: JSON.stringify({
message: 'hello world',
}),
};
};
```
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 { RetentionDays } from 'aws-cdk-lib/aws-logs';
import { CfnOutput } from 'aws-cdk-lib';
export class HelloWorld extends Construct {
constructor(scope: Construct, id: string) {
super(scope, id);
const helloFunction = new NodejsFunction(this, 'function', {
environment: {
Powertools_SERVICE_NAME: 'helloWorld',
LOG_LEVEL: 'INFO',
},
logRetention: RetentionDays.ONE_WEEK,
});
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. Volte ao diretório do projeto.
```
cd hello-world
```
1. Implante o aplicativo.
```
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 logs da função, execute [sam logs](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/sam-cli-command-reference-sam-logs.html). Para obter mais informações, consulte [Trabalhar com logs](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/serverless-sam-cli-logging.html) no *Guia do desenvolvedor do AWS Serverless Application Model*.
```
sam logs --stack-name HelloWorldStack
```
O resultado de saída do log se parece com:
```
2025/01/31/[$LATEST]2ca67f180dcd4d3e88b5d68576740c8e 2025-08-31T14:48:37.047000 START RequestId: 19ad1007-ff67-40ce-9afe-0af0a9eb512c Version: $LATEST
2025/01/31/[$LATEST]2ca67f180dcd4d3e88b5d68576740c8e 2025-08-31T14:48:37.050000 {
"level": "INFO",
"message": "This is an INFO log - sending HTTP 200 - hello world response",
"service": "helloWorld",
"timestamp": "2025-08-31T14:48:37.048Z",
"xray_trace_id": "1-630f74c4-2b080cf77680a04f2362bcf2"
}
2025/01/31/[$LATEST]2ca67f180dcd4d3e88b5d68576740c8e 2025-08-31T14:48:37.082000 END RequestId: 19ad1007-ff67-40ce-9afe-0af0a9eb512c
2025/01/31/[$LATEST]2ca67f180dcd4d3e88b5d68576740c8e 2025-08-31T14:48:37.082000 REPORT RequestId: 19ad1007-ff67-40ce-9afe-0af0a9eb512c Duration: 34.60 ms Billed Duration: 35 ms Memory Size: 128 MB Max Memory Used: 57 MB Init Duration: 173.48 ms
```
1. Este é um endpoint de API pública que é acessado pela Internet. Recomendamos excluir o endpoint após o teste.
```
cdk destroy
```
## Visualizar logs no console do Lambda
É possível usar o console do Lambda para exibir a saída do log depois de invocar uma função do Lambda.
Se seu código puder ser testado no editor de **Código** incorporado, você encontrará logs nos **resultados de execução**. Ao usar o recurso de teste do console para invocar uma função, você encontrará **Saída de log** na seção **Detalhes**.
## Visualização de logs no console do CloudWatch
É possível usar o console do Amazon CloudWatch para exibir logs de todas as invocações da função do Lambda.
**Para visualizar logs no console do CloudWatch**
1. No console do Amazon CloudWatch, abra a [página Log groups](https://console.aws.amazon.com/cloudwatch/home?#logs:) (Grupos de log).
1. Escolha o grupo de logs de sua função (**/aws/lambda/*nome-de-sua-função***).
1. Escolha um stream de logs.
Cada fluxo de log corresponde a uma [instância da sua função](lambda-runtime-environment.md). Um fluxo de logs é exibido quando você atualiza sua função do Lambda e quando mais instâncias são criadas para lidar com invocações simultâneas. Para localizar logs de uma invocação específica, recomendamos intrumentar sua função com AWS X-Ray. O X-Ray registra detalhes sobre a solicitação e o stream de logs no rastreamento.