Instrumentierung von Node.js Code in AWS Lambda

Lambda lässt sich mit integrieren AWS X-Ray , um Ihnen beim Nachverfolgen, Debuggen und Optimieren von Lambda-Anwendungen zu helfen. Sie können es verwenden X-Ray, um eine Anfrage zu verfolgen, während sie Ressourcen in Ihrer Anwendung durchläuft. Dazu können Lambda-Funktionen und andere Dienste gehören. AWS

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

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.

Verwenden Sie ADOT, um Ihre Funktionen zu instrumentieren 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-Layer für ADOT-Javascript hinzufügen, um Ihre Funktionen automatisch zu instrumentieren. Eine detaillierte Anleitung zum Hinzufügen dieser Ebene finden Sie unter AWS Distro for OpenTelemetry Lambda Support in der ADOT-Dokumentation. JavaScript

Verwenden Sie das X-Ray SDK, um Ihre Funktionen zu instrumentieren Node.js

Um Details zu Aufrufen aufzuzeichnen, die Ihre Lambda-Funktion an andere Ressourcen in Ihrer Anwendung vornimmt, können Sie auch 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.

{
  "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, umschließen Sie die Client-Instanz mit der captureAWSv3Client Methode.

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 legt beispielsweise auf fest, AWS_XRAY_CONTEXT_MISSING um LOG_ERROR zu vermeiden, dass Laufzeitfehler aus dem 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.

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 folgendermaßen vor, um die aktive Nachverfolgung Ihrer Lambda-Funktion mit der Konsole umzuschalten:

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:

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 Protokollierung wird aktiviert mit CloudFormation

Verwenden Sie die Eigenschaft, um die Protokollierung AWS::Lambda::Function für eine Ressource in einer CloudFormation Vorlage zu aktivieren. TracingConfig

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.

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

Interpretieren einer Ablaufverfolgung X-Ray

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 AWSXRayDaemonWriteAccess Richtlinie 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 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 oben verarbeitet Fehler, die in der ersten Protokollgruppe erscheinen, 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 an Ihre Anwendung zurück. X-Ray wendet einen Stichprobenalgorithmus an, um sicherzustellen, dass die Ablaufverfolgung effizient ist, und liefert gleichzeitig eine repräsentative Stichprobe aller Anfragen. 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.

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

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 Grundlegendes zu X-Ray Spuren.

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.

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-Ebene.

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

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 .