Registrare e monitorare le funzioni Lambda con TypeScript - AWS Lambda
Strumenti e librerieUtilizzo di Powertools per AWS Lambda (TypeScript) e di AWS SAM per la registrazione strutturataUtilizzo di Powertools per AWS Lambda (TypeScript) e del AWS CDK per la registrazione strutturataVisualizzazione dei log nella console LambdaVisualizzazione dei registri nella console CloudWatch

Registrare e monitorare le funzioni Lambda con TypeScript

AWS Lambda monitora automaticamente le funzioni Lambda e invia le voci di log ad Amazon CloudWatch. La funzione Lambda viene fornita con un gruppo di log CloudWatch con un flusso di log per ogni istanza della funzione. L'ambiente di runtime di Lambda invia al flusso di log i dettagli su ogni invocazione e altri output dal codice della funzione. Per ulteriori informazioni sui log CloudWatch, consulta Lambda invia automaticamente i log delle funzioni a CloudWatch Logs..

Per i log di output dal codice della funzione, puoi utilizzare i metodi nell'oggetto console. Per una registrazione più dettagliata, puoi utilizzare qualunque libreria di registrazione che scrive su stdout o stderr.

Utilizzo di strumenti di registrazione e librerie

Powertools per AWS Lambda (TypeScript) è un toolkit rivolto agli sviluppatori per implementare le best practice serverless e aumentare la velocità di sviluppo. L'utilità di registrazione fornisce un logger ottimizzato per Lambda che include informazioni aggiuntive sul contesto delle funzioni in tutte le funzioni con output strutturato come JSON. Utilizza l'utility per eseguire le seguenti operazioni:

  • Acquisizione di campi essenziali dal contesto Lambda, avvii a freddo e output di registrazione della struttura come JSON

  • Registrazione degli eventi di chiamata Lambda quando richiesto (disabilitata per impostazione predefinita)

  • Stampa di tutti i log solo per una percentuale di chiamate tramite campionamento dei log (disabilitata per impostazione predefinita)

  • Aggiunta di chiavi supplementari al log strutturato in qualsiasi momento

  • Utilizzo di un formattatore di log personalizzato (Bring Your Own Formatter) per generare i log in una struttura compatibile con Logging RFC dell'organizzazione

Utilizzo di Powertools per AWS Lambda (TypeScript) e di AWS SAM per la registrazione strutturata

Segui i passaggi riportati sotto per scaricare, creare e implementare un'applicazione Hello World in TypeScript di esempio con i moduli Powertools per AWS Lambda (TypeScript) integrati utilizzando AWS SAM. Questa applicazione implementa un backend dell'API di base e utilizza Powertools per l'emissione di log, parametri e tracce. Consiste in un endpoint Gateway Amazon API e in una funzione Lambda. Quando si invia una richiesta GET all'endpoint API Gateway, la funzione Lambda richiama, invia log e parametri a CloudWatch utilizzando Embedded Metric Format e invia le tracce a AWS X-Ray. La funzione restituisce un messaggio hello world.

Prerequisiti

Per completare le fasi riportate in questa sezione, è necessario:

Implementare un'applicazione AWS SAM di esempio

  1. Inizializzare l'applicazione utilizzando il modello Hello World TypeScript.

    sam init --app-template hello-world-powertools-typescript --name sam-app --package-type Zip --runtime nodejs22.x

  2. Costruisci l'app.

    cd sam-app && sam build

  3. Distribuire l'app.

    sam deploy --guided

  4. Seguire le istruzioni visualizzate sullo schermo. Per accettare le opzioni predefinite fornite nell'esperienza interattiva, premi Enter.

    Nota

    Per HelloWorldFunction potrebbe non avere l'autorizzazione definita, va bene?, assicurati di inserire y.

  5. Ottieni l'URL dell'applicazione implementata:

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

  6. Richiama l'endpoint dell'API:

    curl <URL_FROM_PREVIOUS_STEP>

    In caso di esito positivo, vedrai questa risposta:

    {"message":"hello world"}

  7. Per ottenere i log per la funzione, esegui sam logs. Per ulteriori informazioni, consulta l'argomento relativo all'utilizzo dei log nella Guida per sviluppatori AWS Serverless Application Model.

    sam logs --stack-name sam-app

    L'output del log ha la struttura seguente:

    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

  8. Questo è un endpoint API pubblico accessibile su Internet. È consigliabile eliminare l'endpoint dopo il test.

    sam delete

Gestione della conservazione dei log

I gruppi di log non vengono eliminati automaticamente quando si elimina una funzione. Affinché i log non siano archiviati a tempo indeterminato, elimina il gruppo di log o configura un periodo di conservazione trascorso il quale i log vengono eliminati automaticamente da CloudWatch. Per configurare la conservazione dei log, aggiungi quanto segue al tuo modello 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

Utilizzo di Powertools per AWS Lambda (TypeScript) e del AWS CDK per la registrazione strutturata

Segui i passaggi riportati sotto per scaricare, creare e implementare un'applicazione Hello World in TypeScript di esempio con i moduli Powertools per AWS Lambda (TypeScript) integrati utilizzando AWS CDK. Questa applicazione implementa un backend dell'API di base e utilizza Powertools per l'emissione di log, parametri e tracce. Consiste in un endpoint Gateway Amazon API e in una funzione Lambda. Quando si invia una richiesta GET all'endpoint API Gateway, la funzione Lambda richiama, invia log e parametri a CloudWatch utilizzando Embedded Metric Format e invia le tracce a AWS X-Ray. La funzione restituisce un messaggio hello world.

Prerequisiti

Per completare le fasi riportate in questa sezione, è necessario:

Implementare un'applicazione AWS CDK di esempio

  1. Crea una directory di progetto per la nuova applicazione.

    mkdir hello-world
cd hello-world

  2. Inizializza l'app.

    cdk init app --language typescript

  3. Aggiungi il pacchetto @types /aws-lambda come dipendenza di sviluppo.

    npm install -D @types/aws-lambda

  4. Installa l'utilità Logger di Powertools.

    npm install @aws-lambda-powertools/logger

  5. Apri la directory lib. Dovrebbe essere visualizzato un file chiamato hello-world-stack.ts. Crea due nuovi file in questa directory: hello-world.function.ts e hello-world.ts.

  6. Apri hello-world.function.ts e aggiungi il seguente codice al file. Questo è il codice per la funzione 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. Apri hello-world.ts e aggiungi il seguente codice al file. Contiene il costrutto NodejsFunction, che crea la funzione Lambda, configura le variabili di ambiente per Powertools e imposta la conservazione dei log su una settimana. Include anche il costrutto LambdaRestApi, che crea la REST API.

    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. Apri hello-world-stack.ts. Questo è il codice che definisce lo stack AWS CDK. Sostituisci il codice con il seguente:

    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. Passa alla directory del progetto.

    cd hello-world

  10. Distribuisci l'applicazione.

    cdk deploy

  11. Ottieni l'URL dell'applicazione implementata:

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

  12. Richiama l'endpoint dell'API:

    curl <URL_FROM_PREVIOUS_STEP>

    In caso di esito positivo, vedrai questa risposta:

    {"message":"hello world"}

  13. Per ottenere i log per la funzione, esegui sam logs. Per ulteriori informazioni, consulta l'argomento relativo all'utilizzo dei log nella Guida per sviluppatori AWS Serverless Application Model.

    sam logs --stack-name HelloWorldStack

    L'output del log ha la struttura seguente:

    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

  14. Questo è un endpoint API pubblico accessibile su Internet. È consigliabile eliminare l'endpoint dopo il test.

    cdk destroy

Visualizzazione dei log nella console Lambda

È possibile utilizzare la console Lambda per visualizzare l'output del log dopo aver richiamato una funzione Lambda.

Se il codice può essere testato dall'editor del codice incorporato, troverai i log nei risultati dell’esecuzione. Quando utilizzi la funzionalità di test della console per richiamare una funzione, troverai l’output del log nella sezione Dettagli.

Visualizzazione dei registri nella console CloudWatch

È possibile utilizzare la console Amazon CloudWatch per visualizzare i registri per tutti i richiami della funzione Lambda.

Per visualizzare i log nella console CloudWatch:

  1. Aprire la pagina Log groups (Gruppi di log) nella console di CloudWatch.

  2. Scegliere il gruppo di log della funzione (/aws/lambda/function-name).

  3. Creare un flusso di log.

Ogni flusso di log corrisponde a un'istanza della funzione. Nuovi flussi di log vengono visualizzati quando aggiorni la funzione Lambda e quando vengono create istanze aggiuntive per gestire più chiamate simultanee. Per trovare i registri per un richiamo specifico, si consiglia di utilizzare la funzione con AWS X-Ray. X-Ray registra i dettagli sulla richiesta e il flusso di log nella traccia.