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 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.