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 for Java **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 for Java besteht aus einer Reihe von Bibliotheken für Java-Webanwendungen, die Klassen und Methoden zum Generieren und Senden von Trace-Daten an den X-Ray-Daemon bereitstellen. 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, HTTP-Clients oder eines SQL-Datenbank-Connectors an Downstream-Dienste sendet. Sie können Segmente auch manuell erstellen und Debug-Informationen Anmerkungen und Metadaten hinzufügen. Das X-Ray SDK for Java ist ein Open-Source-Projekt. Du kannst das Projekt verfolgen und Issues und Pull-Requests einreichen auf GitHub: [github. com/aws/aws](https://github.com/aws/aws-xray-sdk-java)- xray-sdk-java Fügen Sie zunächst [`AWSXRayServletFilter` als Servlet-Filter](xray-sdk-java-filters.md) hinzu, um eingehende Anforderungen zu verfolgen. Ein Servlet-Filter erstellt ein [Segment](xray-concepts.md#xray-concepts-segments). 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. Ab Version 1.3 können Sie Ihre Anwendung mit [aspekt-orientierter Programmierung (AOP) in Spring](xray-sdk-java-aop-spring.md) instrumentieren. Das bedeutet, dass Sie Ihre Anwendung instrumentieren können, während sie läuft AWS, ohne der Laufzeit Ihrer Anwendung Code hinzufügen zu müssen. Verwenden Sie als Nächstes das X-Ray-SDK SDK for Java, um Ihre AWS SDK für Java Clients zu instrumentieren, indem [Sie das SDK Instrumentor-Untermodul](#xray-sdk-java-dependencies) in Ihre Build-Konfiguration aufnehmen. Immer wenn Sie mit einem instrumentierten Client einen Downstream AWS-Service oder eine Ressource 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. Wenn Sie nicht alle Downstream-Aufrufe instrumentieren möchten AWS-Services, können Sie das Instrumentor-Untermodul weglassen und auswählen, welche Clients instrumentiert werden sollen. Instrumentieren Sie einzelne Clients, [indem Sie einem `TracingHandler`](xray-sdk-java-awssdkclients.md) AWS SDK-Serviceclient einen hinzufügen. Andere Submodule des X-Ray SDK for Java bieten Instrumentierung für Downstream-Aufrufe von HTTP-Web APIs - und SQL-Datenbanken. Sie können [das X-Ray-SDK SDK for Java Java-Versionen von `HTTPClient` und `HTTPClientBuilder` im Apache HTTP-Submodul verwenden](xray-sdk-java-httpclients.md), um Apache HTTP-Clients zu instrumentieren. Um SQL-Anfragen zu instrumentieren, [fügen Sie der Datenquelle den SDK-Interceptor hinzu](xray-sdk-java-sqlclients.md). Nachdem Sie das SDK verwendet haben, passen Sie sein Verhalten an, indem Sie [den Rekorder und den Servlet-Filter konfigurieren](xray-sdk-java-configuration.md). Sie können Plugins zum Festhalten von Daten über die Datenverarbeitungsressourcen, auf denen Ihre Anwendung ausgeführt wird, hinzufügen, das Samplingverhalten durch Samplingregeln anpassen und Protokollebenen einrichten, um mehr oder weniger Informationen von dem SDK in Ihren Anwendungsprotokollen zu sehen. Zeichnen Sie zusätzliche Informationen zu Anforderungen und den Aufgaben, die Ihre Anwendung ausführt, in [Anmerkungen und Metadaten](xray-sdk-java-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 instrumentierte Clients in Ihrem Code haben, kann ein einzelnes Anfragesegment 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-java-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. ## Untermodule Sie können das X-Ray SDK for Java von Maven herunterladen. Das X-Ray-SDK SDK for Java ist je nach Anwendungsfall in Untermodule aufgeteilt und enthält eine Materialliste für die Versionsverwaltung: + [https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-core/](https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-core/)(erforderlich) — Grundlegende Funktionen für die Erstellung von Segmenten und die Übertragung von Segmenten. Umfasst `AWSXRayServletFilter` für die Instrumentierung eingehender Anforderungen. + [https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-aws-sdk/](https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-aws-sdk/)— Instrumentiert Aufrufe, die mit AWS SDK für Java Clients AWS-Services getätigt wurden, indem ein Tracing-Client als Request-Handler hinzugefügt wird. + [https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-aws-sdk-v2/](https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-aws-sdk-v2/)— Instrumentiert Aufrufe, die mit Clients der Version AWS SDK für Java 2.2 und höher AWS-Services getätigt wurden, indem ein Tracing-Client als Request-Interzeptor hinzugefügt wird. + [https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-aws-sdk-instrumentor/](https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-aws-sdk-instrumentor/)— Instrumentiert alle `aws-xray-recorder-sdk-aws-sdk` Clients automatisch. AWS SDK für Java + [https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-aws-sdk-v2-instrumentor/](https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-aws-sdk-v2-instrumentor/)— `aws-xray-recorder-sdk-aws-sdk-v2` Instrumentiert alle Clients ab Version AWS SDK für Java 2.2 automatisch. + [https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-apache-http/](https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-apache-http/)— Instrumentiert ausgehende HTTP-Aufrufe, die mit Apache HTTP-Clients getätigt wurden. + [https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-spring/](https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-spring/)— Stellt Interzeptoren für Spring AOP Framework-Anwendungen bereit. + [https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-sql-postgres/](https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-sql-postgres/)— Instrumentiert ausgehende Aufrufe an eine PostgreSQL-Datenbank, die mit JDBC getätigt wurden. + [https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-sql-mysql/](https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-sql-mysql/)— Instrumentiert ausgehende Aufrufe an eine MySQL-Datenbank, die mit JDBC getätigt wurden. + [https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-bom/](https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-bom/)— Stellt eine Stückliste bereit, anhand derer Sie die Version angeben können, die für alle Submodule verwendet werden soll. + [https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-metrics/](https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-metrics/)— Veröffentlichen Sie CloudWatch Amazon-Metriken ohne Stichproben aus Ihren gesammelten X-Ray-Segmenten. Wenn Sie Maven oder Gradle verwenden, um Ihre Anwendung zu erstellen, [fügen Sie das X-Ray SDK for Java zu Ihrer Build-Konfiguration](#xray-sdk-java-dependencies) hinzu. Eine Referenzdokumentation der Klassen und Methoden des SDK finden Sie unter [AWS X-Ray SDK for Java API Reference](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc). ## Voraussetzungen Das X-Ray SDK for Java erfordert Java 8 oder höher, Servlet API 3, das AWS SDK und Jackson. Das SDK hängt von den folgenden Bibliotheken zur Kompilierungs- und Laufzeit ab: + AWS SDK for Java Version 1.11.398 oder höher + Servlet API 3.1.0 Diese Abhängigkeiten werden in der `pom.xml`-Datei des SDK deklariert und automatisch eingefügt, wenn Sie Maven oder Gradle für die Build-Erstellung verwenden. Wenn Sie eine Bibliothek verwenden, die im X-Ray SDK for Java enthalten ist, müssen Sie die mitgelieferte Version verwenden. Wenn Sie beispielsweise bereits zur Laufzeit von Jackson abhängen und für diese Abhängigkeit JAR-Dateien in Ihre Bereitstellung aufnehmen, müssen Sie diese JAR-Dateien entfernen, da das SDK JAR eigene Versionen von Jackson-Bibliotheken umfasst. ## Abhängigkeitsmanagement Das X-Ray SDK for Java ist bei Maven erhältlich: + **Gruppe** — `com.amazonaws` + **Artifact** — `aws-xray-recorder-sdk-bom` + **Version** – `2.11.0` Wenn Sie Ihre Anwendung mit Maven erstellen, fügen Sie das SDK als Abhängigkeit in Ihrer `pom.xml`-Datei hinzu. **Example pom.xml - Abhängigkeiten** ``` com.amazonaws aws-xray-recorder-sdk-bom 2.11.0 pom import com.amazonaws aws-xray-recorder-sdk-core com.amazonaws aws-xray-recorder-sdk-apache-http com.amazonaws aws-xray-recorder-sdk-aws-sdk com.amazonaws aws-xray-recorder-sdk-aws-sdk-instrumentor com.amazonaws aws-xray-recorder-sdk-sql-postgres com.amazonaws aws-xray-recorder-sdk-sql-mysql ``` Für Gradle fügen Sie das SDK als Kompilierungszeitabhängigkeit in Ihrer `build.gradle`-Datei hinzu. **Example build.gradle – Abhängigkeiten** ``` dependencies { compile("org.springframework.boot:spring-boot-starter-web") testCompile("org.springframework.boot:spring-boot-starter-test") compile("com.amazonaws:aws-java-sdk-dynamodb") compile("com.amazonaws:aws-xray-recorder-sdk-core") compile("com.amazonaws:aws-xray-recorder-sdk-aws-sdk") compile("com.amazonaws:aws-xray-recorder-sdk-aws-sdk-instrumentor") compile("com.amazonaws:aws-xray-recorder-sdk-apache-http") compile("com.amazonaws:aws-xray-recorder-sdk-sql-postgres") compile("com.amazonaws:aws-xray-recorder-sdk-sql-mysql") testCompile("junit:junit:4.11") } dependencyManagement { imports { mavenBom('com.amazonaws:aws-java-sdk-bom:1.11.39') mavenBom('com.amazonaws:aws-xray-recorder-sdk-bom:2.11.0') } } ``` Wenn Sie Elastic Beanstalk für die Bereitstellung Ihrer Anwendung verwenden, können Sie Maven oder Gradle verwenden, um bei jeder Bereitstellung eine On-Instance zu erstellen, anstatt ein großes Archiv mit all Ihren Abhängigkeiten zu erstellen und hochzuladen. Für ein Beispiel, bei dem Gradle verwendet wird, sehen Sie sich die [Beispielanwendung](xray-scorekeep.md) an. # AWS X-Ray Agent für automatische Instrumentierung für Java **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). Der AWS X-Ray Autoinstrumentation-Agent für Java ist eine Tracing-Lösung, die Ihre Java-Webanwendungen mit minimalem Entwicklungsaufwand instrumentiert. Der Agent ermöglicht die Ablaufverfolgung für Servlet-basierte Anwendungen und alle Downstream-Anfragen des Agenten, die mit unterstützten Frameworks und Bibliotheken gestellt wurden. Dazu gehören Downstream-HTTP-Anfragen von Apache, AWS SDK-Anfragen und SQL-Abfragen, die mit einem JDBC-Treiber gestellt wurden. Der Agent verbreitet den X-Ray-Kontext, einschließlich aller aktiven Segmente und Untersegmente, über Threads hinweg. Alle Konfigurationen und die Vielseitigkeit des X-Ray-SDK sind weiterhin mit dem Java-Agenten verfügbar. Es wurden geeignete Standardeinstellungen ausgewählt, um sicherzustellen, dass der Agent mit minimalem Aufwand arbeitet. Die X-Ray-Agentenlösung eignet sich am besten für Servlet-basierte Java-Webanwendungsserver mit Request-Response. Wenn Ihre Anwendung ein asynchrones Framework verwendet oder nicht gut als Request-Response-Service modelliert ist, sollten Sie stattdessen eine manuelle Instrumentierung mit dem SDK in Betracht ziehen.  Der X-Ray-Agent wird mit dem Distributed Systems Comprehension Toolkit (Di) erstellt. SCo Di SCo ist ein Open-Source-Framework zum Erstellen von Java-Agenten, die in verteilten Systemen verwendet werden können. Es ist zwar nicht notwendig, Di zu verstehen, SCo um den X-Ray-Agenten verwenden zu können, aber Sie können mehr über das Projekt erfahren, indem Sie die [Homepage unter](https://github.com/awslabs/disco) besuchen GitHub. Der X-Ray-Agent ist ebenfalls vollständig als Open Source verfügbar. Um den Quellcode einzusehen, Beiträge zu leisten oder Probleme mit dem Agenten zu äußern, besuchen Sie das entsprechende [Repository unter GitHub](https://github.com/aws/aws-xray-java-agent). ## Beispielanwendung Die [eb-java-scorekeep](https://github.com/aws-samples/eb-java-scorekeep/tree/xray-agent)Probenapplikation ist so angepasst, dass sie mit dem Röntgenmittel instrumentiert werden kann. Dieser Zweig enthält keine Servlet-Filter- oder Rekorderkonfiguration, da diese Funktionen vom Agenten ausgeführt werden. Um die Anwendung lokal oder mithilfe von AWS Ressourcen auszuführen, folgen Sie den Schritten in der Readme-Datei der Beispielanwendung. Die Anweisungen zur Verwendung der Beispiel-App zum Generieren von Röntgenspuren finden Sie im [Tutorial der Beispiel-App](xray-scorekeep.md). ## Erste Schritte Gehen Sie wie folgt vor, um mit dem X-Ray-Java-Agenten für automatische Instrumentierung in Ihrer eigenen Anwendung zu beginnen. 1. Führen Sie den X-Ray-Daemon in Ihrer Umgebung aus. Weitere Informationen finden Sie unter [AWS X-Ray Dämon](xray-daemon.md). 1. Laden Sie die [neueste Version des Agenten](https://github.com/aws/aws-xray-java-agent/releases/latest/download/xray-agent.zip) herunter. Entpacken Sie das Archiv und notieren Sie sich seinen Speicherort in Ihrem Dateisystem. Sein Inhalt sollte wie folgt aussehen. ``` disco ├── disco-java-agent.jar └── disco-plugins     ├── aws-xray-agent-plugin.jar     ├── disco-java-agent-aws-plugin.jar     ├── disco-java-agent-sql-plugin.jar     └── disco-java-agent-web-plugin.jar ``` 1. Ändern Sie die JVM-Argumente Ihrer Anwendung so, dass sie Folgendes enthalten, wodurch der Agent aktiviert wird. Stellen Sie sicher, dass das `-javaagent` Argument *vor dem* `-jar` Argument steht, falls zutreffend. Der Prozess zum Ändern von JVM-Argumenten hängt von den Tools und Frameworks ab, die Sie zum Starten Ihres Java-Servers verwenden. Spezifische Anleitungen finden Sie in der Dokumentation Ihres Server-Frameworks. ``` -javaagent://disco-java-agent.jar=pluginPath=//disco-plugins ``` 1. Um festzulegen, wie der Name Ihrer Anwendung auf der X-Ray-Konsole angezeigt wird, legen Sie die `AWS_XRAY_TRACING_NAME` Umgebungsvariable oder die `com.amazonaws.xray.strategy.tracingName` Systemeigenschaft fest. Wenn kein Name angegeben wird, wird ein Standardname verwendet. 1. Starten Sie Ihren Server oder Container neu. Eingehende Anfragen und ihre Downstream-Aufrufe werden jetzt verfolgt. Wenn Sie nicht die erwarteten Ergebnisse sehen, finden Sie weitere Informationen unter[Fehlerbehebung](#XRayAutoInstrumentationAgent-Troubleshooting). ## Konfiguration Der X-Ray-Agent wird durch eine externe, vom Benutzer bereitgestellte JSON-Datei konfiguriert. Standardmäßig wird diese Datei im Stammverzeichnis des Klassenpfads des Benutzers (z. B. in seinem `resources` Verzeichnis) benannt. `xray-agent.json` Sie können einen benutzerdefinierten Speicherort für die Konfigurationsdatei konfigurieren, indem Sie die `com.amazonaws.xray.configFile` Systemeigenschaft auf den absoluten Dateisystempfad Ihrer Konfigurationsdatei setzen. Als Nächstes wird ein Beispiel für eine Konfigurationsdatei angezeigt. ``` {         "serviceName": "XRayInstrumentedService",     "contextMissingStrategy": "LOG_ERROR",     "daemonAddress": "127.0.0.1:2000",     "tracingEnabled": true,     "samplingStrategy": "CENTRAL",         "traceIdInjectionPrefix": "prefix",         "samplingRulesManifest": "/path/to/manifest",         "awsServiceHandlerManifest": "/path/to/manifest",         "awsSdkVersion": 2,         "maxStackTraceLength": 50,         "streamingThreshold": 100,         "traceIdInjection": true,         "pluginsEnabled": true,         "collectSqlQueries": false } ``` ### Konfigurationsspezifikation In der folgenden Tabelle werden gültige Werte für jede Eigenschaft beschrieben. Bei Eigenschaftsnamen wird zwischen Groß- und Kleinschreibung unterschieden, bei ihren Schlüsseln jedoch nicht. Bei Eigenschaften, die durch Umgebungsvariablen und Systemeigenschaften außer Kraft gesetzt werden können, ist die Prioritätsreihenfolge immer die Umgebungsvariable, dann die Systemeigenschaft und dann die Konfigurationsdatei. Hinweise zu Eigenschaften, die Sie überschreiben können, finden Sie unter. [Umgebungsvariablen](xray-sdk-java-configuration.md#xray-sdk-java-configuration-envvars) Alle Felder sind optional. | Name der Eigenschaft | Typ | Zulässige Werte | Description | Umgebungsvariable | Systemeigenschaft | Standard | | --- | --- | --- | --- | --- | --- | --- | | serviceName | Zeichenfolge | Jede Zeichenfolge | Der Name Ihres instrumentierten Dienstes, so wie er in der X-Ray-Konsole angezeigt wird. | AWS\$1XRAY\$1TRACING\$1NAME | com.amazonaws.xray.strategy.tracingName | XRayInstrumentedService | | contextMissingStrategy | Zeichenfolge | LOG\$1ERROR, IGNORE\$1ERROR | Die Aktion, die der Agent ausführt, wenn er versucht, den X-Ray-Segmentkontext zu verwenden, aber keiner vorhanden ist. | AWS\$1XRAY\$1CONTEXT\$1MISSING | com.amazonaws.xray.strategy. contextMissingStrategy | LOG\$1ERROR | | Daemon-Adresse | Zeichenfolge | Formatierte IP-Adresse und Port oder Liste von TCP- und UDP-Adressen | Die Adresse, die der Agent für die Kommunikation mit dem X-Ray-Daemon verwendet. | AWS\$1XRAY\$1DAEMON\$1ADRESSE | com.amazonaws.xray.emitter.DAEMON-Adresse | 127.0.0. 1:2000 | | Ablaufverfolgung aktiviert | Boolesch | Wahr, falsch | Ermöglicht die Instrumentierung durch den X-Ray-Agenten. | AWS\$1XRAY\$1TRACING\$1ENABLED | com.amazonaws.xray.TracingEnabled | TRUE | | Strategie für die Probenahme | Zeichenfolge | ZENTRAL, LOKAL, KEINER, ALLES | Die vom Agenten verwendete Probenahmestrategie. ALL erfasst alle Anfragen, NONE erfasst keine Anfragen. Siehe [Regeln für die Probenahme](xray-sdk-java-configuration.md#xray-sdk-java-configuration-sampling). | – | – | ZENTRALE | | traceIdInjectionPräfix | Zeichenfolge | Jede Zeichenfolge | Schließt das angegebene Präfix vor der Eingabe von Trace IDs in die Protokolle ein. | – | – | Keine (leere Zeichenfolge) | | samplingRulesManifest | Zeichenfolge | Ein absoluter Dateipfad | Der Pfad zu einer Datei mit benutzerdefinierten Stichprobenregeln, die als Quelle für Stichprobenregeln für die lokale Stichprobenstrategie oder als Ausweichregeln für die zentrale Strategie verwendet werden soll. | – | – | [DefaultSamplingRules.json](https://github.com/aws/aws-xray-sdk-java/blob/master/aws-xray-recorder-sdk-core/src/main/resources/com/amazonaws/xray/strategy/sampling/DefaultSamplingRules.json) | | awsServiceHandlerManifest | Zeichenfolge | Ein absoluter Dateipfad | Der Pfad zu einer Zulassungsliste für benutzerdefinierte Parameter, die zusätzliche Informationen von AWS SDK-Clients erfasst. | – | – | [DefaultOperationParameterWhitelist.json](https://github.com/aws/aws-xray-sdk-java/blob/master/aws-xray-recorder-sdk-aws-sdk-v2/src/main/resources/com/amazonaws/xray/interceptors/DefaultOperationParameterWhitelist.json) | | awsSdkVersion | Ganzzahl | 1, 2 | Version des [AWS SDK for Java](https://docs.aws.amazon.com/sdk-for-java/index.html), das Sie verwenden. Wird ignoriert, wenn `awsServiceHandlerManifest` es nicht auch gesetzt ist. | – | – | 2 | | maxStackTraceLänge | Ganzzahl | Nichtnegative Ganzzahlen | Die maximale Anzahl von Zeilen eines Stack-Trace, die in einem Trace aufgezeichnet werden sollen. | – | – | 50 | | StreamingThreshold | Ganzzahl | Nichtnegative Ganzzahlen | Nachdem mindestens so viele Untersegmente geschlossen wurden, werden sie an den Daemon gestreamt, um zu verhindern, dass die Blöcke out-of-band zu groß werden. | – | – | 100 | | traceIdInjection | Boolesch | Wahr, falsch | Aktiviert die X-Ray-Trace-ID-Injektion in Protokolle, wenn die in der [Protokollierungskonfiguration beschriebenen Abhängigkeiten und die Konfiguration](xray-sdk-java-configuration.md#xray-sdk-java-configuration-logging) ebenfalls hinzugefügt werden. Sonst tut es nichts. | – | – | TRUE | | Plugins aktiviert | Boolesch | Wahr, falsch | Aktiviert Plugins, die Metadaten über die AWS Umgebungen aufzeichnen, in denen Sie arbeiten. Siehe [Plugins](xray-sdk-java-configuration.md#xray-sdk-java-configuration-plugins). | – | – | TRUE | | collectSqlQueries | Boolesch | Wahr, Falsch | Zeichnet SQL-Abfragezeichenfolgen nach bestem Wissen und Gewissen in SQL-Untersegmenten auf. | – | – | FALSE | | Kontextweiterleitung | Boolesch | Wahr, falsch | Gibt automatisch den X-Ray-Kontext zwischen Threads weiter, falls der Wert wahr ist. Andernfalls verwendet Thread Local, um den Kontext zu speichern, und eine manuelle Weitergabe zwischen Threads ist erforderlich. | – | – | TRUE | ### Protokollierungskonfiguration Das Log Level des X-Ray-Agenten kann auf die gleiche Weise wie das X-Ray SDK for Java konfiguriert werden. Weitere Informationen [Protokollierung](xray-sdk-java-configuration.md#xray-sdk-java-configuration-logging) zur Konfiguration der Protokollierung mit dem X-Ray SDK for Java finden Sie unter. ### Manuelle Instrumentierung Wenn Sie zusätzlich zur automatischen Instrumentierung des Agenten eine manuelle Instrumentierung durchführen möchten, fügen Sie das X-Ray SDK als Abhängigkeit zu Ihrem Projekt hinzu. Beachten Sie, dass die unter [Tracing Incoming Requests](xray-sdk-java-filters.md) erwähnten benutzerdefinierten Servlet-Filter des SDK nicht mit dem X-Ray-Agenten kompatibel sind. **Anmerkung** Sie müssen die neueste Version des X-Ray-SDK verwenden, um die manuelle Instrumentierung durchzuführen und gleichzeitig den Agenten zu verwenden. Wenn Sie in einem Maven-Projekt arbeiten, fügen Sie Ihrer `pom.xml` Datei die folgenden Abhängigkeiten hinzu. ```       com.amazonaws     aws-xray-recorder-sdk-core     2.11.0      ``` Wenn Sie in einem Gradle-Projekt arbeiten, fügen Sie Ihrer `build.gradle` Datei die folgenden Abhängigkeiten hinzu. ``` implementation 'com.amazonaws:aws-xray-recorder-sdk-core:2.11.0' ``` Sie können während der Verwendung des Agenten zusätzlich zu [Anmerkungen, Metadaten und Benutzern](xray-sdk-java-segment.md) [benutzerdefinierte Untersegmente](xray-sdk-java-subsegments.md) hinzufügen, genau wie IDs beim normalen SDK. Der Agent verbreitet den Kontext automatisch zwischen Threads, sodass bei der Arbeit mit Multithread-Anwendungen keine Behelfslösungen für die Übertragung des Kontexts erforderlich sein sollten. ## Fehlerbehebung Da der Agent über eine vollautomatische Instrumentierung verfügt, kann es schwierig sein, die Ursache eines Problems zu ermitteln, wenn Probleme auftreten. Wenn der X-Ray-Agent bei Ihnen nicht wie erwartet funktioniert, überprüfen Sie die folgenden Probleme und Lösungen. Der X-Ray-Agent und das SDK verwenden Jakarta Commons Logging (JCL). Um die Logging-Ausgabe zu sehen, stellen Sie sicher, dass sich eine Bridge, die JCL mit Ihrem Logging-Backend verbindet, im Klassenpfad befindet, wie im folgenden Beispiel: oder. `log4j-jcl` `jcl-over-slf4j` ### Problem: Ich habe den Java-Agenten in meiner Anwendung aktiviert, sehe aber nichts auf der X-Ray-Konsole **Läuft der X-Ray-Daemon auf demselben Computer?** Falls nicht, lesen Sie in der [Dokumentation zum X-Ray-Daemon](https://docs.aws.amazon.com/xray/latest/devguide/xray-daemon.html) nach, um ihn einzurichten. **Sehen Sie in Ihren Anwendungsprotokollen eine Meldung wie „Initialisierung des X-Ray Agent Recorders“?** Wenn Sie den Agenten korrekt zu Ihrer Anwendung hinzugefügt haben, wird diese Meldung auf der INFO-Ebene protokolliert, wenn Ihre Anwendung gestartet wird, bevor sie Anfragen entgegennimmt. Wenn diese Meldung nicht angezeigt wird, läuft der Java-Agent nicht zusammen mit Ihrem Java-Prozess. Stellen Sie sicher, dass Sie alle Einrichtungsschritte korrekt und ohne Tippfehler ausgeführt haben. **Sehen Sie in Ihren Anwendungsprotokollen mehrere Fehlermeldungen mit der Aufschrift „Ausnahme fehlt AWS X-Ray im Kontext unterdrücken“?** Diese Fehler treten auf, weil der Agent versucht, Downstream-Anfragen wie AWS SDK-Anfragen oder SQL-Abfragen zu instrumentieren, der Agent aber nicht in der Lage war, automatisch ein Segment zu erstellen. Wenn Sie viele dieser Fehler sehen, ist der Agent möglicherweise nicht das beste Tool für Ihren Anwendungsfall und Sie sollten stattdessen eine manuelle Instrumentierung mit dem X-Ray-SDK in Betracht ziehen. Alternativ können Sie die X-Ray [SDK-Debug-Logs](xray-sdk-java-configuration.md#xray-sdk-java-configuration-logging) aktivieren, um den Stack-Trace zu sehen, wo die kontextlosen Ausnahmen auftreten. Sie können diese Teile Ihres Codes mit benutzerdefinierten Segmenten umschließen, wodurch diese Fehler behoben werden sollten. Ein Beispiel für das Umschließen von Downstream-Anfragen mit benutzerdefinierten Segmenten finden Sie im Beispielcode unter [Instrumentieren von Startcode](scorekeep-startup.md). ### Problem: Einige der Segmente, die ich erwarte, erscheinen nicht auf der X-Ray-Konsole **Verwendet Ihre Anwendung Multithreading?** Wenn einige Segmente, von denen Sie erwarten, dass sie erstellt werden, nicht in Ihrer Konsole erscheinen, könnte dies an Hintergrund-Threads in Ihrer Anwendung liegen. Wenn Ihre Anwendung Aufgaben mithilfe von Hintergrund-Threads ausführt, die „Fire and Forget“ sind, wie z. B. einen einmaligen Aufruf einer Lambda-Funktion mit dem AWS SDK oder das regelmäßige Abfragen einiger HTTP-Endpunkte, kann dies den Agenten verwirren, während er den Kontext zwischen Threads verbreitet. Um zu überprüfen, ob dies Ihr Problem ist, aktivieren Sie die X-Ray SDK-Debug-Logs und suchen Sie nach Meldungen wie: *Segment wird nicht ausgegeben, da es Untersegmente in Bearbeitung übergeordnet* hat. Um dieses Problem zu umgehen, können Sie versuchen, den Hintergrund-Threads beizutreten, bevor Ihr Server zurückkehrt, um sicherzustellen, dass die gesamte in ihnen geleistete Arbeit aufgezeichnet wird. Oder Sie können die `contextPropagation` Konfiguration des Agenten so einstellen, dass die `false` Kontextweiterleitung in Hintergrund-Threads deaktiviert wird. In diesem Fall müssen Sie diese Threads manuell mit benutzerdefinierten Segmenten instrumentieren oder die Ausnahmen ignorieren, die sie erzeugen, wenn der Kontext fehlt. **Haben Sie Stichprobenregeln eingerichtet?** Wenn scheinbar zufällige oder unerwartete Segmente auf der X-Ray-Konsole erscheinen oder die Segmente, von denen Sie erwarten, dass sie sich auf der Konsole befinden, nicht, liegt möglicherweise ein Sampling-Problem vor. Der X-Ray-Agent wendet zentralisierte Stichproben auf alle von ihm erstellten Segmente an und verwendet dabei die Regeln der X-Ray-Konsole. Die Standardregel lautet, dass 1 Segment pro Sekunde plus 5% der nachfolgenden Segmente abgetastet werden. Das bedeutet, dass Segmente, die schnell mit dem Agenten erstellt werden, möglicherweise nicht gesampelt werden. Um dieses Problem zu lösen, sollten Sie auf der X-Ray-Konsole benutzerdefinierte Sampling-Regeln erstellen, die die gewünschten Segmente entsprechend abtasten. Weitere Informationen finden Sie unter [Sampling](xray-console-sampling.md). # Konfiguration des X-Ray SDK for Java **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 SDK for Java enthält eine Klasse mit dem Namen`AWSXRay`, die den globalen Rekorder bereitstellt. Dies ist ein `TracingHandler`, mit dem Sie Ihren Code instrumentieren können. Sie können die globale Aufzeichnung so konfigurieren, dass der `AWSXRayServletFilter`, der Segmente für eingehende HTTP-Aufrufe erstellt, angepasst wird. **Topics** + [Service-Plugins](#xray-sdk-java-configuration-plugins) + [Regeln für die Probenahme](#xray-sdk-java-configuration-sampling) + [Protokollierung](#xray-sdk-java-configuration-logging) + [Segment-Listeners](#xray-sdk-java-configuration-listeners) + [Umgebungsvariablen](#xray-sdk-java-configuration-envvars) + [Systemeigenschaften](#xray-sdk-java-configuration-sysprops) ## 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. + Amazon EKS — `EKSPlugin` fügt die Container-ID, den Clusternamen, die Pod-ID und die CloudWatch Logs-Gruppe hinzu. ![\[Segmentieren Sie Ressourcendaten mit Amazon EC2- und Elastic Beanstalk-Plugins.\]](http://docs.aws.amazon.com/de_de/xray/latest/devguide/images/scorekeep-PUTrules-segment-resources.png) Um ein Plugin zu verwenden, rufen Sie `withPlugin` im `AWSXRayRecorderBuilder` auf. **Example src/main/java/scorekeep/WebConfig.java — Rekorder** ``` import [com.amazonaws.xray.AWSXRay](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/AWSXRay.html); import [com.amazonaws.xray.AWSXRayRecorderBuilder](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/AWSXRayRecorderBuilder.html); import [com.amazonaws.xray.plugins.EC2Plugin](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/plugins/EC2Plugin.html); import [com.amazonaws.xray.plugins.ElasticBeanstalkPlugin](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/plugins/ElasticBeanstalkPlugin.html); import [com.amazonaws.xray.strategy.sampling.LocalizedSamplingStrategy](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/strategy/sampling/LocalizedSamplingStrategy.html); @Configuration public class WebConfig { ... static { AWSXRayRecorderBuilder builder = AWSXRayRecorderBuilder.standard().withPlugin(new EC2Plugin()).withPlugin(new ElasticBeanstalkPlugin()); URL ruleFile = WebConfig.class.getResource("/sampling-rules.json"); builder.withSamplingStrategy(new LocalizedSamplingStrategy(ruleFile)); AWSXRay.setGlobalRecorder(builder.build()); } } ``` Das SDK verwendet auch Plugin-Einstellungen, um das `origin` Feld im 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 Sicherungsregeln in Spring bereitzustellen, konfigurieren Sie den globalen Recorder mit einer `CentralizedSamplingStrategy` in einer Konfigurationsklasse. **Example src/main/java/myapp/WebConfig.java — Rekorder-Konfiguration** ``` import [com.amazonaws.xray.AWSXRay](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/AWSXRay.html); import [com.amazonaws.xray.AWSXRayRecorderBuilder](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/AWSXRayRecorderBuilder.html); import [com.amazonaws.xray.javax.servlet.AWSXRayServletFilter](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/javax/servlet/AWSXRayServletFilter.html); import [com.amazonaws.xray.plugins.EC2Plugin](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/plugins/EC2Plugin.html); import [com.amazonaws.xray.strategy.sampling.LocalizedSamplingStrategy](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/strategy/sampling/LocalizedSamplingStrategy.html); @Configuration public class WebConfig { static { AWSXRayRecorderBuilder builder = AWSXRayRecorderBuilder.standard().withPlugin(new EC2Plugin()); URL ruleFile = WebConfig.class.getResource("/sampling-rules.json"); builder.withSamplingStrategy(new CentralizedSamplingStrategy(ruleFile)); AWSXRay.setGlobalRecorder(builder.build()); } ``` Für Tomcat fügen Sie einen Listener hinzu, der `ServletContextListener` erweitert, und registrieren den Listener in der Bereitstellungsbeschreibung. **Example src/com/myapp/web/Startup.java** ``` import [com.amazonaws.xray.AWSXRay](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/AWSXRay.html); import [com.amazonaws.xray.AWSXRayRecorderBuilder](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/AWSXRayRecorderBuilder.html); import [com.amazonaws.xray.plugins.EC2Plugin](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/plugins/EC2Plugin.html); import [com.amazonaws.xray.strategy.sampling.LocalizedSamplingStrategy](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/strategy/sampling/LocalizedSamplingStrategy.html); import java.net.URL; import javax.servlet.ServletContextEvent; import javax.servlet.ServletContextListener; public class Startup implements ServletContextListener { @Override public void contextInitialized(ServletContextEvent event) { AWSXRayRecorderBuilder builder = AWSXRayRecorderBuilder.standard().withPlugin(new EC2Plugin()); URL ruleFile = Startup.class.getResource("/sampling-rules.json"); builder.withSamplingStrategy(new CentralizedSamplingStrategy(ruleFile)); AWSXRay.setGlobalRecorder(builder.build()); } @Override public void contextDestroyed(ServletContextEvent event) { } } ``` **Example WEB-INF/web.xml** ``` ... com.myapp.web.Startup ``` Um nur lokale Regeln zu verwenden, ersetzen Sie die `CentralizedSamplingStrategy` durch eine `LocalizedSamplingStrategy`. ``` builder.withSamplingStrategy(new LocalizedSamplingStrategy(ruleFile)); ``` ## Protokollierung Standardmäßig gibt das SDK Meldungen `ERROR` auf -Ebene in Ihre Anwendungsprotokolle aus. Sie können die Protokollierung auf Debug-Ebene im SDK aktivieren, um detailliertere Protokolle in Ihrer Anwendungsprotokolldatei auszugeben. Gültige Protokollebenen sind`DEBUG`,, `INFO``WARN`, `ERROR` und. `FATAL` `FATAL`Bei der Protokollebene werden alle Protokollmeldungen stummgeschaltet, da das SDK nicht auf fataler Ebene protokolliert. **Example application.properties** Legen Sie die Protokollierungsebene mit der `logging.level.com.amazonaws.xray`-Eigenschaft fest. ``` logging.level.com.amazonaws.xray = DEBUG ``` Verwenden Sie Debug-Protokolle, um Probleme wie nicht geschlossene Untersegmente zu identifizieren, wenn Sie [Untersegmente manuell generieren](xray-sdk-java-subsegments.md). ### Trace-ID-Injection in Protokolle Wenn Sie den Protokollanweisungen Ihre aktuelle vollqualifizierte Trace-ID zur Verfügung stellen möchten, können Sie die ID in den zugeordneten Diagnosekontext (MDC) einfügen. Über die `SegmentListener`-Schnittstelle werden Methoden während der Ereignisse des Segmentlebenszyklus aus dem X-Ray-Recorder aufgerufen. Wenn ein Segment oder Teilsegment beginnt, wird die qualifizierte Trace-ID mit dem Schlüssel `AWS-XRAY-TRACE-ID` in den MDC injiziert. Wenn dieses Segment endet, wird der Schlüssel aus dem MDC entfernt. Dadurch wird die Trace-ID der verwendeten Protokollierungsbibliothek verfügbar gemacht. Wenn ein Teilsegment endet, wird seine übergeordnete ID in den MDC injiziert. **Example vollqualifizierte Trace-ID** Die vollqualifizierte ID wird als `TraceID@EntityID` dargestellt. ``` 1-5df42873-011e96598b447dfca814c156@541b3365be3dafc3 ``` Diese Funktion funktioniert mit Java-Anwendungen, die mit dem AWS X-Ray SDK for Java instrumentiert sind, und unterstützt die folgenden Logging-Konfigurationen: + SLF4J Frontend-API mit Logback-Backend + SLF4J Frontend-API mit Log4J2-Backend + Log4J2 Frontend-API mit Log4J2-Backend In den folgenden Registerkarten finden Sie die Anforderungen jedes Frontends und jedes Backends. ------ #### [ SLF4J Frontend ] 1. Fügen Sie Ihrem Projekt die folgende Maven-Abhängigkeit hinzu. ``` com.amazonaws aws-xray-recorder-sdk-slf4j 2.11.0 ``` 1. Schließen Sie beim Erstellen von `AWSXRayRecorder` die `withSegmentListener`-Methode ein. Dadurch wird eine `SegmentListener` Klasse hinzugefügt, die automatisch einen neuen Trace in den J MDC einfügt. IDs SLF4 Der `SegmentListener` akzeptiert eine optionale Zeichenfolge als Parameter, um das Präfix der Log-Anweisung zu konfigurieren. Das Präfix kann auf folgende Weise konfiguriert werden: + **Keine** — Verwendet das `AWS-XRAY-TRACE-ID` Standardpräfix. + **Leer** — Verwendet eine leere Zeichenfolge (z. B.`""`). + **Benutzerdefiniert** — Verwendet ein benutzerdefiniertes Präfix, wie es in der Zeichenfolge definiert ist. **Example `AWSXRayRecorderBuilder`-Anweisung** ``` AWSXRayRecorderBuilder builder = AWSXRayRecorderBuilder .standard().withSegmentListener(new SLF4JSegmentListener("CUSTOM-PREFIX")); ``` ------ #### [ Log4J2 front end ] 1. Fügen Sie Ihrem Projekt die folgende Maven-Abhängigkeit hinzu. ``` com.amazonaws aws-xray-recorder-sdk-log4j 2.11.0 ``` 1. Schließen Sie beim Erstellen von `AWSXRayRecorder` die `withSegmentListener`-Methode ein. Dadurch wird eine `SegmentListener` Klasse hinzugefügt, die automatisch einen neuen vollqualifizierten Trace IDs in den SLF4 J MDC einfügt. Der `SegmentListener` akzeptiert eine optionale Zeichenfolge als Parameter, um das Präfix der Log-Anweisung zu konfigurieren. Das Präfix kann auf folgende Weise konfiguriert werden: + **Keine** — Verwendet das `AWS-XRAY-TRACE-ID` Standardpräfix. + **Leer** — Verwendet eine leere Zeichenfolge (z. B.`""`) und entfernt das Präfix. + **Benutzerdefiniert** — Verwendet das in der Zeichenfolge definierte benutzerdefinierte Präfix. **Example `AWSXRayRecorderBuilder`-Anweisung** ``` AWSXRayRecorderBuilder builder = AWSXRayRecorderBuilder .standard().withSegmentListener(new Log4JSegmentListener("CUSTOM-PREFIX")); ``` ------ #### [ Logback backend ] Um die Trace-ID in die Protokollereignisse einzufügen, müssen Sie das `PatternLayout` des Loggers ändern, der jede Protokollierungsanweisung formatiert. 1. Suchen Sie, wo das `patternLayout` konfiguriert ist. Sie können dies programmgesteuert oder über eine XML-Konfigurationsdatei erreichen. Weitere Informationen finden Sie unter [Logback-Konfiguration](http://logback.qos.ch/manual/configuration.html). 1. Fügen Sie `%X{AWS-XRAY-TRACE-ID}` an einer beliebigen Stelle in `patternLayout` ein, um die Trace-ID in zukünftige Protokollierungsanweisungen einzufügen. `%X{}` gibt an, dass Sie mit dem aus dem MDC bereitgestellten Schlüssel einen Wert abrufen. Weitere Informationen zu PatternLayouts In Logback finden Sie unter [PatternLayout](https://logback.qos.ch/manual/layouts.html#ClassicPatternLayout). ------ #### [ Log4J2 backend ] 1. Suchen Sie, wo das `patternLayout` konfiguriert ist. Sie können dies programmgesteuert oder über eine im XML-, JSON-, YAML- oder Eigenschaftenformat geschriebene Konfigurationsdatei erreichen. Weitere Informationen zum Konfigurieren von Log4J2 über eine Konfigurationsdatei finden Sie unter [Konfiguration](https://logging.apache.org/log4j/2.x/manual/configuration.html). Weitere Informationen zur programmgesteuerten Konfiguration von Log4J2 finden Sie unter [Programmatische Konfiguration](https://logging.apache.org/log4j/2.x/manual/customconfig.html). 1. Fügen Sie `%X{AWS-XRAY-TRACE-ID}` an einer beliebigen Stelle in `PatternLayout` ein, um die Trace-ID in zukünftige Protokollierungsanweisungen einzufügen. `%X{}` gibt an, dass Sie mit dem aus dem MDC bereitgestellten Schlüssel einen Wert abrufen. [Weitere Informationen PatternLayouts zu Log4J2 finden Sie unter Pattern Layout.](https://logging.apache.org/log4j/2.x/manual/layouts.html#Pattern_Layout) ------ **Beispiel für Trace-ID-Injection** Im Folgenden wird eine `PatternLayout`-Zeichenfolge angezeigt, die geändert wurde, sodass die Trace-ID enthalten ist. Die Trace-ID wird nach dem Thread-Namen (`%t`) und vor der Protokollebene (`%-5p`) ausgegeben. **Example `PatternLayout` mit ID-Injection** ``` %d{HH:mm:ss.SSS} [%t] %X{AWS-XRAY-TRACE-ID} %-5p %m%n ``` AWS X-Ray druckt automatisch den Schlüssel und die Trace-ID in der Protokollanweisung aus, um das Parsen zu vereinfachen. Im Folgenden wird eine Protokollanweisung dargestellt, die das modifizierte `PatternLayout` verwendet. **Example Protokollanweisung mit ID-Injection** ``` 2019-09-10 18:58:30.844 [nio-5000-exec-4] AWS-XRAY-TRACE-ID: 1-5d77f256-19f12e4eaa02e3f76c78f46a@1ce7df03252d99e1 WARN 1 - Your logging message here ``` Die Protokollierungsnachricht selbst ist im Muster `%m` eingebettet und wird beim Aufruf des Loggers festgelegt. ## Segment-Listeners Segment-Listener sind eine Schnittstelle zum Abfangen von Lebenszyklusereignissen wie dem Anfang und Ende von Segmenten, die von der erzeugt werden. `AWSXRayRecorder` Die Implementierung einer Segment-Listener-Ereignisfunktion könnte darin bestehen, allen Teilsegmenten dieselbe Anmerkung hinzuzufügen, wenn sie mit [https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/listeners/SegmentListener.html#onBeginSubsegment-com.amazonaws.xray.entities.Subsegment-](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/listeners/SegmentListener.html#onBeginSubsegment-com.amazonaws.xray.entities.Subsegment-) erstellt werden, eine Meldung zu protokollieren, nachdem jedes Segment mit [https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/listeners/SegmentListener.html#afterEndSegment-com.amazonaws.xray.entities.Segment-](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/listeners/SegmentListener.html#afterEndSegment-com.amazonaws.xray.entities.Segment-) an den Daemon gesendet wurde, oder von SQL Interceptors mit [https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/listeners/SegmentListener.html#beforeEndSubsegment-com.amazonaws.xray.entities.Subsegment-](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/listeners/SegmentListener.html#beforeEndSubsegment-com.amazonaws.xray.entities.Subsegment-) gesendete Abfragen aufzuzeichnen, um zu überprüfen, ob das Teilsegment eine SQL-Abfrage darstellt, wobei zusätzliche Metadaten hinzugefügt werden, falls dies der Fall ist. Die vollständige Liste der `SegmentListener` Funktionen finden Sie in der Dokumentation für das [AWS X-Ray Recorder SDK for Java API](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/listeners/SegmentListener.html). Das folgende Beispiel zeigt, wie Sie allen Teilsegmenten bei der Erstellung eine konsistente Anmerkung mit [https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/listeners/SegmentListener.html#onBeginSubsegment-com.amazonaws.xray.entities.Subsegment-](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/listeners/SegmentListener.html#onBeginSubsegment-com.amazonaws.xray.entities.Subsegment-) hinzufügen und mit [https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/listeners/SegmentListener.html#afterEndSegment-com.amazonaws.xray.entities.Segment-](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/listeners/SegmentListener.html#afterEndSegment-com.amazonaws.xray.entities.Segment-) eine Protokollmeldung am Ende jedes Segments drucken. **Example MySegmentListener.java** ``` import com.amazonaws.xray.entities.Segment; import com.amazonaws.xray.entities.Subsegment; import com.amazonaws.xray.listeners.SegmentListener; public class MySegmentListener implements SegmentListener { ..... @Override public void onBeginSubsegment(Subsegment subsegment) { subsegment.putAnnotation("annotationKey", "annotationValue"); } @Override public void afterEndSegment(Segment segment) { // Be mindful not to mutate the segment logger.info("Segment with ID " + segment.getId()); } } ``` Dieser benutzerdefinierte Segment-Listener wird dann beim Erstellen des `AWSXRayRecorder` referenziert. **Example AWSXRayRecorderBuilder Aussage** ``` AWSXRayRecorderBuilder builder = AWSXRayRecorderBuilder .standard().withSegmentListener(new MySegmentListener()); ``` ## Umgebungsvariablen Sie können Umgebungsvariablen verwenden, um das X-Ray SDK for Java zu konfigurieren. Das SDK unterstützt die folgenden Variablen. + `AWS_XRAY_CONTEXT_MISSING`— Stellen Sie diese Option ein`RUNTIME_ERROR`, um Ausnahmen auszulösen, 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_LOG_GROUP`— Legen Sie den Namen einer Protokollgruppe auf eine Protokollgruppe fest, die Ihrer Anwendung zugeordnet ist. Wenn Ihre Protokollgruppe dasselbe AWS Konto und dieselbe Region wie Ihre Anwendung verwendet, sucht X-Ray anhand dieser angegebenen Protokollgruppe automatisch nach den Segmentdaten Ihrer Anwendung. Weitere Informationen zu Protokollgruppen finden Sie unter [Arbeiten mit Protokollgruppen und Streams](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/Working-with-log-groups-and-streams.html). + `AWS_XRAY_TRACING_NAME`— Legen Sie einen Dienstnamen fest, den das SDK für Segmente verwendet. Überschreibt den für die [Segmentbenennungsstrategie](xray-sdk-java-filters.md#xray-sdk-java-filters-naming) des Servlet-Filters festgelegten Dienstnamen. Umgebungsvariablen überschreiben äquivalente [Systemeigenschaften](#xray-sdk-java-configuration-sysprops) und Werte in Code. ## Systemeigenschaften Sie können Systemeigenschaften als JVM-spezifische Alternative zu [Umgebungsvariablen](#xray-sdk-java-configuration-envvars) verwenden. Das SDK unterstützt die folgenden Eigenschaften: + `com.amazonaws.xray.strategy.tracingName`— Entspricht`AWS_XRAY_TRACING_NAME`. + `com.amazonaws.xray.emitters.daemonAddress`— Entspricht`AWS_XRAY_DAEMON_ADDRESS`. + `com.amazonaws.xray.strategy.contextMissingStrategy`— Entspricht`AWS_XRAY_CONTEXT_MISSING`. Wenn eine Systemeigenschaft und die entsprechende Umgebungsvariable eingerichtet sind, wird der Wert der Umgebungsvariablen verwendet. Bei beiden Methoden werden Werte in Code überschrieben. # Nachverfolgung eingehender Anfragen mit dem X-Ray SDK for Java **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 verwenden, um eingehende HTTP-Anfragen zu verfolgen, die Ihre Anwendung auf einer EC2-Instance in Amazon EC2 oder Amazon ECS bearbeitet. AWS Elastic Beanstalk Verwenden Sie einen `Filter`, um eingehende HTTP-Anforderungen zu instrumentieren. Wenn Sie den X-Ray-Servlet-Filter zu Ihrer Anwendung hinzufügen, erstellt das X-Ray SDK for Java 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** + [Hinzufügen eines Ablaufverfolgungsfilters zu Ihrer Anwendung (Tomcat)](#xray-sdk-java-filters-tomcat) + [Hinzufügen eines Ablaufverfolgungsfilters zu Ihrer Anwendung (Spring)](#xray-sdk-java-filters-spring) + [Konfiguration einer Segmentbenennungsstrategie](#xray-sdk-java-filters-naming) ## Hinzufügen eines Ablaufverfolgungsfilters zu Ihrer Anwendung (Tomcat) Im Fall von Tomcat fügen Sie einen `` zur `web.xml`-Datei Ihres Projekts hinzu. Legen Sie mit dem `fixedName` Parameter einen [Servicenamen](#xray-sdk-java-filters-naming) fest, damit die erstellten Segmente auf eingehende Anforderungen angewendet werden. **Example WEB-INF/web.xml – Tomcat** ``` AWSXRayServletFilter com.amazonaws.xray.javax.servlet.AWSXRayServletFilter fixedName MyApp AWSXRayServletFilter * ``` ## Hinzufügen eines Ablaufverfolgungsfilters zu Ihrer Anwendung (Spring) Für Spring fügen Sie einen `Filter` zu Ihrer `WebConfig`-Klasse hinzu. Übermitteln Sie den Segmentnamen als Zeichenfolge an den [https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/javax/servlet/AWSXRayServletFilter.html](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/javax/servlet/AWSXRayServletFilter.html)-Konstruktor. **Example src/main/java/myapp/WebConfig.java - Frühling** ``` package myapp; import org.springframework.context.annotation.Configuration; import org.springframework.context.annotation.Bean; import javax.servlet.Filter; import [com.amazonaws.xray.javax.servlet.AWSXRayServletFilter](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/javax/servlet/AWSXRayServletFilter.html); @Configuration public class WebConfig { @Bean public Filter TracingFilter() { return new AWSXRayServletFilter("Scorekeep"); } } ``` ## 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 des Servlet-Filters den Namen Ihrer Anwendung, wie [im vorherigen Abschnitt](#xray-sdk-java-filters-tomcat) gezeigt, ein. Dies hat den gleichen Effekt wie das Erstellen eines Fixed [SegmentNamingStrategy](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/strategy/SegmentNamingStrategy.html)durch Aufrufen `SegmentNamingStrategy.fixed()` und Übergeben an den [https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/javax/servlet/AWSXRayServletFilter.html](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/javax/servlet/AWSXRayServletFilter.html)Konstruktor. **Anmerkung** Sie können den mit der `AWS_XRAY_TRACING_NAME`-[Umgebungsvariablen](xray-sdk-java-configuration.md#xray-sdk-java-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. Alternativ können Sie `dynamicNamingRecognizedHosts` und `dynamicNamingFallbackName` nutzen, um das Muster und den Standardnamen zu bestimmen und Segmente in Tomcat dynamisch zu benennen. **Example WEB-INF/web.xml – Servlet-Filter mit dynamischer Benennung** ``` AWSXRayServletFilter com.amazonaws.xray.javax.servlet.AWSXRayServletFilter dynamicNamingRecognizedHosts *.example.com dynamicNamingFallbackName MyApp AWSXRayServletFilter * ``` Erstellen Sie für Spring eine Dynamik, [SegmentNamingStrategy](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/strategy/SegmentNamingStrategy.html)indem Sie sie aufrufen`SegmentNamingStrategy.dynamic()`, und übergeben Sie sie an den `AWSXRayServletFilter` Konstruktor. **Example src/main/java/myapp/WebConfig.java — Servlet-Filter mit dynamischer Benennung** ``` package myapp; import org.springframework.context.annotation.Configuration; import org.springframework.context.annotation.Bean; import javax.servlet.Filter; import [com.amazonaws.xray.javax.servlet.AWSXRayServletFilter](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/javax/servlet/AWSXRayServletFilter.html); import [com.amazonaws.xray.strategy.SegmentNamingStrategy](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/strategy/SegmentNamingStrategy.html); @Configuration public class WebConfig { @Bean public Filter TracingFilter() { return new AWSXRayServletFilter(SegmentNamingStrategy.dynamic("MyApp", "*.example.com")); } } ``` # Verfolgen von AWS SDK-Aufrufen mit dem X-Ray SDK for Java **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 Java die Aufrufe im Downstream in [Untersegmenten](xray-sdk-java-subsegments.md). Verfolgte Ressourcen AWS-Services und Ressourcen, auf die Sie innerhalb dieser Services zugreifen (z. B. ein Amazon S3 S3-Bucket oder eine Amazon SQS SQS-Warteschlange), werden als Downstream-Knoten auf der Trace-Map in der X-Ray-Konsole angezeigt. Das X-Ray-SDK SDK for Java instrumentiert automatisch alle AWS-SDK-Clients, wenn Sie die `aws-sdk` und die `aws-sdk-instrumentor` [Submodule](xray-sdk-java.md#xray-sdk-java-submodules) in Ihren Build aufnehmen. Wenn Sie das Instrumentor-Untermodul nicht einbeziehen, können Sie auswählen, welche Clients Sie instrumentieren möchten, und andere ausschließen. Um einzelne Clients zu instrumentieren, entfernen Sie das `aws-sdk-instrumentor` Submodul aus Ihrem Build und fügen Sie mithilfe des Client-Builders des Services ein `XRayClient` AS `TracingHandler` auf Ihrem AWS SDK-Client hinzu. Wenn Sie beispielsweise einen `AmazonDynamoDB`-Client instrumentieren möchten, übergeben Sie einen Ablaufverfolgungshandler an `AmazonDynamoDBClientBuilder`. **Example MyModel.java — DynamoDB-Client** ``` import [com.amazonaws.xray.AWSXRay](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/AWSXRay.html); import [com.amazonaws.xray.handlers.TracingHandler](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/handlers/TracingHandler.html); ... public class MyModel { private AmazonDynamoDB client = AmazonDynamoDBClientBuilder.standard() .withRegion(Regions.fromName(System.getenv("AWS_REGION"))) .withRequestHandlers(new TracingHandler(AWSXRay.getGlobalRecorder())) .build(); ... ``` 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 Um Downstream-Aufrufe AWS-Services mit AWS SDK für Java 2.2 und höher zu instrumentieren, können Sie das `aws-xray-recorder-sdk-aws-sdk-v2-instrumentor` Modul aus Ihrer Build-Konfiguration weglassen. Fügen Sie stattdessen das `aws-xray-recorder-sdk-aws-sdk-v2 module` ein und instrumentieren Sie dann einzelne Clients, indem Sie sie mit einem `TracingInterceptor` konfigurieren. **Example AWS SDK für Java 2.2 und höher — Tracing Interceptor** ``` import com.amazonaws.xray.interceptors.TracingInterceptor; import software.amazon.awssdk.core.client.config.ClientOverrideConfiguration import software.amazon.awssdk.services.dynamodb.DynamoDbClient; //... public class MyModel { private DynamoDbClient client = DynamoDbClient.builder() .region(Region.US_WEST_2) .overrideConfiguration(ClientOverrideConfiguration.builder() .addExecutionInterceptor(new TracingInterceptor()) .build() ) .build(); //... ``` # Rückverfolgung von Aufrufen an Downstream-HTTP-Webservices mit dem X-Ray SDK for Java **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 die Version von X-Ray SDK für Java verwenden, `HttpClient` um diese Aufrufe zu instrumentieren und die API als Downstream-Service zum Service Graph hinzuzufügen. Das X-Ray-SDK SDK for Java umfasst `DefaultHttpClient` `HttpClientBuilder` Klassen, die anstelle der HttpComponents Apache-Äquivalente verwendet werden können, um ausgehende HTTP-Aufrufe zu instrumentieren. + `com.amazonaws.xray.proxies.apache.http.DefaultHttpClient` - `org.apache.http.impl.client.DefaultHttpClient` + `com.amazonaws.xray.proxies.apache.http.HttpClientBuilder` - `org.apache.http.impl.client.HttpClientBuilder` Diese Bibliotheken befinden sich im [`aws-xray-recorder-sdk-apache-http`](xray-sdk-java.md)-Untermodul. Sie können Ihre vorhandenen Importanweisungen durch das X-Ray-Äquivalent ersetzen, um alle Clients zu instrumentieren, oder den vollqualifizierten Namen verwenden, wenn Sie einen Client für die Instrumentierung bestimmter Clients initialisieren. **Example HttpClientBuilder** ``` import com.fasterxml.jackson.databind.ObjectMapper; import org.apache.http.HttpEntity; import org.apache.http.client.methods.CloseableHttpResponse; import org.apache.http.client.methods.HttpGet; import org.apache.http.impl.client.CloseableHttpClient; import org.apache.http.util.EntityUtils; import [com.amazonaws.xray.proxies.apache.http.HttpClientBuilder](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/proxies/apache/http/HttpClientBuilder.html); ... public String randomName() throws IOException { CloseableHttpClient httpclient = HttpClientBuilder.create().build(); HttpGet httpGet = new HttpGet("http://names.example.com/api/"); CloseableHttpResponse response = httpclient.execute(httpGet); try { HttpEntity entity = response.getEntity(); InputStream inputStream = entity.getContent(); ObjectMapper mapper = new ObjectMapper(); Map jsonMap = mapper.readValue(inputStream, Map.class); String name = jsonMap.get("name"); EntityUtils.consume(entity); return name; } finally { response.close(); } } ``` Wenn Sie einen Aufruf einer Downstream-Web-API instrumentieren, zeichnet das X-Ray SDK for Java ein Untersegment mit Informationen über die HTTP-Anfrage und -Antwort auf. 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 for Java **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). ## SQL-Interzeptoren Instrumentieren Sie SQL-Datenbankabfragen, indem Sie den X-Ray SDK for Java JDBC Interceptor zu Ihrer Datenquellenkonfiguration hinzufügen. + **PostgreSQL** – `com.amazonaws.xray.sql.postgres.TracingInterceptor` + **MySQL** – `com.amazonaws.xray.sql.mysql.TracingInterceptor` Diese Interceptors befinden sich im [`aws-xray-recorder-sql-postgres`- bzw. `aws-xray-recorder-sql-mysql`-Untermodul](xray-sdk-java.md). Sie implementieren `org.apache.tomcat.jdbc.pool.JdbcInterceptor` und sind mit Tomcat-Verbindungspools kompatibel. **Anmerkung** Aus Sicherheitsgründen zeichnen die SQL Interceptors die SQL-Abfrage selbst innerhalb von Teilsegmenten nicht auf. Für Spring fügen Sie der Eigenschaftendatei einen Interceptor hinzu und erstellen Sie die Datenquelle mit dem `DataSourceBuilder` von Spring Boot. **Example `src/main/java/resources/application.properties` – PostgreSQL-JDBC-Interceptor** ``` spring.datasource.continue-on-error=true spring.jpa.show-sql=false spring.jpa.hibernate.ddl-auto=create-drop spring.datasource.jdbc-interceptors=com.amazonaws.xray.sql.postgres.TracingInterceptor spring.jpa.database-platform=org.hibernate.dialect.PostgreSQL94Dialect ``` **Example `src/main/java/myapp/WebConfig.java` – Datenquelle** ``` import org.springframework.boot.autoconfigure.EnableAutoConfiguration; import org.springframework.boot.autoconfigure.jdbc.DataSourceBuilder; import org.springframework.boot.context.properties.ConfigurationProperties; import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; import org.springframework.data.jpa.repository.config.EnableJpaRepositories; import javax.servlet.Filter; import javax.sql.DataSource; import java.net.URL; @Configuration @EnableAutoConfiguration @EnableJpaRepositories("myapp") public class RdsWebConfig { @Bean @ConfigurationProperties(prefix = "spring.datasource") public DataSource dataSource() { logger.info("Initializing PostgreSQL datasource"); return DataSourceBuilder.create() .driverClassName("org.postgresql.Driver") .url("jdbc:postgresql://" + System.getenv("RDS_HOSTNAME") + ":" + System.getenv("RDS_PORT") + "/ebdb") .username(System.getenv("RDS_USERNAME")) .password(System.getenv("RDS_PASSWORD")) .build(); } ... } ``` Rufen Sie für Tomcat die JDBC-Datenquelle mit einem Verweis `setJdbcInterceptors` auf die Klasse X-Ray SDK for Java auf. **Example `src/main/myapp/model.java` – Datenquelle** ``` import org.apache.tomcat.jdbc.pool.DataSource; ... DataSource source = new DataSource(); source.setUrl(url); source.setUsername(user); source.setPassword(password); source.setDriverClassName("com.mysql.jdbc.Driver"); source.setJdbcInterceptors("com.amazonaws.xray.sql.mysql.TracingInterceptor;"); ``` Die Tomcat JDBC Data Source-Bibliothek ist im X-Ray SDK for Java enthalten, aber Sie können sie als bereitgestellte Abhängigkeit von dem Dokument deklarieren, in dem Sie sie verwenden. **Example `pom.xml` – JDBC-Datenquelle** ``` org.apache.tomcat tomcat-jdbc 8.0.36 provided ``` ## Nativer SQL Tracing Decorator + Fügen Sie Ihre [https://github.com/aws/aws-xray-sdk-java/tree/master/aws-xray-recorder-sdk-sql](https://github.com/aws/aws-xray-sdk-java/tree/master/aws-xray-recorder-sdk-sql)Abhängigkeiten hinzu. + Dekorieren Sie Ihre Datenbank-Datenquelle, Verbindung oder Anweisung. ``` dataSource = TracingDataSource.decorate(dataSource) connection = TracingConnection.decorate(connection) statement = TracingStatement.decorateStatement(statement) preparedStatement = TracingStatement.decoratePreparedStatement(preparedStatement, sql) callableStatement = TracingStatement.decorateCallableStatement(callableStatement, sql) ``` # Generieren von benutzerdefinierten Untersegmenten mit dem X-Ray SDK for Java **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). 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. Um Untersegmente zu verwalten, verwenden Sie die Methoden `beginSubsegment` und `endSubsegment`. **Example GameModel.java — benutzerdefiniertes Untersegment** ``` import [com.amazonaws.xray.AWSXRay](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/AWSXRay.html); ... public void saveGame(Game game) throws SessionNotFoundException { // wrap in subsegment Subsegment subsegment = AWSXRay.beginSubsegment("Save Game"); try { // check session String sessionId = game.getSession(); if (sessionModel.loadSession(sessionId) == null ) { throw new SessionNotFoundException(sessionId); } mapper.save(game); } catch (Exception e) { subsegment.addException(e); throw e; } finally { AWSXRay.endSubsegment(); } } ``` In diesem Beispiel lädt der Code innerhalb des Untersegments die Spielsitzung aus DynamoDB mit einer Methode auf dem Sitzungsmodell und verwendet den DynamoDB-Mapper AWS SDK für Java des Spiels, um das Spiel zu speichern. Wenn Sie diesen Code in ein Untersegment einbinden, werden die Aufrufe zu DynamoDB-Unterelementen des `Save Game` Untersegments in der Trace-Ansicht in der Konsole. ![\[Timeline showing Scorekeep and DynamoDB operations with durations and status checks.\]](http://docs.aws.amazon.com/de_de/xray/latest/devguide/images/scorekeep-PUTrules-timeline-subsegments.png) Wenn der Code in Ihrem Untersegment geprüfte Ausnahmen auslöst, verpacken Sie ihn in einen `try`-Block und rufen Sie `AWSXRay.endSubsegment()` in einem `finally`-Block auf, um sicherzustellen, dass das Untersegment immer geschlossen ist. Wenn ein Untersegment nicht geschlossen ist, kann das übergeordnete Segment nicht abgeschlossen werden und wird nicht an X-Ray gesendet. Für Code, der keine geprüften Ausnahmen auslöst, können Sie den Code `AWSXRay.CreateSubsegment` als Lambda-Funktion übergeben. **Example Untersegment-Lambda-Funktion** ``` import [com.amazonaws.xray.AWSXRay](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/AWSXRay.html); AWSXRay.createSubsegment("getMovies", (subsegment) -> { // function code }); ``` Wenn Sie ein Untersegment innerhalb eines Segments oder eines anderen Untersegments erstellen, generiert das X-Ray SDK for Java 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" } }, ``` Bei asynchroner Programmierung und Multithread-Programmierung müssen Sie das Teilsegment manuell an die `endSubsegment()` Methode übergeben, um sicherzustellen, dass es korrekt geschlossen wird, da der X-Ray-Kontext während der asynchronen Ausführung geändert werden kann. Wenn ein asynchrones Teilsegment geschlossen wird, nachdem das übergeordnete Segment geschlossen wurde, streamt diese Methode automatisch das gesamte Segment an den X-Ray-Daemon. **Example Asynchrones Teilsegment** ``` @GetMapping("/api") public ResponseEntity api() { CompletableFuture.runAsync(() -> { Subsegment subsegment = AWSXRay.beginSubsegment("Async Work"); try { Thread.sleep(3000); } catch (InterruptedException e) { subsegment.addException(e); throw e; } finally { AWSXRay.endSubsegment(subsegment); } }); return ResponseEntity.ok().build(); } ``` # Hinzufügen von Anmerkungen und Metadaten zu Segmenten mit dem X-Ray SDK for Java **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-java-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 for Java aufnehmen](#xray-sdk-java-segment-annotations) + [Metadaten mit dem X-Ray SDK for Java aufzeichnen](#xray-sdk-java-segment-metadata) + [Benutzer IDs mit dem X-Ray SDK for Java aufzeichnen](#xray-sdk-java-segment-userid) ## Anmerkungen mit dem X-Ray SDK for Java 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. Eine Referenz des aktuellen Segments oder Untersegments finden Sie unter `AWSXRay`. ``` import [com.amazonaws.xray.AWSXRay](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/AWSXRay.html); import [com.amazonaws.xray.entities.Segment](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/entities/Segment.html); ... Segment document = AWSXRay.getCurrentSegment(); ``` oder ``` import [com.amazonaws.xray.AWSXRay](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/AWSXRay.html); import [com.amazonaws.xray.entities.Subsegment](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/entities/Subsegment.html); ... Subsegment document = AWSXRay.getCurrentSubsegment(); ``` 1. Rufen Sie `putAnnotation` mit einem Aktivierungsschlüssel und einem booleschen Wert oder einem Zeichenfolgenwert auf. ``` document.putAnnotation("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 `putAnnotation` 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 [https://github.com/awslabs/eb-java-scorekeep/tree/xray/src/main/java/scorekeep/GameModel.java](https://github.com/awslabs/eb-java-scorekeep/tree/xray/src/main/java/scorekeep/GameModel.java)— Anmerkungen und Metadaten** ``` import [com.amazonaws.xray.AWSXRay](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/AWSXRay.html); import [com.amazonaws.xray.entities.Segment](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/entities/Segment.html); import [com.amazonaws.xray.entities.Subsegment](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/entities/Subsegment.html); ... public void saveGame(Game game) throws SessionNotFoundException { // wrap in subsegment Subsegment subsegment = AWSXRay.beginSubsegment("## GameModel.saveGame"); try { // check session String sessionId = game.getSession(); if (sessionModel.loadSession(sessionId) == null ) { throw new SessionNotFoundException(sessionId); } Segment segment = AWSXRay.getCurrentSegment(); subsegment.putMetadata("resources", "game", game); segment.putAnnotation("gameid", game.getId()); mapper.save(game); } catch (Exception e) { subsegment.addException(e); throw e; } finally { AWSXRay.endSubsegment(); } } ``` ## Metadaten mit dem X-Ray SDK for Java 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. Eine Referenz des aktuellen Segments oder Untersegments finden Sie unter `AWSXRay`. ``` import [com.amazonaws.xray.AWSXRay](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/AWSXRay.html); import [com.amazonaws.xray.entities.Segment](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/entities/Segment.html); ... Segment document = AWSXRay.getCurrentSegment(); ``` oder ``` import [com.amazonaws.xray.AWSXRay](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/AWSXRay.html); import [com.amazonaws.xray.entities.Subsegment](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/entities/Subsegment.html); ... Subsegment document = AWSXRay.getCurrentSubsegment(); ``` 1. Rufen Sie `putMetadata` mit einem String-Namespace, einem Aktivierungsschlüssel sowie einem booleschen Wert, einer Zahl, einer Zeichenfolge oder einem Objektwert auf. ``` document.putMetadata("my namespace", "my key", "my value"); ``` oder Rufen Sie `putMetadata` nur mit einem Aktivierungsschlüssel und einem Wert auf. ``` document.putMetadata("my key", "my value"); ``` Wenn Sie keinen Namespace angeben, verwendet SDK `default`. Wenn `putMetadata` zweimal mit demselben Schlüssel aufgerufen wird, werden zuvor aufgezeichnete Werte im gleichen Segment oder Untersegment überschrieben. **Example [https://github.com/awslabs/eb-java-scorekeep/tree/xray/src/main/java/scorekeep/GameModel.java](https://github.com/awslabs/eb-java-scorekeep/tree/xray/src/main/java/scorekeep/GameModel.java)— Anmerkungen und Metadaten** ``` import [com.amazonaws.xray.AWSXRay](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/AWSXRay.html); import [com.amazonaws.xray.entities.Segment](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/entities/Segment.html); import [com.amazonaws.xray.entities.Subsegment](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/entities/Subsegment.html); ... public void saveGame(Game game) throws SessionNotFoundException { // wrap in subsegment Subsegment subsegment = AWSXRay.beginSubsegment("## GameModel.saveGame"); try { // check session String sessionId = game.getSession(); if (sessionModel.loadSession(sessionId) == null ) { throw new SessionNotFoundException(sessionId); } Segment segment = AWSXRay.getCurrentSegment(); subsegment.putMetadata("resources", "game", game); segment.putAnnotation("gameid", game.getId()); mapper.save(game); } catch (Exception e) { subsegment.addException(e); throw e; } finally { AWSXRay.endSubsegment(); } } ``` ## Benutzer IDs mit dem X-Ray SDK for Java aufzeichnen Zeichnen Sie Segmente des Benutzers IDs auf Anfrage auf, um den Benutzer zu identifizieren, der die Anfrage gesendet hat. **Um den Benutzer aufzuzeichnen IDs** 1. Eine Referenz des aktuellen Segments finden Sie unter `AWSXRay`. ``` import [com.amazonaws.xray.AWSXRay](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/AWSXRay.html); import [com.amazonaws.xray.entities.Segment](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/entities/Segment.html); ... Segment document = AWSXRay.getCurrentSegment(); ``` 1. Rufen Sie `setUser` mit einer Zeichenfolgen-ID des Benutzers auf, der die Anforderung gesendet hat. ``` document.setUser("U12345"); ``` Sie können `setUser` in Ihrem Controller aufrufen, um die Benutzer-ID aufzuzeichnen, sobald die Anwendung mit der Bearbeitung 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 [src/main/java/scorekeep/MoveController.java](https://github.com/awslabs/eb-java-scorekeep/tree/xray/src/main/java/scorekeep/MoveController.java) — Benutzer-ID** ``` import [com.amazonaws.xray.AWSXRay](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/AWSXRay.html); ... @RequestMapping(value="/{userId}", method=RequestMethod.POST) public Move newMove(@PathVariable String sessionId, @PathVariable String gameId, @PathVariable String userId, @RequestBody String move) throws SessionNotFoundException, GameNotFoundException, StateNotFoundException, RulesException { AWSXRay.getCurrentSegment().setUser(userId); return moveFactory.newMove(sessionId, gameId, userId, move); } ``` Nutzen Sie das `user`-Schlüsselwort in einem [Filterausdruck](xray-console-filters.md), um Ablaufverfolgungen einer Benutzer-ID zu finden. ## AWS X-Ray Metriken für das X-Ray SDK for Java **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). In diesem Thema werden der AWS X-Ray Namespace, die Metriken und die Dimensionen beschrieben. Sie können das X-Ray SDK for Java verwenden, um CloudWatch Amazon-Metriken ohne Stichproben aus Ihren gesammelten X-Ray-Segmenten zu veröffentlichen. Diese Metriken werden von der Start- und Endzeit des Segments sowie den Status-Flags für Fehler, Ausfall und Ablehnung abgeleitet. Mit diesen Trace-Metriken können Sie Wiederholungen und Abhängigkeitsprobleme in Teilsegmenten anzeigen. CloudWatch ist ein Metrik-Repository. Eine Metrik ist das grundlegende Konzept von Datenpunkten CloudWatch und stellt eine zeitlich geordnete Menge von Datenpunkten dar. Sie (oder AWS-Services) veröffentlichen Metrikdatenpunkte in CloudWatch und rufen Statistiken über diese Datenpunkte als geordneten Satz von Zeitreihendaten ab. Metriken werden eindeutig durch einen Namen, ein Namespace und eine oder mehrere Dimensionen definiert. Jeder Datenpunkt verfügt über einen Zeitstempel und optional über eine Maßeinheit. Wenn Sie Statistiken anfordern, wird der zurückgegebene Datenstrom durch den Namespace, den Metrik-Namen und die Dimension identifiziert. Weitere Informationen zu CloudWatch finden Sie im [https://docs.aws.amazon.com/AmazonCloudWatch/latest/DeveloperGuide/](https://docs.aws.amazon.com/AmazonCloudWatch/latest/DeveloperGuide/). ### CloudWatch Röntgenmetriken Der `ServiceMetrics/SDK`-Namespace enthält die folgenden Metriken. | Metrik | Verfügbare Statistiken | Description | Einheiten | | --- | --- | --- | --- | | `Latency` | Durchschnitt, Minimum, Maximum, Anzahl | Die Differenz zwischen der Start- und Endzeit Durchschnitt, Minimum und Maximum beschreiben Betriebslatenz. „Anzahl“ beschreibt die Anzahl der Aufrufe. | Millisekunden | | `ErrorRate` | Durchschnitt, Summe | Die Rate der Anforderungen, die mit dem Statuscode „`4xx Client Error`“ fehlgeschlagen sind, was zu einem Fehler führt. | Prozent | | `FaultRate` | Durchschnitt, Summe | Die Rate der Traces, die mit dem Statuscode „`5xx Server Error`“ fehlgeschlagen sind, was zu einem Fehler führte. | Prozent | | `ThrottleRate` | Durchschnitt, Summe | Die Rate der abgelehnten Traces, die einen `429`-Statuscode zurückgeben. Dies ist eine Teilmenge der `ErrorRate`-Metrik. | Prozent | | `OkRate` | Durchschnitt, Summe | Die Rate der verfolgten Anforderungen, die zu einem `OK`-Statuscode führen. | Prozent | ### CloudWatch Röntgenabmessungen Verwenden Sie die Dimensionen in der folgenden Tabelle, um die für Ihre Java Anwendungen mit Röntgeninstrumenten zurückgegebenen Messwerte zu verfeinern. | Dimension | Description | | --- | --- | | `ServiceType` | Der Service-Typ, z. B. `AWS::EC2::Instance` oder `NONE`, falls nicht bekannt. | | `ServiceName` | Der kanonische Name für den Service. | ### CloudWatch X-Ray-Metriken aktivieren Gehen Sie wie folgt vor, um Trace-Metriken in Ihrer instrumentierten Java Anwendung zu aktivieren. **So konfigurieren Sie Trace-Metriken** 1. Fügen Sie das `aws-xray-recorder-sdk-metrics` Paket als Apache Maven Abhängigkeit hinzu. Weitere Informationen finden Sie unter [X-Ray SDK for Java Java-Submodule](#xray-sdk-java-submodules). 1. Aktivieren Sie ein neues `MetricsSegmentListener()` als Teil des globalen Recorder-Builds. **Example src/com/myapp/web/Startup.java** ``` import com.amazonaws.xray.AWSXRay; import com.amazonaws.xray.AWSXRayRecorderBuilder; import com.amazonaws.xray.plugins.EC2Plugin; import com.amazonaws.xray.plugins.ElasticBeanstalkPlugin; import com.amazonaws.xray.strategy.sampling.LocalizedSamplingStrategy; @Configuration public class WebConfig { ... static { AWSXRayRecorderBuilder builder = AWSXRayRecorderBuilder .standard() .withPlugin(new EC2Plugin()) .withPlugin(new ElasticBeanstalkPlugin()) .withSegmentListener(new MetricsSegmentListener()); URL ruleFile = WebConfig.class.getResource("/sampling-rules.json"); builder.withSamplingStrategy(new LocalizedSamplingStrategy(ruleFile)); AWSXRay.setGlobalRecorder(builder.build()); } } ``` 1. Stellen Sie den CloudWatch Agenten bereit, um Metriken mithilfe von Amazon Elastic Compute Cloud (Amazon EC2), Amazon Elastic Container Service (Amazon ECS) oder Amazon Elastic Kubernetes Service (Amazon EKS) zu sammeln: + Informationen zur Konfiguration von Amazon EC2 finden Sie unter [Installation des CloudWatch Agenten](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/install-CloudWatch-Agent-on-EC2-Instance.html). + Informationen zur Konfiguration von Amazon ECS finden Sie unter [Überwachen von Amazon ECS-Containern mithilfe von Container Insights](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/cloudwatch-container-insights.html). + Informationen zur Konfiguration von Amazon EKS finden [Sie unter Installieren des CloudWatch Agenten mithilfe des Amazon CloudWatch Observability EKS-Add-ons](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/install-CloudWatch-Observability-EKS-addon.html). 1. Konfigurieren Sie das SDK für die Kommunikation mit dem CloudWatch Agenten. Standardmäßig kommuniziert das SDK mit dem CloudWatch Agenten über die Adresse`127.0.0.1`. Sie können alternative Adressen konfigurieren, indem Sie die Umgebungsvariable oder die Java-Eigenschaft auf `address:port` festlegen. **Example Umgebungsvariable** ``` AWS_XRAY_METRICS_DAEMON_ADDRESS=address:port ``` **Example Java-Eigenschaft** ``` com.amazonaws.xray.metrics.daemonAddress=address:port ``` **So überprüfen Sie die Konfiguration** 1. Melden Sie sich bei der an AWS-Managementkonsole und öffnen Sie die CloudWatch Konsole unter [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/). 1. Öffnen Sie die Registerkarte **Metriken**, um den Zustrom Ihrer Metriken zu überwachen. 1. (Optional) Öffnen Sie in der CloudWatch Konsole auf der Registerkarte **Protokolle** die `ServiceMetricsSDK` Protokollgruppe. Suchen Sie nach einem Protokolldatenstrom, der den Host-Metriken entspricht, und bestätigen Sie die Protokollmeldungen. # Übermitteln von Segmentkontext zwischen Threads in einer Multithread-Anwendung **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). Beim Erstellen eines neuen Threads in Ihrer Anwendung behält `AWSXRayRecorder` eine Referenz zur aktuellen Segment- oder Untersegment-[Entity](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/entities/Entity.html) nicht bei. Wenn Sie im neuen Thread einen instrumentierten Client verwenden, versucht das SDK, in ein Segment zu schreiben, das nicht existiert, was zu einem führt. [SegmentNotFoundException](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/exceptions/SegmentNotFoundException.html) Um zu vermeiden, dass während der Entwicklung Ausnahmen ausgelöst werden, können Sie den Rekorder so konfigurieren [ContextMissingStrategy](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/strategy/ContextMissingStrategy.html), dass er stattdessen einen Fehler protokollieren soll. Sie können die Strategie im Code mit einer [SetContextMissingStrategy](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/AWSXRayRecorder.html#setContextMissingStrategy(com.amazonaws.xray.strategy.ContextMissingStrategy))[Umgebungsvariablen](xray-sdk-java-configuration.md#xray-sdk-java-configuration-envvars) oder einer [Systemeigenschaft](xray-sdk-java-configuration.md#xray-sdk-java-configuration-sysprops) konfigurieren oder entsprechende Optionen konfigurieren. Eine Möglichkeit zur Behebung des Fehlers ist die Verwendung eines neuen Segments, indem Sie [beginSegment](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/AWSXRayRecorder.html#beginSegment(java.lang.String)) aufrufen, wenn Sie den Thread starten, und [endSegment](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/AWSXRayRecorder.html#endSegment--), wenn Sie ihn schließen. Dies funktioniert, wenn Sie Code instrumentieren, der nicht als Reaktion auf eine HTTP-Anforderung ausgeführt wird, z. B. Code, der beim Starten Ihrer Anwendung ausgeführt wird. Wenn Sie mehrere Threads zur Verarbeitung eingehender Anfragen verwenden, können Sie das aktuelle Segment oder Untersegment an den neuen Thread übergeben und für die globale Aufzeichnung bereitstellen. Auf diese Weise wird sichergestellt, dass die im neuen Thread aufgezeichneten Informationen mit demselben Segment verknüpft werden wie die übrigen zu dieser Anfrage aufgezeichneten Informationen. Sobald das Segment im neuen Thread verfügbar ist, können Sie jedes Runnable mit Zugriff auf den Kontext dieses Segments mithilfe der `segment.run(() -> { ... })` Methode ausführen. Ein Beispiel finden Sie unter [Verwenden instrumentierter Clients in Auftragnehmer-Threads](scorekeep-workerthreads.md). ## X-Ray mit asynchroner Programmierung verwenden Das X-Ray SDK for Java kann in asynchronen Java-Programmen mit [SegmentContextExecutors](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/contexts/SegmentContextExecutors.html)verwendet werden. Das SegmentContextExecutor implementiert das Executor-Interface, was bedeutet, dass es an alle asynchronen Operationen von a übergeben werden kann. [CompletableFuture](https://docs.oracle.com/javase/8/docs/api/java/util/concurrent/CompletableFuture.html) Dadurch wird sichergestellt, dass alle asynchronen Operationen mit dem richtigen Segment in ihrem Kontext ausgeführt werden. **Example Beispiel App.java: Übergabe an SegmentContextExecutor CompletableFuture** ``` DynamoDbAsyncClient client = DynamoDbAsyncClient.create(); AWSXRay.beginSegment(); // ... client.getItem(request).thenComposeAsync(response -> { // If we did not provide the segment context executor, this request would not be traced correctly. return client.getItem(request2); }, SegmentContextExecutors.newSegmentContextExecutor()); ``` # AOP mit Spring und dem X-Ray SDK for Java **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). In diesem Thema wird beschrieben, wie Sie das X-Ray SDK und das Spring Framework verwenden, um Ihre Anwendung zu instrumentieren, ohne ihre Kernlogik zu ändern. Das bedeutet, dass es jetzt eine nichtinvasive Methode zur Instrumentierung Ihrer Anwendungen gibt, die remote ausgeführt werden. AWS **So aktivieren Sie AOP in Spring** 1. [Konfigurieren von Spring](#xray-sdk-java-aop-spring-configuration) 1. [Fügen Sie Ihrer Anwendung einen Tracing-Filter hinzu](#xray-sdk-java-aop-filters-spring) 1. [Kommentieren Ihres Codes oder implementieren einer Schnittstelle](#xray-sdk-java-aop-annotate-or-implement) 1. [Aktivieren von X-Ray in Ihrer Anwendung](#xray-sdk-java-aop-activate-xray) ## Konfigurieren von Spring Sie können Maven oder Gradle verwenden, um Spring zu konfigurieren, um AOP für die Instrumentierung Ihrer Anwendung verwenden zu können. Wenn Sie Ihre Anwendung mit Maven erstellen, fügen Sie die folgende Abhängigkeit in Ihrer `pom.xml`-Datei hinzu. ``` com.amazonaws aws-xray-recorder-sdk-spring 2.11.0 ``` Für Gradle fügen Sie die folgende Abhängigkeit in Ihre `build.gradle`-Datei ein. ``` compile 'com.amazonaws:aws-xray-recorder-sdk-spring:2.11.0' ``` ## Spring Boot konfigurieren Wenn Sie Spring Boot verwenden, fügen Sie zusätzlich zu der im vorherigen Abschnitt beschriebenen Spring-Abhängigkeit die folgende Abhängigkeit hinzu, sofern sie nicht bereits in Ihrem Klassenpfad enthalten ist. Maven: ``` org.springframework.boot spring-boot-starter-aop 2.5.2 ``` Gradle: ``` compile 'org.springframework.boot:spring-boot-starter-aop:2.5.2' ``` ## Hinzufügen eines Tracing-Filters zu Ihrer Anwendung Fügen Sie Ihrer `WebConfig` Klasse eine `Filter` hinzu. Übermitteln Sie den Segmentnamen als Zeichenfolge an den [https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/javax/servlet/AWSXRayServletFilter.html](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/javax/servlet/AWSXRayServletFilter.html)-Konstruktor. Weitere Informationen zur Verfolgung von Filtern und zur Instrumentierung eingehender Anfragen finden Sie unter. [Nachverfolgung eingehender Anfragen mit dem X-Ray SDK for Java](xray-sdk-java-filters.md) **Example src/main/java/myapp/WebConfig.java — Frühling** ``` package myapp; import org.springframework.context.annotation.Configuration; import org.springframework.context.annotation.Bean; import javax.servlet.Filter; import [com.amazonaws.xray.javax.servlet.AWSXRayServletFilter](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/javax/servlet/AWSXRayServletFilter.html); @Configuration public class WebConfig { @Bean public Filter TracingFilter() { return new AWSXRayServletFilter("Scorekeep"); } } ``` ## Jakarta-Unterstützung Spring 6 verwendet [Jakarta](https://spring.io/blog/2022/11/16/spring-framework-6-0-goes-ga) anstelle von Javax für seine Enterprise Edition. Um diesen neuen Namespace zu unterstützen, hat X-Ray einen parallel Satz von Klassen erstellt, die in ihrem eigenen Jakarta-Namespace leben. Ersetzen Sie für die Filterklassen durch. `javax` `jakarta` Wenn Sie eine Segmentbenennungsstrategie konfigurieren, fügen Sie `jakarta` vor der Benennungsstrategie den Klassennamen hinzu, wie im folgenden Beispiel: ``` package myapp; import org.springframework.context.annotation.Configuration; import org.springframework.context.annotation.Bean; import jakarta.servlet.Filter; import com.amazonaws.xray.jakarta.servlet.AWSXRayServletFilter; import com.amazonaws.xray.strategy.jakarta.SegmentNamingStrategy; @Configuration public class WebConfig { @Bean public Filter TracingFilter() { return new AWSXRayServletFilter(SegmentNamingStrategy.dynamic("Scorekeep")); } } ``` ## Kommentieren Ihres Codes oder Implementieren einer Schnittstelle Ihre Klassen müssen entweder mit der `@XRayEnabled` Anmerkung versehen sein oder die `XRayTraced` Schnittstelle implementieren. Damit wird das AOP-System angewiesen, die Funktionen der betroffenen Klasse für die X-Ray-Instrumentierung zu kapseln. ## X-Ray in Ihrer Anwendung aktivieren Um X-Ray Tracing in Ihrer Anwendung zu aktivieren, muss Ihr Code die abstrakte Klasse erweitern, `BaseAbstractXRayInterceptor` indem er die folgenden Methoden überschreibt. + `generateMetadata`— Diese Funktion ermöglicht die Anpassung der Metadaten, die an den Trace der aktuellen Funktion angehängt sind. Standardmäßig wird der Klassenname der ausgeführten Funktion in den Metadaten aufgezeichnet. Sie können weitere Daten hinzufügen, wenn Sie zusätzliche Informationen benötigen. + `xrayEnabledClasses`— Diese Funktion ist leer und sollte es auch bleiben. Sie dient als Host für ein Pointcut, das den Interceptor anweist, welche Methoden gekapselt werden sollen. Definieren Sie das Pointcut, indem Sie angeben, welche der Klassen mit `@XRayEnabled` kommentiert sind, um ein Tracing durchzuführen. Die folgende pointcut-Anweisung weist den Interceptor an, alle Controller-Beans einzukapseln, die mit dem Kommentar `@XRayEnabled` gekennzeichnet sind. ``` @Pointcut(“@within(com.amazonaws.xray.spring.aop.XRayEnabled) && bean(*Controller)”) ``` Wenn Ihr Projekt Spring Data JPA verwendet, sollten Sie eine Erweiterung von `AbstractXRayInterceptor` anstelle von in Betracht ziehen. `BaseAbstractXRayInterceptor` ## Beispiel Der folgende Code erweitert die abstrakte Klasse`BaseAbstractXRayInterceptor`. ``` @Aspect @Component public class XRayInspector extends BaseAbstractXRayInterceptor { @Override protected Map> generateMetadata(ProceedingJoinPoint proceedingJoinPoint, Subsegment subsegment) throws Exception { return super.generateMetadata(proceedingJoinPoint, subsegment); } @Override @Pointcut("@within(com.amazonaws.xray.spring.aop.XRayEnabled) && bean(*Controller)") public void xrayEnabledClasses() {} } ``` Der folgenden Code ist eine Klasse, die von X-Ray instrumentiert wird. ``` @Service @XRayEnabled public class MyServiceImpl implements MyService { private final MyEntityRepository myEntityRepository; @Autowired public MyServiceImpl(MyEntityRepository myEntityRepository) { this.myEntityRepository = myEntityRepository; } @Transactional(readOnly = true) public List getMyEntities(){ try(Stream entityStream = this.myEntityRepository.streamAll()){ return entityStream.sorted().collect(Collectors.toList()); } } } ``` Wenn Sie Ihre Anwendung ordnungsgemäß konfiguriert haben, sollten Sie den vollständigen Aufruf-Stack der Anwendung sehen, vom Controller bis zu den Service-Aufrufe, wie im folgenden Screenshot der Konsole gezeigt. ![\[Timeline showing API call duration and breakdown of server operations for metering service.\]](http://docs.aws.amazon.com/de_de/xray/latest/devguide/images/aop-spring-console.png)