AWS X-Ray-SDK für Node.js - AWS X-Ray
VoraussetzungenAbhängigkeitsmanagementNode.js-BeispieleKonfigurationEingehende AnforderungenAusgehende HTTP-AufrufeSQL-AbfragenBenutzerdefinierte UntersegmenteAnmerkungen und Metadaten

Die vorliegende Übersetzung wurde maschinell erstellt. Im Falle eines Konflikts oder eines Widerspruchs zwischen dieser übersetzten Fassung und der englischen Fassung (einschließlich infolge von Verzögerungen bei der Übersetzung) ist die englische Fassung maßgeblich.

AWS X-Ray-SDK für Node.js

Das X-Ray-SDK für Node.js ist eine Bibliothek für Express-Webanwendungen und Node.js Lambda-Funktionen, die Klassen und Methoden zum Generieren und Senden von Trace-Daten an den X-Ray-Daemon bereitstellt. Zu den Trace-Daten gehören Informationen über eingehende HTTP-Anfragen, die von der Anwendung bedient werden, sowie über Aufrufe, die die Anwendung mithilfe des AWS SDK oder der HTTP-Clients an nachgeschaltete Dienste sendet.

Anmerkung

Das X-Ray SDK für Node.js ist ein Open-Source-Projekt. Sie können das Projekt verfolgen und Issues und Pull-Requests einreichen unter GitHub: github.com/aws/ aws-xray-sdk-node

Wenn Sie Express nutzen, beginnen Sie, indem Sie das SDK als Middleware auf Ihrem Anwendungsserver hinzufügen, um eingehende Anforderungen zu verfolgen. Der Middleware erstellt für jede verfolgte Anforderung ein Segment und vervollständigt das Segment, nachdem die Antwort gesendet wurde. Während das Segment geöffnet ist, können Sie die SDK-Client-Methoden nutzen, um dem Segment Informationen hinzuzufügen, Untersegmente zu erstellen und nachgelagerte Aufrufe rückzuverfolgen. Das SDK erfasst auch automatisch Ausnahmen, die Ihre Anwendung ausgibt, während das Segment geöffnet ist.

Bei Lambda-Funktionen, die von einer instrumentierten Anwendung oder einem Dienst aufgerufen werden, liest Lambda den Tracing-Header und verfolgt automatisch Sampling-Anfragen. Für andere Funktionen können Sie Lambda so konfigurieren, dass eingehende Anfragen abgefragt und verfolgt werden. In beiden Fällen erstellt Lambda das Segment und stellt es dem X-Ray SDK zur Verfügung.

Anmerkung

Auf Lambda ist das X-Ray SDK optional. Wenn Sie es nicht in Ihrer Funktion verwenden, enthält Ihre Service-Map immer noch einen Knoten für den Lambda-Service und einen für jede Lambda-Funktion. Durch Hinzufügen des SDK können Sie Ihren Funktionscode instrumentieren, um Untersegmente zu dem von Lambda aufgezeichneten Funktionssegment hinzuzufügen. Weitere Informationen finden Sie unter AWS Lambda und AWS X-Ray.

Verwenden Sie als Nächstes das X-Ray-SDK für Node.js, um Ihr AWS SDK für die Clients JavaScript in Node.js zu instrumentieren. Immer wenn Sie einen Downstream AWS-Service oder eine Ressource mit einem instrumentierten Client aufrufen, zeichnet das SDK Informationen über den Anruf in einem Untersegment auf. AWS-Services und die Ressourcen, auf die Sie innerhalb der Services zugreifen, werden in der Trace-Map als Downstream-Knoten angezeigt, sodass Sie Fehler und Drosselungsprobleme bei einzelnen Verbindungen leichter identifizieren können.

Das X-Ray-SDK für Node.js bietet auch Instrumentierung für Downstream-Aufrufe von HTTP-Web-APIs und SQL-Abfragen. Umhüllen Sie den HTTP-Client in der SDK-Erfassungsmethode, um Informationen zu ausgehenden HTTP-Anforderungen aufzuzeichnen. Für SQL-Clients verwenden Sie die Capture-Methode für Ihre Datenbank.

Die Middleware wendet Samplingregeln auf eingehende Anforderungen an, um zu ermitteln, welche Anforderungen rückverfolgt werden. Sie können das X-Ray SDK für Node.js konfigurieren, um das Sampling-Verhalten anzupassen oder Informationen über die AWS Rechenressourcen aufzuzeichnen, auf denen Ihre Anwendung ausgeführt wird.

Zeichnen Sie zusätzliche Informationen zu Anforderungen und den Aufgaben, die Ihre Anwendung ausführt, in Anmerkungen und Metadaten auf. Anmerkungen sind einfache Schlüsselwertpaare, die für die Verwendung mit Filterausdrücken indiziert werden, damit Sie nach Ablaufverfolgen mit bestimmten Daten suchen können. Metadateneinträge sind weniger einschränkend und können ganze Objekte und Arrays aufzeichnen – alle Daten, die in eine JSON zusammengefasst werden können.

Anmerkungen und Metadaten

Anmerkungen und Metadaten sind beliebiger Text, den Sie mit dem X-Ray SDK zu Segmenten hinzufügen. Anmerkungen werden für die Verwendung mit Filterausdrücken indexiert. Metadaten werden nicht indexiert, können aber im Rohsegment mit der X-Ray-Konsole oder API angezeigt werden. Jeder, dem Sie Lesezugriff auf X-Ray gewähren, kann diese Daten einsehen.

Wenn Sie viele instrumentierten Clients in Ihrem Code haben, kann ein einzelnes Anforderungssegmente viele Untersegmente enthalten, eines für jeden Aufruf mit einem instrumentierten Client. Sie können Untersegmente organisieren und gruppieren, indem Sie Client-Aufrufe in benutzerdefinierten Untersegmenten zusammenfassen. Sie können ein benutzerdefiniertes Untersegment für eine ganze Funktion oder eine Code-Abschnitt erstellen und Metadaten und Anmerkungen im Untersegment festhalten, anstatt alles im übergeordneten Segment aufzuzeichnen.

Referenzdokumentation zu den Klassen und Methoden des SDK finden Sie in der API-Referenz zum AWS X-Ray SDK for Node.js.

Voraussetzungen

Das X-Ray SDK für Node.js benötigt Node.js und die folgenden Bibliotheken:

  • atomic-batcher— 1.0.2

  • cls-hooked— 4.2.2

  • pkginfo— 0,4,0

  • semver— 5,3,0

Das SDK zieht diese Bibliotheken bei der Installation in NPM ein.

Um AWS SDK-Clients verfolgen zu können, benötigt das X-Ray-SDK für Node.js eine Mindestversion des AWS SDK für JavaScript in Node.js.

  • aws-sdk— 2.7.15

Abhängigkeitsmanagement

Das X-Ray-SDK für Node.js ist bei NPM erhältlich.

Installieren Sie das SDK für eine lokale Bereitstellung in Ihrem Projektverzeichnis mit npm.

~/nodejs-xray$ npm install aws-xray-sdk
aws-xray-sdk@3.3.3
  ├─┬ aws-xray-sdk-core@3.3.3
  │ ├── @aws-sdk/service-error-classification@3.15.0
  │ ├── @aws-sdk/types@3.15.0
  │ ├─┬ @types/cls-hooked@4.3.3
  │ │ └── @types/node@15.3.0
  │ ├── atomic-batcher@1.0.2
  │ ├─┬ cls-hooked@4.2.2
  │ │ ├─┬ async-hook-jl@1.7.6
  │ │ │ └── stack-chain@1.3.7
  │ │ └─┬ emitter-listener@1.1.2
  │ │   └── shimmer@1.2.1
  │ └── semver@5.7.1
  ├── aws-xray-sdk-express@3.3.3
  ├── aws-xray-sdk-mysql@3.3.3
  └── aws-xray-sdk-postgres@3.3.3

Verwenden Sie die --save-Option zum Speichern von SDK in Abhängigkeit von package.json in Ihrer Anwendung.

~/nodejs-xray$ npm install aws-xray-sdk --save
aws-xray-sdk@3.3.3

Wenn Ihre Anwendung Abhängigkeiten hat, deren Versionen mit den Abhängigkeiten des X-Ray-SDK in Konflikt stehen, werden beide Versionen installiert, um die Kompatibilität sicherzustellen. Weitere Informationen finden Sie in der offiziellen NPM-Dokumentation zur Auflösung von Abhängigkeiten.

Node.js-Beispiele

Verwenden Sie das AWS X-Ray SDK für Node.js, um sich einen end-to-end Überblick über die Anfragen zu verschaffen, die Ihre Node.js -Anwendungen durchlaufen.

Konfiguration des X-Ray-SDK für Node.js

Sie können das X-Ray-SDK für Node.js mit Plug-ins so konfigurieren, dass es Informationen über den Dienst enthält, auf dem Ihre Anwendung ausgeführt wird, das standardmäßige Sampling-Verhalten ändern oder Sampling-Regeln hinzufügen, die für Anfragen an bestimmte Pfade gelten.

Service-Plugins

Wird verwendetplugins, um Informationen über den Dienst aufzuzeichnen, der Ihre Anwendung hostet.

Plug-ins

  • Amazon EC2 — EC2Plugin fügt die Instance-ID, die Availability Zone und die CloudWatch Logs-Gruppe hinzu.

  • Elastic Beanstalk — ElasticBeanstalkPlugin fügt den Umgebungsnamen, die Versionsbezeichnung und die Bereitstellungs-ID hinzu.

  • Amazon ECS — ECSPlugin fügt die Container-ID hinzu.

Um ein Plug-in zu verwenden, konfigurieren Sie das X-Ray SDK für den Client Node.js mithilfe der config Methode.

Beispiel app.js – Plugins
var AWSXRay = require('aws-xray-sdk');
AWSXRay.config([AWSXRay.plugins.EC2Plugin,AWSXRay.plugins.ElasticBeanstalkPlugin]);

Das SDK verwendet auch Plugin-Einstellungen, um das origin Feld für das Segment festzulegen. Dies gibt den AWS Ressourcentyp an, auf dem Ihre Anwendung ausgeführt wird. Wenn Sie mehrere Plugins verwenden, verwendet das SDK die folgende Auflösungsreihenfolge, um den Ursprung zu bestimmen: ElasticBeanstalk > EKS > ECS > EC2.

Samplingregeln

Das SDK verwendet die Sampling-Regeln, die Sie in der X-Ray-Konsole definieren, um zu bestimmen, welche Anfragen aufgezeichnet werden sollen. Die Standardregel verfolgt die erste Anfrage jede Sekunde und fünf Prozent aller weiteren Anfragen aller Dienste, die Traces an X-Ray senden. Erstellen Sie zusätzliche Regeln in der X-Ray-Konsole, um die Menge der aufgezeichneten Daten für jede Ihrer Anwendungen anzupassen.

Das SDK wendet benutzerdefinierte Regeln in der Reihenfolge an, in der sie definiert sind. Wenn eine Anfrage mehreren benutzerdefinierten Regeln entspricht, wendet das SDK nur die erste Regel an.

Anmerkung

Wenn das SDK X-Ray nicht erreichen kann, um Sampling-Regeln abzurufen, kehrt es zu einer lokalen Standardregel zurück, die die erste Anfrage pro Sekunde und fünf Prozent aller zusätzlichen Anfragen pro Host vorsieht. Dies kann passieren, wenn der Host nicht berechtigt ist, Sampling-APIs aufzurufen, oder wenn er keine Verbindung zum X-Ray-Daemon herstellen kann, der als TCP-Proxy für API-Aufrufe durch das SDK fungiert.

Sie können das SDK auch so konfigurieren, dass Sampling-Regeln aus einem JSON-Dokument geladen werden. Das SDK kann lokale Regeln als Backup für Fälle verwenden, in denen X-Ray Sampling nicht verfügbar ist, oder ausschließlich lokale Regeln verwenden.

Beispiel sampling-rules.json
{
  "version": 2,
  "rules": [
    {
      "description": "Player moves.",
      "host": "*",
      "http_method": "*",
      "url_path": "/api/move/*",
      "fixed_target": 0,
      "rate": 0.05
    }
  ],
  "default": {
    "fixed_target": 1,
    "rate": 0.1
  }
}

In diesem Beispiel werden eine benutzerdefinierte Regel und eine Standardregel definiert. Die benutzerdefinierte Regel wendet eine Stichprobenrate von fünf Prozent an, ohne dass eine Mindestanzahl von Anfragen für Pfade verfolgt werden muss. /api/move/ Die Standardregel verfolgt die erste Anfrage jede Sekunde und 10 Prozent der weiteren Anfragen.

Der Nachteil der lokalen Definition von Regeln besteht darin, dass das feste Ziel von jeder Instanz des Rekorders unabhängig angewendet wird, anstatt vom X-Ray-Dienst verwaltet zu werden. Wenn Sie mehr Hosts bereitstellen, wird die feste Rate vervielfacht, wodurch es schwieriger wird, die Menge der aufgezeichneten Daten zu kontrollieren.

Wenn aktiviert AWS Lambda, können Sie die Samplerate nicht ändern. Wenn Ihre Funktion von einem instrumentierten Dienst aufgerufen wird, werden Aufrufe, die Anfragen generierten, die von diesem Dienst abgetastet wurden, von Lambda aufgezeichnet. Wenn aktives Tracing aktiviert ist und kein Tracing-Header vorhanden ist, trifft Lambda die Stichprobenentscheidung.

Um Backup-Regeln zu konfigurieren, weisen Sie das X-Ray SDK for Node.js an, Sampling-Regeln aus einer Datei mit zu ladensetSamplingRules.

Beispiel app.js – Sampling-Regeln aus einer Datei
var AWSXRay = require('aws-xray-sdk');
AWSXRay.middleware.setSamplingRules('sampling-rules.json');

Sie können Ihre Regeln auch in Code definieren und als Objekt an setSamplingRules übergeben.

Beispiel app.js – Sampling-Regeln aus einem Objekt
var AWSXRay = require('aws-xray-sdk');
var rules = {
  "rules": [ { "description": "Player moves.", "service_name": "*", "http_method": "*", "url_path": "/api/move/*", "fixed_target": 0, "rate": 0.05 } ],
  "default": { "fixed_target": 1, "rate": 0.1 },
  "version": 1
  }

AWSXRay.middleware.setSamplingRules(rules);

Um nur lokale Regeln zu verwenden, rufen Sie disableCentralizedSampling auf.

AWSXRay.middleware.disableCentralizedSampling()

Protokollierung

Zum Protokollieren der SDK-Ausgabe rufen Sie AWSXRay.setLogger(logger) auf, wobei logger ein Objekt ist, dass Standard-Protokollierungsmethoden (warn, infousw.) bereitstellt.

Standardmäßig protokolliert das SDK Fehlermeldungen auf der Konsole mithilfe der Standardmethoden für das Konsolenobjekt. Die Protokollebene des integrierten Loggers kann entweder mithilfe der AWS_XRAY_LOG_LEVEL Umgebungsvariablen AWS_XRAY_DEBUG_MODE oder festgelegt werden. Eine Liste der gültigen Werte auf Protokollebene finden Sie unter Umgebungsvariablen.

Wenn Sie ein anderes Format oder ein anderes Ziel für die Protokolle angeben möchten, können Sie dem SDK Ihre eigene Implementierung der Logger-Schnittstelle zur Verfügung stellen, wie unten gezeigt. Jedes Objekt, das diese Schnittstelle implementiert, kann verwendet werden. Das bedeutet, dass viele Logging-Bibliotheken, z. B. Winston, verwendet und direkt an das SDK übergeben werden könnten.

Beispiel app.js – Protokollierung
var AWSXRay = require('aws-xray-sdk');

// Create your own logger, or instantiate one using a library.
var logger = {
  error: (message, meta) => { /* logging code */ },
  warn: (message, meta) => { /* logging code */ },
  info: (message, meta) => { /* logging code */ },
  debug: (message, meta) => { /* logging code */ }
}

AWSXRay.setLogger(logger);
AWSXRay.config([AWSXRay.plugins.EC2Plugin]);

Rufen Sie vor der Ausführung anderer Konfigurationsmethoden setLogger auf, um sicherzustellen, dass Sie die Ausgabe dieser Vorgänge erfassen.

Adresse des X-Ray-Daemons

Wenn der X-Ray-Daemon auf einem anderen Port oder Host lauscht als127.0.0.1:2000, können Sie das X-Ray-SDK für Node.js so konfigurieren, dass Trace-Daten an eine andere Adresse gesendet werden.

AWSXRay.setDaemonAddress('host:port');

Sie können den Host mit Namen oder IPv4-Adresse angeben.

Beispiel app.js – Daemon-Adresse
var AWSXRay = require('aws-xray-sdk');
AWSXRay.setDaemonAddress('daemonhost:8082');

Wenn Sie den Daemon so konfiguriert haben, dass er auf verschiedenen Ports für TCP und UDP wartet, können Sie beides in den Einstellungen für die Daemon-Adresse angeben.

Beispiel app.js – Daemon-Adresse auf separaten Ports
var AWSXRay = require('aws-xray-sdk');
AWSXRay.setDaemonAddress('tcp:daemonhost:8082 udp:daemonhost:8083');

Sie können die Daemon-Adresse auch festlegen, indem Sie die AWS_XRAY_DAEMON_ADDRESS Umgebungsvariable verwenden.

Umgebungsvariablen

Sie können Umgebungsvariablen verwenden, um das X-Ray SDK für Node.js zu konfigurieren. Das SDK unterstützt die folgenden Variablen.

  • AWS_XRAY_CONTEXT_MISSING— Legt fest, RUNTIME_ERROR dass Ausnahmen ausgelöst werden, wenn Ihr instrumentierter Code versucht, Daten aufzuzeichnen, obwohl kein Segment geöffnet ist.

    Zulässige Werte

    • RUNTIME_ERROR— Löst eine Laufzeitausnahme aus.

    • LOG_ERROR— Einen Fehler protokollieren und fortfahren (Standard).

    • IGNORE_ERROR— Fehler ignorieren und fortfahren.

    Fehler im Zusammenhang mit fehlenden Segmenten oder Untersegmenten können auftreten, wenn Sie versuchen, einen instrumentierten Client in Startcode zu verwenden, der ausgeführt wird, wenn keine Anfrage geöffnet ist, oder in Code, der einen neuen Thread erzeugt.

  • AWS_XRAY_DAEMON_ADDRESS— Legt den Host und den Port des X-Ray-Daemon-Listeners fest. Standardmäßig verwendet 127.0.0.1:2000 das SDK sowohl Trace-Daten (UDP) als auch Sampling-Daten (TCP). Verwenden Sie diese Variable, wenn Sie den Daemon so konfiguriert haben, dass er auf einem anderen Port lauscht oder wenn er auf einem anderen Host läuft.

    Format

    • Derselbe Port — address:port

    • Verschiedene Anschlüsse — tcp:address:port udp:address:port

  • AWS_XRAY_DEBUG_MODE— Stellen Sie diese Option einTRUE, um das SDK so zu konfigurieren, dass es Protokolle auf debug Ebene 2 ausgibt.

  • AWS_XRAY_LOG_LEVEL — Legt eine Protokollebene für den Standard-Logger fest. Gültige Werte sind debug, info, warn, error und silent. Dieser Wert wird ignoriert, wenn AWS_XRAY_DEBUG_MODE auf TRUE gesetzt ist.

  • AWS_XRAY_TRACING_NAME— Legen Sie einen Dienstnamen fest, den das SDK für Segmente verwendet. Überschreibt den für die Express-Middleware festgelegten Segmentnamen.

Nachverfolgung eingehender Anfragen mit dem X-Ray SDK für Node.js

Sie können das X-Ray-SDK für Node.js verwenden, um eingehende HTTP-Anfragen zu verfolgen, die Ihre Express- und Restify-Anwendungen auf einer EC2-Instance in Amazon EC2 oder Amazon ECS bearbeiten. AWS Elastic Beanstalk

Das X-Ray SDK für Node.js bietet Middleware für Anwendungen, die die Express- und Restify-Frameworks verwenden. Wenn Sie die X-Ray-Middleware zu Ihrer Anwendung hinzufügen, erstellt das X-Ray-SDK für Node.js ein Segment für jede gesampelte Anfrage. Dieses Segment umfasst Dauer, Methode und Status der HTTP-Anforderung. Die zusätzliche Instrumentierung schafft Untersegmente zu diesem Segment.

Anmerkung

Für AWS Lambda Funktionen erstellt Lambda für jede abgetastete Anfrage ein Segment. Weitere Informationen finden Sie unter AWS Lambda und AWS X-Ray.

Jedes Segment hat einen Namen, der Ihre Anwendung in der Service Map identifiziert. Das Segment kann statisch benannt werden, oder Sie können das SDK so konfigurieren, dass es dynamisch auf der Grundlage des Host-Headers in der eingehenden Anfrage benannt wird. Mit der dynamischen Benennung können Sie Traces auf der Grundlage des Domainnamens in der Anfrage gruppieren und einen Standardnamen anwenden, wenn der Name nicht einem erwarteten Muster entspricht (z. B. wenn der Host-Header gefälscht ist).

Weitergeleitete Anfragen

Wenn ein Load Balancer oder ein anderer Vermittler eine Anfrage an Ihre Anwendung weiterleitet, nimmt X-Ray die Client-IP aus dem X-Forwarded-For Header in der Anfrage und nicht aus der Quell-IP im IP-Paket. Die Client-IP, die für eine weitergeleitete Anfrage aufgezeichnet wird, kann gefälscht sein und sollte daher nicht als vertrauenswürdig eingestuft werden.

Wenn eine Anfrage weitergeleitet wird, legt das SDK ein zusätzliches Feld im Segment fest, um dies anzuzeigen. Wenn das Segment das Feld enthält, das auf x_forwarded_for gesetzt isttrue, wurde die Client-IP aus dem X-Forwarded-For Header in der HTTP-Anfrage übernommen.

Der Meldungshandler erzeugt für jede eingehende Anforderung ein Segment mit einem http-Block, der die folgenden Informationen enthält:

  • HTTP-Methode — GET, POST, PUT, DELETE usw.

  • Client-Adresse — Die IP-Adresse des Clients, der die Anfrage gesendet hat.

  • Antwortcode — Der HTTP-Antwortcode für die abgeschlossene Anfrage.

  • Timing — Die Startzeit (als die Anfrage empfangen wurde) und die Endzeit (als die Antwort gesendet wurde).

  • Benutzeragent — Der user-agent aus der Anfrage.

  • Länge des Inhalts — Die Länge content-length der Antwort.

Nachverfolgung eingehender Anforderungen mit Express

Zum Verwenden der Express-Middleware initialisieren Sie den SDK-Client und nutzen Sie die Middleware, die von der express.openSegment-Funktion zurückgegeben wird, bevor Sie Ihre Routen festlegen.

Beispiel app.js – Express
var app = express();

var AWSXRay = require('aws-xray-sdk');
app.use(AWSXRay.express.openSegment('MyApp'));

app.get('/', function (req, res) {
  res.render('index');
});

app.use(AWSXRay.express.closeSegment());

Nachdem Sie Ihre Routen definiert haben, verwenden Sie die Ausgabe von express.closeSegment wie abgebildet, um alle Fehler zu behandeln, die vom X-Ray SDK für Node.js zurückgegeben werden.

Nachverfolgung eingehender Anforderungen mit Restify

Um die Restify-Middleware zu verwenden, initialisieren Sie den SDK-Client und führen Sie enable aus. Übergeben Sie den Namen Ihres Restify-Servers und des Segments.

Beispiel app.js – Restify
var AWSXRay = require('aws-xray-sdk');
var AWSXRayRestify = require('aws-xray-sdk-restify');

var restify = require('restify');
var server = restify.createServer();
AWSXRayRestify.enable(server, 'MyApp'));

server.get('/', function (req, res) {
  res.render('index');
});

Konfiguration einer Segmentbenennungsstrategie

AWS X-Ray verwendet einen Dienstnamen, um Ihre Anwendung zu identifizieren und sie von den anderen Anwendungen, Datenbanken, externen APIs und AWS Ressourcen zu unterscheiden, die Ihre Anwendung verwendet. Wenn das X-Ray SDK Segmente für eingehende Anfragen generiert, zeichnet es den Dienstnamen Ihrer Anwendung im Namensfeld des Segments auf.

Das X-Ray SDK kann Segmente nach dem Hostnamen im HTTP-Anforderungsheader benennen. Dieser Header kann jedoch gefälscht sein, was zu unerwarteten Knoten in Ihrer Service Map führen kann. Um zu verhindern, dass das SDK Segmente aufgrund von Anfragen mit gefälschten Host-Headern falsch benennt, müssen Sie einen Standardnamen für eingehende Anfragen angeben.

Wenn Ihre Anwendung Anfragen für mehrere Domänen bearbeitet, können Sie das SDK so konfigurieren, dass es eine dynamische Benennungsstrategie verwendet, um dies in Segmentnamen widerzuspiegeln. Eine dynamische Benennungsstrategie ermöglicht es dem SDK, den Hostnamen für Anfragen zu verwenden, die einem erwarteten Muster entsprechen, und den Standardnamen auf Anfragen anzuwenden, bei denen dies nicht der Fall ist.

Beispielsweise könnten Sie eine einzige Anwendung haben, die Anfragen an drei Subdomänen — www.example.comapi.example.com, und — bedient. static.example.com Sie können eine dynamische Benennungsstrategie mit dem Muster verwenden*.example.com, um Segmente für jede Subdomain mit einem anderen Namen zu identifizieren, was zu drei Dienstknoten auf der Service-Map führt. Wenn Ihre Anwendung Anfragen mit einem Hostnamen empfängt, der nicht dem Muster entspricht, wird auf der Service Map ein vierter Knoten mit einem von Ihnen angegebenen Fallback-Namen angezeigt.

Wenn Sie denselben Namen für alle Segmente verwenden möchten, geben Sie bei der Initialisierung der Middleware den Namen Ihrer Anwendung, wie in den vorherigen Abschnitten gezeigt, ein.

Anmerkung

Sie können den mit der AWS_XRAY_TRACING_NAME-Umgebungsvariablen in Code definierten standardmäßigen Dienstnamen überschreiben.

Eine dynamische Benennungsstrategie definiert ein Muster, dem Hostnamen entsprechen sollten, sowie einen Standardnamen, der verwendet wird, wenn der Hostname in der HTTP-Anforderung nicht mit diesem Muster übereinstimmt. Zur dynamischen Segmentbenennung verwenden Sie AWSXRay.middleware.enableDynamicNaming.

Beispiel app.js – dynamische Segmentnamen

Wenn der Hostname in der Anforderung dem Muster *.example.com entspricht, verwenden Sie den Hostnamen. Verwenden Sie andernfalls MyApp.

var app = express();

var AWSXRay = require('aws-xray-sdk');
app.use(AWSXRay.express.openSegment('MyApp'));
AWSXRay.middleware.enableDynamicNaming('*.example.com');
        
app.get('/', function (req, res) {
  res.render('index');
});

app.use(AWSXRay.express.closeSegment());

Verfolgen von Aufrufen an Downstream-HTTP-Webservices mithilfe des X-Ray SDK für Node.js

Wenn Ihre Anwendung Microservices oder öffentliche HTTP-APIs aufruft, können Sie den X-Ray SDK for Node.js Client verwenden, um diese Aufrufe zu instrumentieren und die API als Downstream-Service zum Service Graph hinzuzufügen.

Übergeben Sie Ihren http oder https Client an die captureHTTPs Methode X-Ray SDK for Node.js, um ausgehende Anrufe zu verfolgen.

Anmerkung

Aufrufe, die HTTP-Anforderungsbibliotheken von Drittanbietern wie Axios oder Superagent verwenden, werden durch die captureHTTPsGlobal()-API unterstützt und werden weiterhin nachverfolgt, wenn sie das http-Modul verwenden.

Beispiel app.js – HTTP-Client
var AWSXRay = require('aws-xray-sdk');
var http = AWSXRay.captureHTTPs(require('http'));

Zur Aktivierung der Nachverfolgung auf allen HTTP-Clients rufen Sie captureHTTPsGlobal auf, bevor Sie http laden.

Beispiel app.js – HTTP-Client (Global)
var AWSXRay = require('aws-xray-sdk');
AWSXRay.captureHTTPsGlobal(require('http'));
var http = require('http');

Wenn Sie einen Aufruf einer Downstream-Web-API instrumentieren, zeichnet das X-Ray-SDK für Node.js ein Untersegment auf, das Informationen über die HTTP-Anfrage und -Antwort enthält. X-Ray verwendet das Untersegment, um ein abgeleitetes Segment für die Remote-API zu generieren.

Beispiel Untersegment für einen nachgelagerten HTTP-Aufruf
{
  "id": "004f72be19cddc2a",
  "start_time": 1484786387.131,
  "end_time": 1484786387.501,
  "name": "names.example.com",
  "namespace": "remote",
  "http": {
    "request": {
      "method": "GET",
      "url": "https://names.example.com/"
    },
    "response": {
      "content_length": -1,
      "status": 200
    }
  }
}
Beispiel Abgeleitetes Segment für einen nachgelagerten HTTP-Anruf
{
  "id": "168416dc2ea97781",
  "name": "names.example.com",
  "trace_id": "1-62be1272-1b71c4274f39f122afa64eab",
  "start_time": 1484786387.131,
  "end_time": 1484786387.501,
  "parent_id": "004f72be19cddc2a",
  "http": {
    "request": {
      "method": "GET",
      "url": "https://names.example.com/"
    },
    "response": {
      "content_length": -1,
      "status": 200
    }
  },
  "inferred": true
}

Verfolgen von SQL-Abfragen mit dem X-Ray SDK für Node.js

Instrumentieren Sie SQL-Datenbankabfragen, indem Sie Ihren SQL-Client in die entsprechende Client-Methode des X-Ray SDK for Node.js einbinden.

  • PostgreSQL – AWSXRay.capturePostgres() 

    var AWSXRay = require('aws-xray-sdk');
var pg = AWSXRay.capturePostgres(require('pg'));
var client = new pg.Client();

  • MySQL – AWSXRay.captureMySQL() 

    var AWSXRay = require('aws-xray-sdk');
var mysql = AWSXRay.captureMySQL(require('mysql'));
...
var connection = mysql.createConnection(config);

Wenn Sie mit einem instrumentierten Client SQL-Abfragen vornehmen, zeichnet das X-Ray SDK for Node.js in einem Untersegment Informationen über die Verbindung und die Abfrage auf.

Zusätzliche Daten in SQL-Untersegmenten einbeziehen

Sie können Untersegmenten, die für SQL-Abfragen generiert wurden, zusätzliche Informationen hinzufügen, sofern diese einem SQL-Feld auf der Zulassungsliste zugeordnet sind. Um beispielsweise die bereinigte SQL-Abfragezeichenfolge in einem Untersegment aufzuzeichnen, können Sie sie direkt zum SQL-Objekt des Untersegments hinzufügen.

Beispiel Weisen Sie SQL einem Untersegment zu
    const queryString = 'SELECT * FROM MyTable';
connection.query(queryString, ...);

// Retrieve the most recently created subsegment
const subs = AWSXRay.getSegment().subsegments;

if (subs & & subs.length > 0) {
  var sqlSub = subs[subs.length - 1];
  sqlSub.sql.sanitized_query = queryString;
}

Eine vollständige Liste der SQL-Felder auf der Zulassungsliste finden Sie unter SQL-Abfragen im AWS X-Ray Entwicklerhandbuch.

Generieren benutzerdefinierter Untersegmente mit dem X-Ray SDK für Node.js

Untersegmente erweitern das Segment eines Traces um Details über die Arbeit, die zur Bearbeitung einer Anfrage geleistet wurde. Jedes Mal, wenn Sie einen Anruf mit einem instrumentierten Client tätigen, zeichnet das X-Ray-SDK die in einem Untersegment generierten Informationen auf. Sie können zusätzliche Untersegmente erstellen, um andere Untersegmente zu gruppieren, die Leistung eines Codeabschnitts zu messen oder Anmerkungen und Metadaten aufzuzeichnen.

Benutzerdefinierte Express-Untersegmente

Um ein benutzerdefiniertes Untersegment für eine Funktion zu erstellen, die Aufrufe des nachgelagerten Service vornimmt, verwenden Sie die captureAsyncFunc-Funktion.

Beispiel app.js – benutzerdefinierte Untersegmente Express
var AWSXRay = require('aws-xray-sdk');

app.use(AWSXRay.express.openSegment('MyApp'));

app.get('/', function (req, res) {
  var host = 'api.example.com';

  AWSXRay.captureAsyncFunc('send', function(subsegment) {
    sendRequest(host, function() {
      console.log('rendering!');
      res.render('index');
      subsegment.close();
    });
  });
});

app.use(AWSXRay.express.closeSegment());

function sendRequest(host, cb) {
  var options = {
    host: host,
    path: '/',
  };

  var callback = function(response) {
    var str = '';

    response.on('data', function (chunk) {
      str += chunk;
    });

    response.on('end', function () {
      cb();
    });
  }

  http.request(options, callback).end();
};

In diesem Beispiel erstellt die Anwendung ein benutzerdefiniertes Untersegment namens send für Aufrufe der sendRequest-Funktion. captureAsyncFunc übergibt ein Untersegment, das Sie innerhalb der Callback-Funktion schließen müssen, wenn die asynchronen Aufrufe der Funktion abgeschlossen sind.

Für synchrone Funktionen können Sie die captureFunc-Funktion verwenden, mit der das Untersegment automatisch geschlossen wird, sobald der Funktionsblock ausgeführt wurde.

Wenn Sie ein Untersegment innerhalb eines Segments oder eines anderen Untersegments erstellen, generiert das X-Ray SDK for Node.js eine ID dafür und zeichnet die Start- und Endzeit auf.

Beispiel Untersegment mit Metadaten
"subsegments": [{
  "id": "6f1605cd8a07cb70",
  "start_time": 1.480305974194E9,
  "end_time": 1.4803059742E9,
  "name": "Custom subsegment for UserModel.saveUser function",
  "metadata": {
    "debug": {
      "test": "Metadata string from UserModel.saveUser"
    }
  },

Benutzerdefinierte Lambda-Untersegmente

Das SDK ist so konfiguriert, dass es automatisch ein Platzhalter-Fassadensegment erstellt, wenn es erkennt, dass es in Lambda ausgeführt wird. Um ein grundlegendes Untersegment zu erstellen, das einen einzelnen AWS::Lambda::Function Knoten auf der X-Ray-Trace-Map erstellt, rufen Sie das Fassadensegment auf und verwenden es für neue Zwecke. Wenn Sie manuell ein neues Segment mit einer neuen ID erstellen (während Sie die Ablaufverfolgung-ID, die übergeordnete ID und die Sampling-Entscheidung teilen), können Sie ein neues Segment senden.

Beispiel app.js – benutzerdefinierte manuelle Untersegmente
const segment = AWSXRay.getSegment(); //returns the facade segment
const subsegment = segment.addNewSubsegment('subseg');
...
subsegment.close();
//the segment is closed by the SDK automatically

Hinzufügen von Anmerkungen und Metadaten zu Segmenten mit dem X-Ray SDK for Node.js

Sie können Anmerkungen und Metadaten verwenden, um zusätzliche Informationen über Anfragen, die Umgebung oder Ihre Anwendung aufzuzeichnen. Sie können Anmerkungen und Metadaten zu den Segmenten hinzufügen, die das X-Ray SDK erstellt, oder zu benutzerdefinierten Untersegmenten, die Sie erstellen.

Anmerkungen sind Schlüssel-Wert-Paare mit Zeichenfolgen-, Zahlen- oder booleschen Werten. Anmerkungen sind für die Verwendung mit Filterausdrücken indexiert. Berücksichtigen Sie Anmerkungen, um Daten zur Gruppierung von Ablaufverfolgungen in der Konsole zu verwenden, oder wenn Sie die GetTraceSummaries-API aufrufen.

Metadaten sind Schlüssel-Wert-Paare, die Werte beliebigen Typs enthalten können, einschließlich Objekte und Listen, aber nicht für die Verwendung mit Filterausdrücken indexiert sind. Verwenden Sie Metadaten, um zusätzliche Daten aufzuzeichnen, die Sie im Trace speichern möchten, aber nicht für die Suche verwenden müssen.

Zusätzlich zu Anmerkungen und Metadaten können Sie auch Benutzer-ID-Zeichenfolgen in Segmenten aufzeichnen. Benutzer-IDs werden in einem eigenen Feld aufgezeichnet und zur Suche indiziert.

Anmerkungen mit dem X-Ray SDK für Node.js aufnehmen

Verwenden Sie Anmerkungen, um Informationen zu Segmenten oder Untersegmenten, die zur Suche indiziert werden sollten, aufzuzeichnen.

Anmerkung zu Anforderungen

  • Schlüssel — Der Schlüssel für eine X-Ray-Anmerkung kann bis zu 500 alphanumerische Zeichen enthalten. Sie können keine anderen Leerzeichen oder Symbole als den Unterstrich (_) verwenden.

  • Werte — Der Wert für eine X-Ray-Anmerkung kann bis zu 1.000 Unicode-Zeichen enthalten.

  • Die Anzahl der Anmerkungen — Sie können bis zu 50 Anmerkungen pro Spur verwenden.

So zeichnen Sie Anmerkungen auf

  1. Erhalten Sie eine Referenz zum aktuellen Segment oder Untersegment.

    var AWSXRay = require('aws-xray-sdk');
...
var document = AWSXRay.getSegment();

  2. Rufen Sie addAnnotation mit einem Aktivierungsschlüssel und einem booleschen Wert oder einem Zeichenfolgenwert auf.

    document.addAnnotation("mykey", "my value");

Das SDK zeichnet Anmerkungen als Schlüssel-Wert-Paare in einem annotations-Objekt im Segmentdokument auf. Wenn addAnnotation zweimal mit demselben Schlüssel aufgerufen wird, werden zuvor aufgezeichnete Werte im gleichen Segment oder Untersegment überschrieben.

Nutzen Sie das annotations.key-Schlüsselwort in einem Filterausdruck, um Ablaufverfolgungen durch Anmerkungen mit bestimmten Werten zu finden.

Beispiel app.js – Anmerkungen
var AWS = require('aws-sdk');
var AWSXRay = require('aws-xray-sdk');
var ddb = AWSXRay.captureAWSClient(new AWS.DynamoDB());
...
app.post('/signup', function(req, res) {
    var item = {
        'email': {'S': req.body.email},
        'name': {'S': req.body.name},
        'preview': {'S': req.body.previewAccess},
        'theme': {'S': req.body.theme}
    };

    var seg = AWSXRay.getSegment();
    seg.addAnnotation('theme', req.body.theme);
  
    ddb.putItem({
      'TableName': ddbTable,
      'Item': item,
      'Expected': { email: { Exists: false } }
  }, function(err, data) {
...

Aufzeichnen von Metadaten mit dem X-Ray SDK für Node.js

Verwenden Sie Metadaten, um Segment- oder Untersegmentinformationen aufzuzeichnen, die nicht zur Suche indiziert werden müssen. Metadatenwerte sind Zeichenfolgen, Zahlen, boolesche Werte oder andere Objekte, die in Form eines JSON-Objekts oder eines Arrays angeordnet sein können.

So zeichnen Sie Metadaten auf

  1. Erhalten Sie eine Referenz zum aktuellen Segment oder Untersegment.

    var AWSXRay = require('aws-xray-sdk');
...
var document = AWSXRay.getSegment();

  2. Rufen Sie addMetadata mit einem Zeichenfolgenschlüssel, einem booleschen Wert, einer Zeichenfolge oder einem Objektwert und einem Zeichenfolgen-Namespace auf.

    document.addMetadata("my key", "my value", "my namespace");

    or

    Rufen Sie addMetadata nur mit einem Aktivierungsschlüssel und einem Wert auf.

    document.addMetadata("my key", "my value");

Wenn Sie keinen Namespace angeben, verwendet SDK default. Wenn addMetadata zweimal mit demselben Schlüssel aufgerufen wird, werden zuvor aufgezeichnete Werte im gleichen Segment oder Untersegment überschrieben.

Aufzeichnen von Benutzer-IDs mit dem X-Ray SDK für Node.js

Zeichnen Sie Benutzer-IDs in Anforderungssegmenten auf, um den Benutzer zu identifizieren, der die Anforderung gesendet hat. Dieser Vorgang ist nicht mit AWS Lambda Funktionen kompatibel, da Segmente in Lambda-Umgebungen unveränderlich sind. Der setUser-Aufruf kann nur auf Segmente angewendet werden, nicht auf Untersegmente.

So zeichnen Sie Benutzer-IDs auf

  1. Erhalten Sie eine Referenz zum aktuellen Segment oder Untersegment.

    var AWSXRay = require('aws-xray-sdk');
...
var document = AWSXRay.getSegment();

  2. Rufen Sie setUser() mit einer Zeichenfolgen-ID des Benutzers auf, der die Anforderung gesendet hat.

    var user = 'john123';

AWSXRay.getSegment().setUser(user);

Sie können setUser aufrufen, um die Benutzer-ID aufzuzeichnen, sobald die Express-Anwendung mit der Verarbeitung einer Anfrage beginnt. Wenn Sie das Segment nur zur Einrichtung der Benutzer-ID verwenden, können Sie die Aufrufe in einer einzelnen Zeile anordnen.

Beispiel app.js – Benutzer-ID
var AWS = require('aws-sdk');
var AWSXRay = require('aws-xray-sdk');
var uuidv4 = require('uuid/v4');
var ddb = AWSXRay.captureAWSClient(new AWS.DynamoDB());
...
    app.post('/signup', function(req, res) {
    var userId = uuidv4();
    var item = {
        'userId': {'S': userId},
        'email': {'S': req.body.email},
        'name': {'S': req.body.name}
    };

    var seg = AWSXRay.getSegment().setUser(userId);
  
    ddb.putItem({
      'TableName': ddbTable,
      'Item': item,
      'Expected': { email: { Exists: false } }
  }, function(err, data) {
...

Nutzen Sie das user-Schlüsselwort in einem Filterausdruck, um Ablaufverfolgungen einer Benutzer-ID zu finden.