Node.js Code instrumentieren 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 es verwenden X-Ray, um eine Anfrage zu verfolgen, während sie Ressourcen in Ihrer Anwendung durchquert, zu denen Lambda-Funktionen und andere AWS Dienste gehören können.

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

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

• AWS X-Ray-SDK für Node.js— Ein SDK zum Generieren und Senden von Trace-Daten an. X-Ray

Jedes der SDKs bietet Möglichkeiten, Ihre Telemetriedaten an den X-Ray Dienst zu senden. Anschließend können Sie X-Ray die Leistungskennzahlen Ihrer Anwendung anzeigen, filtern und Einblicke in sie gewinnen, um Probleme und Optimierungsmöglichkeiten zu identifizieren.

Wichtig

Die SDKs X-Ray und Powertools für AWS Lambda SDKs sind Teil einer eng integrierten Instrumentierungslösung, die von angeboten wird. AWS Die ADOT Lambda Layers sind Teil eines branchenweiten Standards für die Verfolgung von Instrumenten, die im Allgemeinen mehr Daten erfassen, aber möglicherweise nicht für alle Anwendungsfälle geeignet sind. Sie können mit beiden Lösungen eine durchgängige Ablaufverfolgung implementieren. X-Ray Weitere Informationen zur Auswahl zwischen beiden finden Sie unter Auswahl zwischen der AWS Distribution for Open Telemetry und SDKs. X-Ray

Verwenden Sie ADOT zur Instrumentierung Ihrer Funktionen Node.js

ADOT bietet vollständig verwaltete Lambda-Ebenen, die alles packen, was Sie zum Sammeln von Telemetriedaten mit dem OTel-SDK benötigen. Indem Sie diese Ebene verwenden, können Sie Ihre Lambda-Funktionen instrumentieren, ohne einen Funktionscode ändern zu müssen. Sie können Ihren Ebenen auch für die benutzerdefinierte Initialisierung von OTel konfigurieren. Weitere Informationen finden Sie unter Benutzerdefinierte Konfiguration für den ADOT Collector auf Lambda in der ADOT-Dokumentation.

Für Node.js Laufzeiten 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 unter AWS Distro for OpenTelemetry Lambda Support for JavaScript in der ADOT-Dokumentation.

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

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

Beispiel leer- .json nodejs/package

{
  "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 für JavaScript instrumentieren, schließen Sie die Client-Instanz mit der captureAWSv3Client Methode ein.

Beispiel leer — nodejs/function /index.js — Auf der Suche nach einem AWS SDK-Client

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 Beispiel-Initialisierungscode

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

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

Weitere Informationen finden Sie unter Arbeiten mit Lambda-Umgebungsvariablen.

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 wie folgt vor, um die aktive Ablaufverfolgung in Ihrer Lambda-Ereignisfunktion mit der Konsole umzuschalten:

So aktivieren Sie die aktive Nachverfolgung

1. Öffnen Sie die Seite Event Functions der Lambda-Konsole.

2. Wählen Sie eine Event-Funktion aus.

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

4. Wählen Sie unter Zusätzliche Überwachungstools die Option Bearbeiten aus.

5. Wählen Sie unter CloudWatch Anwendungssignale und AWS X-Ray die Option Enable for Lambda Service Traces aus.

6. Wählen Sie Speichern.

Aktivieren der Nachverfolgung mit der Lambda-API

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

• 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 CloudFormation

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

Beispiel function-inline.yml — Konfiguration für die Ablaufverfolgung

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

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

Beispiel template.yml — Konfiguration für die Ablaufverfolgung

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

Interpretieren und X-Ray Trace

Ihre Event-Funktion benötigt die Erlaubnis, Trace-Daten hochzuladen X-Ray. Wenn Sie die Ablaufverfolgung in der Lambda-Konsole aktivieren, fügt Lambda der Ausführungsrolle Ihrer Event-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 Dienstdiagramm zeigt Informationen zu Ihrer Anwendung und all ihren Komponenten. 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 Protokollgruppe der ersten auftreten, und verwendet das AWS SDK X-Ray, um Amazon Simple Storage Service (Amazon S3) und Amazon CloudWatch Logs aufzurufen.

X-Ray verfolgt nicht alle Anfragen bis zu Ihrer Anwendung. X-Ray wendet einen Stichprobenalgorithmus an, um sicherzustellen, dass die Rückverfolgung effizient ist und gleichzeitig eine repräsentative Stichprobe aller Anfragen bereitgestellt wird. Die Samplingrate beträgt 1 Anforderung pro Sekunde und 5 Prozent aller weiteren Anforderungen. Sie können die X-Ray Samplingrate für Ihre Funktionen nicht konfigurieren.

In X-Ray zeichnet ein Trace Informationen über eine Anfrage auf, die von einem oder mehreren Diensten verarbeitet wird. Lambda zeichnet 2 Segmente pro Trace auf, wodurch zwei Knoten im Dienstgraphen entstehen. 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 heißen my-function, aber einer hat einen Ursprung von AWS::Lambda und der andere hat einen Ursprung von AWS::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, ist bei Ihrer Funktion ein Problem aufgetreten.

Dieses Beispiel erweitert das AWS::Lambda::Function-Segment, um seine drei Untersegmente anzuzeigen.

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-Ereignisfunktionen 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 im 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 der Protokollnachrichten und Trace-Segmente 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 Invocation-Untersegment. Stattdessen werden Kundenuntersegmente direkt an das Funktionssegment angehängt. Weitere Informationen über die Struktur der alten und neuen Funktionssegmente finden Sie unter X-Ray Spuren verstehen.

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 für 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 kostenlos nutzen. AWS Bei Überschreitung dieses Schwellenwerts X-Ray fallen Gebühren für die Speicherung und den Abruf von Trace an. Weitere Informationen finden Sie unter AWS X-Ray Preise.

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

Wenn Sie das X-Ray SDK verwenden, 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 für Node.js speichert.

Beispiel template.yml — Abhängigkeitsebene

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:
        - nodejs24.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-Änderungen, um das Layer-Archiv vor der Bereitstellung zu generieren. Ein funktionierendes Beispiel finden Sie in der Beispielanwendung blank-nodejs .