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 Usar logs do Amazon CloudWatch com o AWS Lambda.

Para exibir logs do código de função, você pode usar métodos no objeto de console. Para um log mais detalhado, você pode usar qualquer biblioteca de registro em log que grava em stdout ou stderr.

Usar bibliotecas e ferramentas de registro em log

O Powertools para AWS Lambda (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 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) 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 18.x ou posterior

• AWS CLI versão 2

• AWS SAM CLI versão 1.75 ou posterior. Se você tiver uma versão mais antiga da CLI do AWS SAM, consulte Atualizando a CLI do AWS SAM.

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 nodejs18.x

2. Crie a aplicação.

   cd sam-app && sam build

3. Implante o aplicativo.

   sam deploy --guided

4. 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.

5. Obtenha o URL da aplicação implantada:

   aws cloudformation describe-stacks --stack-name sam-app --query 'Stacks[0].Outputs[?OutputKey==`HelloWorldApi`].OutputValue' --output text

6. Invoque o endpoint da API:

   curl <URL_FROM_PREVIOUS_STEP>

   Se tiver êxito, você verá esta resposta:

   {"message":"hello world"}

7. Para obter os logs da função, execute sam logs. Para obter mais informações, consulte Trabalhar com logs 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:

   2023/01/31/[$LATEST]4d53e8d279824834a1ccd35511a4949c 2022-08-31T09:33:10.552000 START RequestId: 70693159-7e94-4102-a2af-98a6343fb8fb Version: $LATEST
   2023/01/31/[$LATEST]4d53e8d279824834a1ccd35511a4949c 2022-08-31T09:33:10.594000 2022-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}
   2023/01/31/[$LATEST]4d53e8d279824834a1ccd35511a4949c 2022-08-31T09:33:10.595000 2022-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":"2022-08-31T09:33:10.594Z"}
   2023/01/31/[$LATEST]4d53e8d279824834a1ccd35511a4949c 2022-08-31T09:33:10.655000 2022-08-31T09:33:10.655Z 70693159-7e94-4102-a2af-98a6343fb8fb INFO {"_aws":{"Timestamp":1661938390655,"CloudWatchMetrics":[{"Namespace":"sam-app","Dimensions":[["service"]],"Metrics":[]}]},"service":"helloWorld"}
   2023/01/31/[$LATEST]4d53e8d279824834a1ccd35511a4949c 2022-08-31T09:33:10.754000 END RequestId: 70693159-7e94-4102-a2af-98a6343fb8fb
   2023/01/31/[$LATEST]4d53e8d279824834a1ccd35511a4949c 2022-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

8. 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) 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 18.x ou posterior

• AWS CLI versão 2

• AWS CDK versão 2

• AWS SAM CLI versão 1.75 ou posterior. Se você tiver uma versão mais antiga da CLI do AWS SAM, consulte Atualizando a CLI do AWS SAM.

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

2. Inicialize a aplicação.

   cdk init app --language typescript

3. Adicione o pacote @types/aws-lambda como uma dependência de desenvolvimento.

   npm install -D @types/aws-lambda

4. Instale o Utilitário logger do Powertools.

   npm install @aws-lambda-powertools/logger

5. 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.

6. 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 { Logger } from '@aws-lambda-powertools/logger';
   const logger = new Logger();
     
   export const handler = async (event: APIGatewayEvent, context: Context): Promise<APIGatewayProxyResult> => {
     logger.info('This is an INFO log - sending HTTP 200 - hello world response');
     return {
       statusCode: 200,
       body: JSON.stringify({
         message: 'hello world',
       }),
     };
   };

7. Abra o hello-world.ts e adicione o código a seguir ao arquivo. Ele contém a estrutura NodeJSFunction, 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, 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,
       });
     }
   }

8. Abra o hello-world-stack.ts. Este é o código que define sua pilha do AWS CDK. 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');
     }
   }

9. Volte ao diretório do projeto.

   cd hello-world

10. Implante o aplicativo.

    cdk deploy

11. Obtenha o URL da aplicação implantada:

    aws cloudformation describe-stacks --stack-name HelloWorldStack --query 'Stacks[0].Outputs[?ExportName==`apiUrl`].OutputValue' --output text

12. Invoque o endpoint da API:

    curl <URL_FROM_PREVIOUS_STEP>

    Se tiver êxito, você verá esta resposta:

    {"message":"hello world"}

13. Para obter os logs da função, execute sam logs. Para obter mais informações, consulte Trabalhar com logs no Guia do desenvolvedor do AWS Serverless Application Model.

    sam logs --stack-name HelloWorldStack

    O resultado de saída do log se parece com:

    2023/01/31/[$LATEST]2ca67f180dcd4d3e88b5d68576740c8e 2022-08-31T14:48:37.047000 START RequestId: 19ad1007-ff67-40ce-9afe-0af0a9eb512c Version: $LATEST
    2023/01/31/[$LATEST]2ca67f180dcd4d3e88b5d68576740c8e 2022-08-31T14:48:37.050000 {
    "level": "INFO",
    "message": "This is an INFO log - sending HTTP 200 - hello world response",
    "service": "helloWorld",
    "timestamp": "2022-08-31T14:48:37.048Z",
    "xray_trace_id": "1-630f74c4-2b080cf77680a04f2362bcf2"
    }
    2023/01/31/[$LATEST]2ca67f180dcd4d3e88b5d68576740c8e 2022-08-31T14:48:37.082000 END RequestId: 19ad1007-ff67-40ce-9afe-0af0a9eb512c
    2023/01/31/[$LATEST]2ca67f180dcd4d3e88b5d68576740c8e 2022-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

14. 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

Você pode 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

Você pode usar o console do Amazon CloudWatch para exibir registros 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 (Grupos de log).

2. Escolha o grupo de logs de sua função (/aws/lambda/nome-de-sua-função).

3. Escolha um stream de logs.

Cada fluxo de log corresponde a uma instância da sua função. Uma transmissão de logs é exibida quando você atualiza sua função do Lambda e quando mais instâncias são criadas para lidar com várias 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.