Nachverfolgen von AWS SDK-Aufrufen mit dem X-Ray SDK for Node.js

Wenn Ihre Anwendung Aufrufe an tätigt, AWS-Services um Daten zu speichern, in eine Warteschlange zu schreiben oder Benachrichtigungen zu senden, verfolgt das X-Ray SDK for Node.js die Aufrufe nachgelagert in Untersegmenten . Nachverfolgte AWS-Services, und Ressourcen, auf die Sie innerhalb dieser Services zugreifen (z. B. ein Amazon S3-Bucket oder eine Amazon SQS-Warteschlange), werden als nachgelagerte Knoten auf der Trace-Map in der X-Ray-Konsole angezeigt.

Instrumentieren Sie AWS SDK-Clients, die Sie über die AWS SDK for JavaScript V2 oder AWS SDK for JavaScript V3 erstellen. Jede AWS SDK-Version bietet verschiedene Methoden zur Instrumentierung von AWS SDK-Clients.

Anmerkung

Derzeit gibt das AWS X-Ray SDK for Node.js beim Instrumentieren von AWS SDK for JavaScript V3-Clients weniger Segmentinformationen zurück als beim Instrumentieren von V2-Clients. Beispielsweise geben Untersegmente, die Aufrufe an DynamoDB darstellen, den Tabellennamen nicht zurück. Wenn Sie diese Segmentinformationen in Ihren Ablaufverfolgungen benötigen, sollten Sie die Verwendung von AWS SDK for JavaScript V2 in Betracht ziehen.

AWS SDK for JavaScript V2

Sie können alle AWS SDK-V2-Clients instrumentieren, indem Sie Ihre aws-sdk Anforderungsanweisung in einen Aufruf von packenAWSXRay.captureAWS.

Beispiel app.js – AWS SDK-Instrumentierung

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

Um einzelne Clients zu instrumentieren, schließen Sie Ihren AWS SDK-Client in einen Aufruf von einAWSXRay.captureAWSClient. Instrumentieren Sie beispielsweise einen AmazonDynamoDB-Client wie folgt:

Beispiel app.js – DynamoDB-Client-Instrumentierung

    const AWSXRay = require('aws-xray-sdk');
...
    const ddb = AWSXRay.captureAWSClient(new AWS.DynamoDB());

Warnung

Verwenden Sie nicht captureAWS und captureAWSClient zusammen. Dies führt zu doppelten Untersegmenten.

Wenn Sie TypeScript mit ECMAScript-Modulen (ESM) verwenden möchten, um Ihren JavaScript Code zu laden, verwenden Sie das folgende Beispiel, um Bibliotheken zu importieren:

Beispiel app.js – AWS SDK-Instrumentierung

import * as AWS from 'aws-sdk';
import * as AWSXRay from 'aws-xray-sdk';

Verwenden Sie den folgenden Code, um alle AWS Clients mit ESM zu instrumentieren:

Beispiel app.js – AWS SDK-Instrumentierung

import * as AWS from 'aws-sdk';
import * as AWSXRay from 'aws-xray-sdk';
const XRAY_AWS = AWSXRay.captureAWS(AWS);
const ddb = new XRAY_AWS.DynamoDB();

Für alle Services können Sie den Namen der API mit dem Namen in der X-Ray-Konsole sehen. Für eine Teilmenge von -Services fügt das X-Ray-SDK dem Segment Informationen hinzu, um mehr Granularität in der Service-Übersicht zu gewährleisten.

Wenn Sie beispielsweise einen Aufruf mit einem instrumentierten DynamoDB-Client tätigen, fügt das SDK dem Segment den Tabellennamen für Aufrufe hinzu, die auf eine Tabelle abzielen. In der Konsole wird jede Tabelle als separater Knoten in der Service-Übersicht angezeigt, mit einem generischen DynamoDB-Knoten für Aufrufe, die keine Tabelle anvisieren.

Beispiel Untersegment für einen Aufruf an DynamoDB zum Speichern eines Elements

{
  "id": "24756640c0d0978a",
  "start_time": 1.480305974194E9,
  "end_time": 1.4803059742E9,
  "name": "DynamoDB",
  "namespace": "aws",
  "http": {
    "response": {
      "content_length": 60,
      "status": 200
    }
  },
  "aws": {
    "table_name": "scorekeep-user",
    "operation": "UpdateItem",
    "request_id": "UBQNSO5AEM8T4FDA4RQDEB94OVTDRVV4K4HIRGVJF66Q9ASUAAJG",
  }
}

Wenn Sie auf benannte Ressourcen zugreifen, werden durch Aufrufe der folgenden Services weitere Knoten in der Service-Übersicht erstellt. Durch Aufrufe, die keinen bestimmten Ressourcen gelten, wird ein generischer Knoten für den Service erstellt.

• Amazon DynamoDB – Tabellenname

• Amazon Simple Storage Service – Bucket- und Schlüsselname

• Amazon Simple Queue Service – Name der Warteschlange

AWS SDK for JavaScript V3

Die AWS SDK for JavaScript V3 ist modular, sodass Ihr Code nur die benötigten Module lädt. Aus diesem Grund ist es nicht möglich, alle AWS SDK-Clients zu instrumentieren, da V3 die captureAWS Methode nicht unterstützt.

Wenn Sie TypeScript mit ECMAScript Modules (ESM) verwenden möchten, um Ihren JavaScript Code zu laden, können Sie das folgende Beispiel verwenden, um Bibliotheken zu importieren:

import * as AWS from 'aws-sdk';
import * as AWSXRay from 'aws-xray-sdk';

Instrumentieren Sie jeden AWS SDK-Client mit der -AWSXRay.captureAWSv3ClientMethode. Instrumentieren Sie beispielsweise einen AmazonDynamoDB-Client wie folgt:

Beispiel app.js – DynamoDB-Client-Instrumentierung mit -SDK für Javascript V3

    const AWSXRay = require('aws-xray-sdk');
    const { DynamoDBClient } = require("@aws-sdk/client-dynamodb");
...
    const ddb = AWSXRay.captureAWSv3Client(new DynamoDBClient({ region: "region" }));

Bei Verwendung von AWS SDK for JavaScript V3 werden Metadaten wie Tabellenname, Bucket- und Schlüsselname oder Warteschlangenname derzeit nicht zurückgegeben, daher enthält die Ablaufverfolgungszuordnung keine diskreten Knoten für jede benannte Ressource wie bei der Instrumentierung von AWS SDK-Clients mit der AWS SDK for JavaScript V2.

Beispiel Untersegment für einen Aufruf an DynamoDB zum Speichern eines Elements bei Verwendung von AWS SDK for JavaScript V3

{
  "id": "24756640c0d0978a",
  "start_time": 1.480305974194E9,
  "end_time": 1.4803059742E9,
  "name": "DynamoDB",
  "namespace": "aws",
  "http": {
    "response": {
      "content_length": 60,
      "status": 200
    }
  },
  "aws": {
    "operation": "UpdateItem",
    "request_id": "UBQNSO5AEM8T4FDA4RQDEB94OVTDRVV4K4HIRGVJF66Q9ASUAAJG",
  }
}