Strumentazione del codice Node.js 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 due librerie SDK:

• AWSDistro for OpenTelemetry (ADOT): una distribuzione sicura, pronta per la produzione e AWS supportata dell'SDK (Otel). OpenTelemetry

• SDK AWS X-Ray per Node.js: un SDK per generare e inviare i dati di traccia su X-Ray.

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.

Utilizzo di ADOT per strumentare le funzioni Node.js

ADOT fornisce livelli Lambda completamente gestiti che mettono insieme tutto il necessario per raccogliere i dati di telemetria utilizzando l'SDK OTel. Usando questo livello, è possibile strumentare le funzioni Lambda senza dover modificare alcun codice funzione. È inoltre possibile configurare il livello per eseguire l'inizializzazione personalizzata di OTel. Per ulteriori informazioni, consulta la sezione relativa alla configurazione personalizzata per ADOT Collector su Lambda nella documentazione di ADOT.

Per i runtime Node.js, puoi aggiungere il livello Lambda gestito da AWS per ADOT Javascript per strumentare automaticamente le tue funzioni. Per istruzioni dettagliate su come aggiungere questo layer, consulta AWSDistro for OpenTelemetry Lambda JavaScript Support nella documentazione ADOT.

Utilizzo dell'SDK X-Ray per strumentare le funzioni Node.js

Per registrare i dettagli sulle chiamate effettuate dalla funzione Lambda ad altre risorse nell'applicazione, è anche possibile utilizzare il SDK AWS X-Ray per Node.js. Per ottenere l'SDK, aggiungere il pacchetto aws-xray-sdk-core alle dipendenze dell'applicazione.

Esempio blank-nodejs/package.json

{
  "name": "blank-nodejs",
  "version": "1.0.0",
  "private": true,
  "devDependencies": {
    "aws-sdk": "2.631.0",
    "jest": "25.4.0"
  },
  "dependencies": {
    "aws-xray-sdk-core": "1.1.2"
  },
  "scripts": {
    "test": "jest"
  }
}

Per strumentare i client AWS SDK, eseguire il wrap della libreria aws-sdk con il metodo captureAWS.

Esempio blank-nodejs/function/index.js – Tracciamento di un client SDK AWS

const AWSXRay = require('aws-xray-sdk-core')
const AWS = AWSXRay.captureAWS(require('aws-sdk'))

// Create client outside of handler to reuse
const lambda = new AWS.Lambda()

// Handler
exports.handler = async function(event, context) {
  event.Records.forEach(record => {
  ...

Il runtime Lambda imposta alcune variabili di ambiente per configurare l'SDK X-Ray. Ad esempio, Lambda imposta AWS_XRAY_CONTEXT_MISSING su LOG_ERROR per evitare di generare errori di runtime dall'SDK X-Ray. Per impostare una strategia mancante di contesto personalizzato, sovrascrivi la variabile di ambiente nella configurazione della funzione in modo da non avere alcun valore, quindi puoi impostare la strategia mancante di contesto a livello di programmazione.

Esempio di codice di inizializzazione

const AWSXRay = require('aws-xray-sdk-core');

// Configure the context missing strategy to do nothing
AWSXRay.setContextMissingStrategy(() => {});

Per ulteriori informazioni, consulta Utilizzo delle variabili di ambiente Lambda.

Dopo aver aggiunto le dipendenze corrette e aver apportato le modifiche necessarie al codice, attivare il tracciamento nella configurazione della funzione tramite la console Lambda o l'API.

Attivazione del tracciamento con la console Lambda

Per attivare il tracciamento attivo sulla funzione Lambda con la console, attenersi alla seguente procedura:

Per attivare il tracciamento attivo

1. Aprire la pagina Funzioni della console Lambda.

2. Scegliere una funzione.

3. Scegliere Configuration (Configurazione) e quindi Monitoring and operations tools (Strumenti di monitoraggio e operazioni).

4. Scegli Modifica.

5. In X-Ray, attivare Active tracing (Tracciamento attivo).

6. Selezionare Salva.

Attivazione del tracciamento con l'API Lambda

Configurare il tracciamento sulla funzione Lambda con la AWS CLI o SDK AWS e utilizzare le seguenti operazioni API:

• UpdateFunctionConfiguration

• GetFunctionConfiguration

• CreateFunction

Il seguente comando AWS CLI di esempio consente il tracciamento attivo su una funzione denominata my-function.

aws lambda update-function-configuration --function-name my-function \
--tracing-config Mode=Active

La modalità di tracciamento fa parte della configurazione specifica della versione quando si pubblica una versione della funzione. Non è possibile modificare la modalità di tracciamento in una versione pubblicata.

Attivazione del tracciamento con AWS CloudFormation

Per attivare il tracciamento su una risorsa AWS::Lambda::Function in un modello AWS CloudFormation, utilizzare la proprietà TracingConfig.

Esempio function-inline.yml – Configurazione del tracciamento

Resources:
  function:
    Type: AWS::Lambda::Function
    Properties:
      TracingConfig:
        Mode: Active
      ...

Per una risorsa AWS Serverless Application Model (AWS SAM) AWS::Serverless::Function, utilizzare la proprietà Tracing.

Esempio template.yml – Configurazione del tracciamento

Resources:
  function:
    Type: AWS::Serverless::Function
    Properties:
      Tracing: Active
      ...

Interpretazione di una traccia X-Ray

La funzione ha bisogno dell'autorizzazione per caricare i dati di traccia su X-Ray. Quando si attiva il tracciamento nella console Lambda, Lambda aggiunge le autorizzazioni necessarie al ruolo di esecuzione della funzione. Altrimenti, aggiungi la AWSXRayDaemonWriteAccesspolicy al ruolo di esecuzione.

Dopo aver configurato il tracciamento attivo, è possibile osservare richieste specifiche tramite l'applicazione. Il grafico dei servizi X-Ray mostra informazioni sull'applicazione e tutti i suoi componenti. L'esempio seguente dall'applicazione del processore di errori mostra un'applicazione con due funzioni. La funzione principale elabora gli eventi e talvolta restituisce errori. La seconda funzione in alto elabora gli errori che compaiono nel gruppo di log della prima e utilizza l'AWSSDK per chiamare X-Ray, Amazon Simple Storage Service (Amazon S3) e Amazon Logs. CloudWatch

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.

Quando si utilizza il tracciamento attivo, Lambda registra 2 segmenti, che creano due nodi sul grafico del servizio. L'immagine seguente evidenzia questi due nodi per la funzione principale dall'applicazione di esempio del processore di errore.

Il primo nodo a sinistra rappresenta il servizio Lambda che riceve la richiesta di chiamata. Il secondo nodo rappresenta la specifica funzione Lambda. L'esempio seguente mostra una traccia con questi 2 segmenti. Entrambi sono nominati my-function, ma uno ha l'origine di AWS::Lambda e l'altro ha origine AWS::Lambda::Function.

Questo esempio espande il segmento della funzione per visualizzare i relativi tre sottosegmenti:

• Inizializzazione – Rappresenta il tempo trascorso a caricare la funzione e ad eseguire il codice di inizializzazione. Questo sottosegmento viene visualizzato solo per il primo evento che viene elaborato da ogni istanza della funzione.

• Chiamata: rappresenta il tempo impiegato per eseguire il codice del gestore.

• Overhead: rappresenta il tempo impiegato dal runtime Lambda per prepararsi a gestire l'evento successivo.

È inoltre possibile strumentare i client HTTP, registrare query SQL e creare segmenti secondari personalizzati con annotazioni e metadati. Per ulteriori informazioni, consulta SDK AWS X-Ray per Node.js nella Guida per gli sviluppatori di AWS X-Ray.

Prezzi

È possibile utilizzare il tracciamento X-Ray gratuitamente ogni mese fino a un certo limite come parte del piano gratuito di AWS. Oltre la soglia, X-Ray addebita lo storage di traccia e il recupero. Per ulteriori informazioni, consulta Prezzi di AWS X-Ray.

Memorizzazione delle dipendenze di runtime in un livello (SDK X-Ray)

Se si utilizza l'SDK X-Ray per strumentare i client SDK AWS del codice della funzione, il pacchetto di implementazione può diventare piuttosto grande. Per evitare di caricare dipendenze di runtime ogni volta che si aggiorna il codice della funzione, includere l'SDK X-Ray in un livello Lambda.

L'esempio seguente mostra una risorsa AWS::Serverless::LayerVersion che memorizza SDK AWS X-Ray per Node.js.

Esempio template.yml – Livello delle dipendenze

Resources:
  function:
    Type: AWS::Serverless::Function
    Properties:
      CodeUri: function/.
      Tracing: Active
      Layers:
        - !Ref libs
      ...
  libs:
    Type: AWS::Serverless::LayerVersion
    Properties:
      LayerName: blank-nodejs-lib
      Description: Dependencies for the blank sample app.
      ContentUri: lib/.
      CompatibleRuntimes:
        - nodejs16.x

Con questa configurazione, si aggiorna il livello della libreria solo se si modificano le dipendenze di runtime. Poiché il pacchetto di implementazione della funzione contiene solo il codice, questo può contribuire a ridurre i tempi di caricamento.

La creazione di un layer per le dipendenze richiede modifiche alla compilazione per generare l'archivio dei layer prima della distribuzione. Per un esempio funzionante, vedere l'applicazione di esempio blank-nodejs .