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. # Konfiguration des X-Ray-SDK für Node.js **Anmerkung** SDK/Daemon X-Ray-Wartungshinweis — Am 25. Februar 2026 wechselt das AWS X-Ray SDKs/Daemon in den Wartungsmodus, in dem die Versionen von X-Ray SDK und Daemon auf Sicherheitsprobleme beschränkt AWS werden. Weitere Informationen zum Zeitplan für den Support finden Sie unter. [Zeitplan für die Support von X-Ray SDK und Daemon](xray-sdk-daemon-timeline.md) Wir empfehlen die Migration zu OpenTelemetry. Weitere Informationen zur Migration zu OpenTelemetry finden Sie unter [Migration von X-Ray-Instrumentierung zu OpenTelemetry Instrumentierung](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html). 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. **Topics** + [Service-Plugins](#xray-sdk-nodejs-configuration-plugins) + [Regeln für die Probenahme](#xray-sdk-nodejs-configuration-sampling) + [Protokollierung](#xray-sdk-nodejs-configuration-logging) + [Adresse des X-Ray-Daemons](#xray-sdk-nodejs-configuration-daemon) + [Umgebungsvariablen](#xray-sdk-nodejs-configuration-envvars) ## Service-Plugins Wird verwendet`plugins`, um Informationen über den Dienst aufzuzeichnen, der Ihre Anwendung hostet. **Plugins** + 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. **Example 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. ## Regeln für die Probenahme 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](xray-console-sampling.md), 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 APIs, Sampling 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. **Example 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 laden`setSamplingRules`. **Example 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. **Example 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`, `info`usw.) 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](#xray-sdk-nodejs-configuration-envvars). 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. **Example 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 als`127.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 anhand des Namens oder der Adresse angeben. IPv4 **Example 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. **Example 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](#xray-sdk-nodejs-configuration-envvars) 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`— 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](xray-daemon-configuration.md) 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 ein`TRUE`, 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 er auf gesetzt AWS\$1XRAY\$1DEBUG\$1MODE ist`TRUE`. + `AWS_XRAY_TRACING_NAME`— Legen Sie einen Dienstnamen fest, den das SDK für Segmente verwendet. Überschreibt den [für die Express-Middleware festgelegten](xray-sdk-nodejs-middleware.md) Segmentnamen.