Utilizzo di Powertools per AWS Lambda (TypeScript) e di AWS SAM per il tracciamento Utilizzo di Powertools per AWS Lambda (TypeScript) e del AWS CDK per il tracciamento Interpretazione di una traccia X-Ray

Tracciamento del codice TypeScript in AWS Lambda

Lambda si integra con AWS X-Ray per aiutarti a tracciare, eseguire il debug e ottimizzare le applicazioni Lambda. Puoi utilizzare X-Ray per tracciare una richiesta mentre attraversa le risorse nell'applicazione, che possono includere funzioni Lambda e altri servizi AWS.

Per inviare dati di tracciamento a X-Ray, è possibile utilizzare una delle tre librerie SDK:

AWS Distro for OpenTelemetry (ADOT): una distribuzione supportata da AWS sicura, pronta per la produzione, dell'SDK OpenTelemetry (OTel).
SDK AWS X-Ray per Node.js: un SDK per generare e inviare i dati di traccia su X-Ray.
Powertools per AWS Lambda (TypeScript): un toolkit rivolto agli sviluppatori per implementare le best practice serverless e aumentare la velocità di sviluppo.

Ciascun SDK offre dei modi per inviare i dati di telemetria al servizio X-Ray. Puoi quindi utilizzare X-Ray per visualizzare, filtrare e analizzare le metriche delle prestazioni dell'applicazione per identificare i problemi e le opportunità di ottimizzazione.

Importante

Gli SDK X-Ray e Powertools per AWS Lambda fanno parte di una soluzione di strumentazione strettamente integrata offerta da AWS. I livelli Lambda ADOT fanno parte di uno standard di settore per la strumentazione di tracciamento che in generale raccoglie più dati, ma potrebbero non essere adatti a tutti i casi d'uso. È possibile implementare il tracciamento end-to-end di X-Ray utilizzando entrambe le soluzioni. Per ulteriori informazioni sulla scelta più adatta, consulta Scegliere tra le AWS Distro per OpenTelemetry e SDK X-Ray.

Sezioni

Utilizzo di Powertools per AWS Lambda (TypeScript) e di AWS SAM per il tracciamento
Utilizzo di Powertools per AWS Lambda (TypeScript) e del AWS CDK per il tracciamento
Interpretazione di una traccia X-Ray

Utilizzo di Powertools per AWS Lambda (TypeScript) e di AWS SAM per il tracciamento

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 back-end 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:

Node.js
AWS CLI versione 2
AWS SAM CLI versione 1.75 o successiva. Se disponi di una versione precedente della CLI AWS SAM, consulta Aggiornamento della CLI AWS SAM.

Implementare un'applicazione AWS SAM di esempio

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 --no-tracing

Costruisci l'app.
```
cd sam-app && sam build
```
Distribuire l'app.
```
sam deploy --guided
```
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.

Ottieni l'URL dell'applicazione implementata:


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

Richiama l'endpoint dell'API:
```
curl <URL_FROM_PREVIOUS_STEP>
```
In caso di esito positivo, vedrai questa risposta:
```
{"message":"hello world"}
```

Per ottenere le tracce per la funzione, esegui sam traces.


sam traces

L'output della traccia ha il seguente aspetto:


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

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

X-Ray non traccia tutte le richieste nell'applicazione. X-Ray applica un algoritmo di campionamento per garantire che il tracciamento avvenga in modo efficiente, continuando allo stesso tempo a fornire un campione rappresentativo di tutte le richieste. La frequenza di campionamento è di una richiesta al secondo e del 5% delle altre richieste. Non è possibile configurare la frequenza di campionamento di X-Ray per le funzioni.

Utilizzo di Powertools per AWS Lambda (TypeScript) e del AWS CDK per il tracciamento

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 back-end 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:

Node.js
AWS CLI versione 2
AWS CDK versione 2
AWS SAM CLI versione 1.75 o successiva. Se disponi di una versione precedente della CLI AWS SAM, consulta Aggiornamento della CLI AWS SAM.

Implementare un'applicazione AWS Cloud Development Kit (AWS CDK) di esempio

Crea una directory di progetto per la nuova applicazione.
```
mkdir hello-world
cd hello-world
```
Inizializza l'app.
```
cdk init app --language typescript
```
Aggiungi il pacchetto @types /aws-lambda come dipendenza di sviluppo.
```
npm install -D @types/aws-lambda
```

Installa l'utilità Tracer di Powertools.


npm install @aws-lambda-powertools/tracer

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.

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 { Tracer } from '@aws-lambda-powertools/tracer';
const tracer = new Tracer();

export const handler = async (event: APIGatewayEvent, context: Context): Promise<APIGatewayProxyResult> => {
  // 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;
};

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 { 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,
    });
  }
}

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');
  }
}

Distribuisci l'applicazione.
```
cd ..
cdk deploy
```

Ottieni l'URL dell'applicazione implementata:


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

Richiama l'endpoint dell'API:
```
curl <URL_FROM_PREVIOUS_STEP>
```
In caso di esito positivo, vedrai questa risposta:
```
{"message":"hello world"}
```

Per ottenere le tracce per la funzione, esegui sam traces.


sam traces

L'output della traccia ha il seguente aspetto:


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

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

Interpretazione di una traccia X-Ray

Dopo aver configurato il tracciamento attivo, è possibile osservare richieste specifiche tramite l'applicazione. La mappa del tracciamento X-Ray fornisce informazioni sull'applicazione e su tutti i relativi componenti. L'esempio seguente mostra una traccia dall'applicazione di esempio:

La mappa del servizio X-Ray per l'applicazione di esempio

Avvertimento JavaScript è disabilitato o non è disponibile nel tuo browser.

Per usare la documentazione AWS, JavaScript deve essere abilitato. Consulta le pagine della guida del browser per le istruzioni.

Convenzioni dei documenti

Registrazione dei log

Compilazione con Python

Tracciamento del codice TypeScript in AWS Lambda

Importante

Sezioni

Utilizzo di Powertools per AWS Lambda (TypeScript) e di AWS SAM per il tracciamento

Prerequisiti

Implementare un'applicazione AWS SAM di esempio

Nota

Utilizzo di Powertools per AWS Lambda (TypeScript) e del AWS CDK per il tracciamento

Prerequisiti

Implementare un'applicazione AWS Cloud Development Kit (AWS CDK) di esempio

Interpretazione di una traccia X-Ray