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

TypeScript Codice di tracciamento 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:

AWSDistro for OpenTelemetry (ADOT): una distribuzione sicura, pronta per la produzione e supportata dell'SDK (OtelAWS). OpenTelemetry
SDK AWS X-Ray per Node.js: un SDK per generare e inviare i dati di traccia su X-Ray.
Powertools for AWS Lambda (TypeScript): un toolkit per sviluppatori per implementare le migliori pratiche Serverless e aumentare la velocità degli sviluppatori.

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 end-to-end tracciamento in 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.

Sections

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

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

Segui i passaggi seguenti per scaricare, creare e distribuire un' TypeScript applicazione Hello World di esempio con i moduli Powertools for AWS Lambda (TypeScript) integrati utilizzando il. 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 invii una richiesta GET all'endpoint API Gateway, la funzione Lambda richiama, invia log e metriche utilizzando Embedded Metric Format e invia tracce a. CloudWatch AWS X-Ray La funzione restituisce un messaggio hello world.

Prerequisiti

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

Node.js 18.x o versione successiva
AWS CLI versione 2
CLI AWS SAM 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

Inizializza l'applicazione utilizzando il modello Hello World. TypeScript


sam init --app-template hello-world-powertools-typescript --name sam-app --package-type Zip --runtime nodejs18.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
Perché HelloWorldFunction potrebbe non avere un'autorizzazione definita. Va bene? , assicurati di entrarey.

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.

Nota

La frequenza di campionamento di X-Ray non può essere configurata per le funzioni.

Utilizzo di Powertools for AWS Lambda (TypeScript) e the AWS CDK per tracciare

Segui i passaggi seguenti per scaricare, creare e distribuire un' TypeScript applicazione Hello World di esempio con moduli Powertools for 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 invii una richiesta GET all'endpoint API Gateway, la funzione Lambda richiama, invia log e metriche utilizzando Embedded Metric Format e invia tracce a. CloudWatch AWS X-Ray La funzione restituisce un messaggio hello world.

Prerequisiti

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

Node.js 18.x o versione successiva
AWS CLI versione 2
AWS CDK versione 2
CLI AWS SAM 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. Dovresti vedere un file chiamato .ts. hello-world-stack 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 NodejsFunction costrutto che crea la funzione Lambda, configura le variabili di ambiente per Powertools e imposta la conservazione dei log su una settimana. Include anche il LambdaRestApi costrutto, che crea l'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,
    });
  }
}

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

Compilazione con Python