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
**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).
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, das für Node.js Versionen 14.x und höher unterstützt wird. Du kannst das Projekt verfolgen und Issues und Pull-Requests einreichen auf GitHub: [github. com/aws/aws](https://github.com/aws/aws-xray-sdk-node)- xray-sdk-node
Wenn Sie Express nutzen, beginnen Sie, indem Sie [das SDK als Middleware](xray-sdk-nodejs-middleware.md) auf Ihrem Anwendungsserver hinzufügen, um eingehende Anforderungen zu verfolgen. Der Middleware erstellt für jede verfolgte Anforderung ein [Segment](xray-concepts.md#xray-concepts-segments) 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](xray-concepts.md#xray-concepts-tracingheader). Für andere Funktionen können Sie [Lambda so konfigurieren](xray-services-lambda.md), 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](xray-services-lambda.md).
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](xray-sdk-nodejs-awssdkclients.md). 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](xray-sdk-nodejs-httpclients.md), um Informationen zu ausgehenden HTTP-Anforderungen aufzuzeichnen. Für SQL-Clients [verwenden Sie die Capture-Methode für Ihre Datenbank](xray-sdk-nodejs-sqlclients.md).
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](xray-sdk-nodejs-configuration.md), 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](xray-sdk-nodejs-segment.md) auf. Anmerkungen sind einfache Schlüsselwertpaare, die für die Verwendung mit [Filterausdrücken](xray-console-filters.md) 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 Segmenten mit dem X-Ray SDK 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](xray-sdk-nodejs-subsegments.md) 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](https://docs.aws.amazon.com//xray-sdk-for-nodejs/latest/reference).
## 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.
+ **Package** — [https://www.npmjs.com/package/aws-xray-sdk](https://www.npmjs.com/package/aws-xray-sdk)
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](http://npm.github.io/how-npm-works-docs/npm3/how-npm3-works.html).
## 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 durch Ihre Node.js -Anwendungen übertragen werden.
+ [Node.js Beispielanwendung](https://github.com/aws-samples/aws-xray-sdk-node-sample) aktiviert GitHub.
# 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.
# Nachverfolgung eingehender Anfragen mit dem 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 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](xray-services-lambda.md).
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 ist`true`, 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.
**Topics**
+ [Nachverfolgung eingehender Anforderungen mit Express](#xray-sdk-nodejs-middleware-express)
+ [Nachverfolgung eingehender Anforderungen mit Restify](#xray-sdk-nodejs-middleware-restify)
+ [Konfiguration einer Segmentbenennungsstrategie](#xray-sdk-nodejs-middleware-naming)
## 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.
**Example 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.
**Example 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 AWS Ressourcen und Ressourcen zu unterscheiden APIs, 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](xray-api-segmentdocuments.md#api-segmentdocuments-fields).
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önnen Sie über eine einzige Anwendung verfügen, die Anfragen an drei Subdomänen — `www.example.com``api.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](xray-sdk-nodejs-configuration.md#xray-sdk-nodejs-configuration-envvars) 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`.
**Example 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 AWS SDK-Aufrufen mit dem 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).
Wenn Ihre Anwendung Aufrufe tätigt, um Daten AWS-Services zu speichern, in eine Warteschlange zu schreiben oder Benachrichtigungen zu senden, verfolgt das X-Ray SDK for Node.js die Aufrufe im Downstream in [Untersegmenten](xray-sdk-nodejs-subsegments.md). Traced und Ressourcen AWS-Services, auf die Sie innerhalb dieser Services zugreifen (z. B. ein Amazon S3-Bucket oder eine Amazon SQS SQS-Warteschlange), werden als Downstream-Knoten auf der Trace-Map in der X-Ray-Konsole angezeigt.
AWS [Instrumenten-SDK-Clients, die Sie über [AWS SDK für JavaScript V2 oder AWS SDK für JavaScript V3](https://docs.aws.amazon.com/sdk-for-javascript/v2/developer-guide/welcome.html) erstellen.](https://docs.aws.amazon.com/sdk-for-javascript/v3/developer-guide/welcome.html) Jede AWS SDK-Version bietet unterschiedliche Methoden zur Instrumentierung von AWS SDK-Clients.
**Anmerkung**
Derzeit gibt das AWS X-Ray SDK für Node.js bei der Instrumentierung von AWS SDK für JavaScript V3-Clients weniger Segmentinformationen zurück als bei der Instrumentierung von V2-Clients. Beispielsweise geben Untersegmente, die Aufrufe von DynamoDB darstellen, den Tabellennamen nicht zurück. Wenn Sie diese Segmentinformationen in Ihren Traces benötigen, sollten Sie die Verwendung von V2 in Betracht ziehen. AWS SDK für JavaScript
------
#### [ AWS SDK für JavaScript V2 ]
Sie können alle AWS SDK V2-Clients instrumentieren, indem Sie Ihre `aws-sdk` require-Anweisung in einen Call to einbinden`AWSXRay.captureAWS`.
**Example app.js — AWS SDK-Instrumentierung**
```
const AWS = AWSXRay.captureAWS(require('aws-sdk'));
```
Um einzelne Clients zu instrumentieren, binden Sie Ihren AWS SDK-Client in einen Aufruf von ein`AWSXRay.captureAWSClient`. Instrumentieren Sie beispielsweise einen `AmazonDynamoDB`-Client wie folgt:
**Example 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](https://www.typescriptlang.org/docs/handbook/typescript-in-5-minutes.html)mit [ECMAScriptModulen](https://nodejs.org/api/esm.html) (ESM) Ihren JavaScript Code laden möchten, verwenden Sie das folgende Beispiel, um Bibliotheken zu importieren:
**Example 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:
**Example 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 Dienste können Sie den Namen der aufgerufenen API in der X-Ray-Konsole sehen. Für eine Untergruppe von Diensten fügt das X-Ray SDK dem Segment Informationen hinzu, um die Service Map detaillierter zu gestalten.
Wenn Sie beispielsweise einen Aufruf mit einem instrumentierten DynamoDB-Client tätigen, fügt das SDK den Tabellennamen dem Segment für Aufrufe hinzu, die auf eine Tabelle abzielen. In der Konsole wird jede Tabelle als separater Knoten in der Service Map angezeigt, mit einem generischen DynamoDB-Knoten für Aufrufe, die nicht auf eine Tabelle abzielen.
**Example Untersegment für einen Aufruf von 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 für JavaScript V3 ]
Die AWS SDK für JavaScript Version 3 ist modular aufgebaut, sodass Ihr Code nur die Module lädt, die er benötigt. 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) Ihren JavaScript Code laden möchten, 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.captureAWSv3Client` Methode. Instrumentieren Sie beispielsweise einen `AmazonDynamoDB`-Client wie folgt:
**Example 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 für JavaScript V3 werden Metadaten wie Tabellenname, Bucket- und Schlüsselname oder Warteschlangenname derzeit nicht zurückgegeben. Daher enthält die Trace-Map keine separaten Knoten für jede benannte Ressource, wie dies bei der Instrumentierung von AWS SDK-Clients mit V2 der Fall wäre. AWS SDK für JavaScript
**Example Untersegment für einen Aufruf von DynamoDB zum Speichern eines Elements bei Verwendung von V3 AWS SDK für JavaScript**
```
{
"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",
}
}
```
------
# Verfolgen von Aufrufen an Downstream-HTTP-Webservices mithilfe 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).
Wenn Ihre Anwendung Microservices oder öffentliches HTTP aufruft APIs, 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](https://docs.aws.amazon.com/xray-sdk-for-nodejs/latest/reference/module-http_p.html) unterstützt und werden weiterhin nachverfolgt, wenn sie das `http`-Modul verwenden.
**Example 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.
**Example 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.
**Example 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
}
}
}
```
**Example 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
**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).
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.
**Example 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](https://docs.aws.amazon.com/xray/latest/devguide/xray-api-segmentdocuments.html#api-segmentdocuments-sql).*
# Generieren benutzerdefinierter Untersegmente mit dem X-Ray SDK für Node.js
Untersegmente erweitern das [Segment](xray-concepts.md#xray-concepts-segments) 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
**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).
Um ein benutzerdefiniertes Untersegment für eine Funktion zu erstellen, die Aufrufe des nachgelagerten Service vornimmt, verwenden Sie die `captureAsyncFunc`-Funktion.
**Example 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.
**Example 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.
**Example 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
**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 zusätzliche Informationen über Anfragen, die Umgebung oder Ihre Anwendung mit Anmerkungen und Metadaten aufzeichnen. 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.](xray-console-filters.md) Berücksichtigen Sie Anmerkungen, um Daten zur Gruppierung von Ablaufverfolgungen in der Konsole zu verwenden, oder wenn Sie die [https://docs.aws.amazon.com/xray/latest/api/API_GetTraceSummaries.html](https://docs.aws.amazon.com/xray/latest/api/API_GetTraceSummaries.html)-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](#xray-sdk-nodejs-segment-userid) in Segmenten aufzeichnen. Benutzer IDs werden in einem separaten Feld in Segmenten aufgezeichnet und für die Verwendung bei der Suche indexiert.
**Topics**
+ [Anmerkungen mit dem X-Ray SDK für Node.js aufnehmen](#xray-sdk-nodejs-segment-annotations)
+ [Metadaten mit dem X-Ray SDK für Node.js aufzeichnen](#xray-sdk-nodejs-segment-metadata)
+ [Benutzer IDs mit dem X-Ray SDK für Node.js aufzeichnen](#xray-sdk-nodejs-segment-userid)
## 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 einen Punkt oder Punkt (.) 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();
```
1. Rufen Sie `addAnnotation` mit einem Aktivierungsschlüssel und einem booleschen Wert oder einem Zeichenfolgenwert auf.
```
document.addAnnotation("mykey", "my value");
```
Das folgende Beispiel zeigt, wie Sie `putAnnotation` mit einem String-Schlüssel aufrufen, der einen Punkt und einen booleschen Wert, eine Zahl oder einen String-Wert enthält.
```
document.putAnnotation("testkey.test", "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 `annotation[key]`-Schlüsselwort in einem [Filterausdruck](xray-console-filters.md), um Ablaufverfolgungen durch Anmerkungen mit bestimmten Werten zu finden.
**Example 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) {
...
```
## Metadaten mit dem X-Ray SDK für Node.js aufzeichnen
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();
```
1. 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");
```
oder
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.
## Benutzer IDs mit dem X-Ray SDK für Node.js aufzeichnen
Zeichnen Sie Segmente des Benutzers IDs auf Anfrage auf, um den Benutzer zu identifizieren, der die Anfrage 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.
**Um einen Benutzer aufzuzeichnen IDs**
1. Erhalten Sie eine Referenz zum aktuellen Segment oder Untersegment.
```
var AWSXRay = require('aws-xray-sdk');
...
var document = AWSXRay.getSegment();
```
1. 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.
**Example 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](https://docs.aws.amazon.com/xray/latest/devguide/xray-console-filters.html), um Ablaufverfolgungen einer Benutzer-ID zu finden.