Instrumentierung von Node.js Code in AWS Lambda

Lambda lässt sich integrieren AWS X-Ray , um Ihnen zu helfen, Lambda-Anwendungen zu verfolgen, zu debuggen und zu optimieren. Sie können mit X-Ray eine Anforderung verfolgen, während sie Ressourcen in Ihrer Anwendung durchläuft, die Lambda-Funktionen und andere AWS -Services enthalten können.

Um Tracing-Daten an X-Ray zu senden, können Sie eine von zwei SDK Bibliotheken verwenden:

• AWS Distribution for OpenTelemetry (ADOT) — Eine sichere, produktionsbereite und AWS unterstützte Distribution von (). OpenTelemetry OTel SDK

• AWS X-Ray-SDK for Node.js— Und SDK zum Generieren und Senden von Trace-Daten an X-Ray.

Jedes SDKs bietet Möglichkeiten, Ihre Telemetriedaten an den X-Ray-Dienst zu senden. Sie können dann mit X-Ray die Leistungsmetriken Ihrer Anwendung anzeigen, filtern und erhalten, um Probleme und Möglichkeiten zur Optimierung zu identifizieren.

Wichtig

X-Ray und Powertools für AWS Lambda SDKs sind Teil einer eng integrierten Instrumentierungslösung von AWS. Die ADOT Lambda-Layer sind Teil eines branchenweiten Standards für Tracing-Instrumente, die im Allgemeinen mehr Daten sammeln, aber möglicherweise nicht für alle Anwendungsfälle geeignet sind. Sie können die end-to-end Ablaufverfolgung in X-Ray mit beiden Lösungen implementieren. Weitere Informationen zur Auswahl zwischen beiden finden Sie unter Wählen zwischen der AWS Distribution für Open Telemetry und X-Ray. SDKs

Wird ADOT zur Instrumentierung Ihrer Funktionen von Node.js verwendet

ADOTbietet vollständig verwaltete Lambda-Schichten, die alles zusammenfassen, was Sie zum Sammeln von Telemetriedaten mithilfe der benötigen. OTel SDK Indem Sie diese Ebene verwenden, können Sie Ihre Lambda-Funktionen instrumentieren, ohne einen Funktionscode ändern zu müssen. Sie können Ihren Layer auch so konfigurieren, dass er eine benutzerdefinierte Initialisierung von durchführt. OTel Weitere Informationen finden Sie in der ADOT Dokumentation unter Benutzerdefinierte Konfiguration für den ADOT Collector auf Lambda.

Für Laufzeiten von Node.js können Sie die AWS verwaltete Lambda-Schicht für ADOT Javascript hinzufügen, um Ihre Funktionen automatisch zu instrumentieren. Eine ausführliche Anleitung zum Hinzufügen dieser Ebene finden Sie JavaScript in der Dokumentation unter AWS Distro for OpenTelemetry Lambda Support for. ADOT

Verwenden Sie das X-Ray SDK zur Instrumentierung Ihrer Node.js Funktionen

Um Details zu Aufrufen aufzuzeichnen, die Ihre Lambda-Funktion an andere Ressourcen in Ihrer Anwendung vornimmt, können Sie auch AWS X-Ray-SDK for Node.js verwenden. Um das zu erhaltenSDK, fügen Sie das aws-xray-sdk-core Paket zu den Abhängigkeiten Ihrer Anwendung hinzu.

Beispiel blank-nodejs/package.json

{
  "name": "blank-nodejs",
  "version": "1.0.0",
  "private": true,
  "devDependencies": {
    "jest": "29.7.0"
  },
  "dependencies": {
    "@aws-sdk/client-lambda": "3.345.0",
    "aws-xray-sdk-core": "3.5.3"
  },
  "scripts": {
    "test": "jest"
  }
}

Um AWS SDK Clients in Version 3 zu AWS SDK for JavaScript instrumentieren, schließen Sie die Client-Instanz mit der captureAWSv3Client Methode ein.

Beispiel blank-nodejs/function/index.js — Einen AWS SDK Client verfolgen

const AWSXRay = require('aws-xray-sdk-core');
const { LambdaClient, GetAccountSettingsCommand } = require('@aws-sdk/client-lambda');

// Create client outside of handler to reuse
const lambda = AWSXRay.captureAWSv3Client(new LambdaClient());

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

Die Lambda-Laufzeit legt einige Umgebungsvariablen fest, um das X-Ray SDK zu konfigurieren. Lambda setzt beispielsweise auf, AWS_XRAY_CONTEXT_MISSING um LOG_ERROR zu vermeiden, dass Laufzeitfehler vom X-Ray SDK ausgelöst werden. Um eine benutzerdefinierte Strategie für fehlenden Kontext festzulegen, überschreiben Sie die Umgebungsvariable in der Funktionskonfiguration so, dass sie keinen Wert aufweist. Dann können Sie die Strategie für fehlenden Kontext programmgesteuert festlegen.

Beispiel-Initialisierungscode

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

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

Weitere Informationen finden Sie unter Verwenden Sie Lambda-Umgebungsvariablen, um Werte im Code zu konfigurieren.

Nachdem Sie die richtigen Abhängigkeiten hinzugefügt und die erforderlichen Codeänderungen vorgenommen haben, aktivieren Sie die Ablaufverfolgung in der Konfiguration Ihrer Funktion über die Lambda-Konsole oder die. API

Aktivieren der Nachverfolgung mit der Lambda-Konsole

Gehen Sie folgendermaßen vor, um die aktive Nachverfolgung Ihrer Lambda-Funktion mit der Konsole umzuschalten:

So aktivieren Sie die aktive Nachverfolgung

1. Öffnen Sie die Seite Funktionen der Lambda-Konsole.

2. Wählen Sie eine Funktion aus.

3. Wählen Sie Configuration (Konfiguration) und dann Monitoring and operations tools (Überwachungs- und Produktionstools).

4. Wählen Sie Edit (Bearbeiten) aus.

5. Schalten Sie unter X-Ray Active tracing (Aktive Nachverfolgung) ein.

6. Wählen Sie Save (Speichern) aus.

Tracing mit dem Lambda aktivieren API

Konfigurieren Sie die Ablaufverfolgung für Ihre Lambda-Funktion mit dem AWS CLI oder AWS SDK und verwenden Sie die folgenden Operationen: API

• UpdateFunctionConfiguration

• GetFunctionConfiguration

• CreateFunction

Der folgende AWS CLI Beispielbefehl aktiviert die aktive Ablaufverfolgung für eine Funktion namens my-function.

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

Der Ablaufverfolgungsmodus ist Teil der versionsspezifischen Konfiguration, wenn Sie eine Version Ihrer Funktion veröffentlichen. Sie können den Ablaufverfolgungsmodus für eine veröffentlichte Version nicht ändern.

Die Ablaufverfolgung wird aktiviert mit AWS CloudFormation

Um die Ablaufverfolgung für eine AWS::Lambda::Function Ressource in einer AWS CloudFormation Vorlage zu aktivieren, verwenden Sie die TracingConfig Eigenschaft.

Beispiel function-inline.yml – Ablaufverfolgungskonfiguration

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

Verwenden Sie für eine AWS::Serverless::Function Ressource AWS Serverless Application Model (AWS SAM) die Tracing Eigenschaft.

Beispiel template.yml – Ablaufverfolgungskonfiguration

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

Interpretieren einer X-Ray-Nachverfolgung

Ihre Funktion benötigt die Berechtigung zum Hochladen von Trace-Daten zu X-Ray. Wenn Sie die aktive Nachverfolgung in der Lambda-Konsole aktivieren, fügt Lambda der Ausführungsrolle Ihrer Funktion die erforderlichen Berechtigungen hinzu. Andernfalls fügen Sie die AWSXRayDaemonWriteAccessRichtlinie der Ausführungsrolle hinzu.

Nachdem Sie die aktive Nachverfolgung konfiguriert haben, können Sie bestimmte Anfragen über Ihre Anwendung beobachten. Das X-Ray-Service-Diagramm zeigt Informationen über Ihre Anwendung und alle ihre Komponenten an. Das folgende Beispiel zeigt eine Anwendung mit zwei Funktionen. Die primäre Funktion verarbeitet Ereignisse und gibt manchmal Fehler zurück. Die zweite Funktion an oberster Stelle verarbeitet Fehler, die in der ersten Protokollgruppe auftreten, und verwendet die AWS SDK zum Aufrufen von X-Ray, Amazon Simple Storage Service (Amazon S3) und Amazon CloudWatch Logs.

X-Ray verfolgt nicht alle Anfragen an Ihre Anwendung nach. X-Ray wendet einen Sampling-Algorithmus an, um sicherzustellen, dass die Nachverfolgung effizient ist, und stellt dennoch ein repräsentatives Beispiel aller Anfragen bereit. Die Samplingrate beträgt 1 Anforderung pro Sekunde und 5 Prozent aller weiteren Anforderungen. Sie können die Röntgenabtastrate nicht für Ihre Funktionen konfigurieren.

In X-Ray, zeichnet eine Ablaufverfolgung Informationen zu einer Anforderung auf, die von einem oder mehreren Services verarbeitet wird. Lambda zeichnet 2 Segmente pro Trace auf, wodurch zwei Knoten im Service-Graph erstellt werden. In der folgenden Abbildung werden diese beiden Knoten hervorgehoben:

Der erste Knoten auf der linken Seite stellt den Lambda-Service dar, der die Aufrufanforderung empfängt. Der zweite Knoten stellt Ihre spezifische Lambda-Funktion dar. Das folgende Beispiel zeigt eine Nachverfolgung mit diesen zwei Segmenten. Beide haben den Namen my-function, aber eine hat einen Ursprung von AWS::Lambda und die andere hat einen Ursprung vonAWS::Lambda::Function. Wenn das AWS::Lambda Segment einen Fehler anzeigt, hatte der Lambda-Service ein Problem. Wenn das AWS::Lambda::Function Segment einen Fehler anzeigt, hatte Ihre Funktion ein Problem.

In diesem Beispiel wird das AWS::Lambda::Function Segment erweitert, sodass seine drei Untersegmente angezeigt werden.

Anmerkung

AWS implementiert derzeit Änderungen am Lambda-Service. Aufgrund dieser Änderungen können Sie geringfügige Unterschiede zwischen der Struktur und dem Inhalt von Systemprotokollnachrichten und Trace-Segmenten feststellen, die von verschiedenen Lambda-Funktionen in Ihrem AWS-Konto ausgegeben werden.

Der hier gezeigte Beispiel-Trace veranschaulicht das Funktionssegment im alten Stil. Die Unterschiede zwischen den Segmenten im alten und neuen Stil werden in den folgenden Abschnitten beschrieben.

Diese Änderungen werden in den kommenden Wochen umgesetzt, und alle Funktionen AWS-Regionen außer China und den GovCloud Regionen werden auf die Verwendung von Protokollnachrichten und Trace-Segmenten im neuen Format umgestellt.

Das Funktionssegment im alten Stil enthält die folgenden Untersegmente:

• Initialisierung – Stellt die Zeit dar, die für das Laden Ihrer Funktion und das Ausführen des Initialisierungscodes aufgewendet wurde. Dieses Untersegment erscheint nur für das erste Ereignis, das jede Instance Ihrer Funktion verarbeitet.

• Invocation (Aufruf) – Stellt die Zeit dar, die beim Ausführen Ihres Handler-Codes vergeht.

• Overhead (Aufwand) – Stellt die Zeit dar, die von der Lambda-Laufzeitumgebung bei der Verarbeitung des nächsten Ereignisses verbraucht wird.

Das Funktionssegment im neuen Stil enthält kein Untersegment. Invocation Stattdessen werden Kundenuntersegmente direkt an das Funktionssegment angehängt. Weitere Informationen zur Struktur der Funktionssegmente im alten und neuen Stil finden Sie unter. Grundlegendes zu X-Ray-Ablaufverfolgungen

Sie können auch HTTP Clients instrumentieren, SQL Abfragen aufzeichnen und benutzerdefinierte Untersegmente mit Anmerkungen und Metadaten erstellen. Weitere Informationen finden Sie unter AWS X-Ray-SDK for Node.js im AWS X-Ray -Entwicklerhandbuch.

Preisgestaltung

Im Rahmen des kostenlosen Kontingents können Sie X-Ray Tracing jeden Monat bis zu einem bestimmten Limit AWS kostenlos nutzen. Über den Schwellenwert hinaus berechnet X-Ray Gebühren für die Speicherung und den Abruf der Nachverfolgung. Weitere Informationen finden Sie unter AWS X-Ray Preise.

Speichern von Laufzeitabhängigkeiten in einer Ebene (X-RaySDK)

Wenn Sie X-Ray verwendenSDK, um AWS SDK Clients Ihren Funktionscode zu instrumentieren, kann Ihr Bereitstellungspaket ziemlich umfangreich werden. Um zu vermeiden, dass bei jeder Aktualisierung Ihres Funktionscodes Laufzeitabhängigkeiten hochgeladen werden, packen Sie das X-Ray SDK in eine Lambda-Schicht.

Das folgende Beispiel zeigt eine AWS::Serverless::LayerVersion-Ressource, die das AWS X-Ray-SDK for Node.js speichert.

Beispiel template.yml – Abhängigkeitenebene

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

Bei dieser Konfiguration aktualisieren Sie die Bibliotheksebene nur, wenn Sie Ihre Laufzeitabhängigkeiten ändern. Da das Funktionsbereitstellungspaket nur Ihren Code enthält, kann dies dazu beitragen, die Upload-Zeiten zu reduzieren.

Das Erstellen einer Ebene für Abhängigkeiten erfordert Build-Konfigurationsänderungen, um das Ebenen-Archiv vor der Bereitstellung zu generieren. Ein funktionierendes Beispiel finden Sie in der Beispielanwendung blank-nodejs .