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 Musteranwendung **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). Die AWS [eb-java-scorekeep](https://github.com/awslabs/eb-java-scorekeep/tree/xray)X-Ray-Beispiel-App, verfügbar auf GitHub, zeigt die Verwendung des AWS X-Ray-SDK zur Instrumentierung eingehender HTTP-Aufrufe, DynamoDB-SDK-Clients und HTTP-Clients. Die Beispiel-App wird verwendet, CloudFormation um DynamoDB-Tabellen zu erstellen, Java-Code auf einer Instanz zu kompilieren und den X-Ray-Daemon ohne zusätzliche Konfiguration auszuführen. Sehen Sie sich das [Scorekeep-Tutorial](scorekeep-tutorial.md) an, um mit der Installation und Verwendung einer instrumentierten Beispielanwendung zu beginnen. Verwenden Sie dazu das oder das. AWS-Managementkonsole AWS CLI ![\[Scorekeep verwendet das AWS X-Ray-SDK zur Instrumentierung eingehender HTTP-Aufrufe, DynamoDB-SDK-Clients und HTTP-Clients\]](http://docs.aws.amazon.com/de_de/xray/latest/devguide/images/scorekeep-flow.png) Das Beispiel umfasst eine Front-End-Web-App, die API, die sie aufruft, und die DynamoDB-Tabellen, die sie zum Speichern von Daten verwendet. Die grundlegende Instrumentierung mit [Filtern](xray-sdk-java-filters.md), [Plugins](xray-sdk-java-configuration.md) und [instrumentierten AWS SDK-Clients](xray-sdk-java-awssdkclients.md) wird im Zweig des Projekts gezeigt. `xray-gettingstarted` Dies ist die Verzweigung, die Sie im [Tutorial "Erste Schritte"](scorekeep-tutorial.md) bereitstellen. Da diese Verzweigung nur die Grundlagen beinhaltet, können Sie einen diff-Vorgang mit der `master`-Verzweigung durchführen, um schnell die Grundlagen zu erfassen. ![\[Service map showing client interaction with Scorekeep container and related AWS-Services.\]](http://docs.aws.amazon.com/de_de/xray/latest/devguide/images/scorekeep-gettingstarted-servicemap-before-ECS.png) Die Beispielanwendung veranschaulicht die grundlegende Instrumentierung in folgenden Dateien: + **HTTP-Anforderungsfilter** — [https://github.com/awslabs/eb-java-scorekeep/tree/xray/src/main/java/scorekeep/WebConfig.java](https://github.com/awslabs/eb-java-scorekeep/tree/xray/src/main/java/scorekeep/WebConfig.java) + **AWS Instrumentierung des SDK-Clients** — [https://github.com/awslabs/eb-java-scorekeep/tree/xray/build.gradle](https://github.com/awslabs/eb-java-scorekeep/tree/xray/build.gradle) Der `xray` Zweig der Anwendung umfasst die Verwendung von [Anmerkungen [HTTPClient](xray-sdk-java-httpclients.md)](xray-sdk-java-segment.md), [SQL-Abfragen](xray-sdk-java-sqlclients.md), [benutzerdefinierten Untersegmenten](xray-sdk-java-subsegments.md), einer instrumentierten [AWS Lambda](xray-services-lambda.md)Funktion sowie instrumentiertem [Initialisierungscode und Skripten](scorekeep-startup.md). Um die Benutzeranmeldung und die AWS SDK für JavaScript Nutzung im Browser zu unterstützen, fügt die `xray-cognito` Filiale Amazon Cognito hinzu, um die Benutzerauthentifizierung und -autorisierung zu unterstützen. Mit den von Amazon Cognito abgerufenen Anmeldeinformationen sendet die Web-App auch Trace-Daten an X-Ray, um Anforderungsinformationen aus Kundensicht aufzuzeichnen. Der Browser-Client erscheint als eigener Knoten auf der Trace-Map und zeichnet zusätzliche Informationen auf, darunter die URL der Seite, die der Benutzer gerade betrachtet, und die Benutzer-ID. Schließlich fügt der `xray-worker` Branch eine instrumentierte Python-Lambda-Funktion hinzu, die unabhängig ausgeführt wird und Elemente aus einer Amazon SQS SQS-Warteschlange verarbeitet. Scorekeep fügt ein Element zur Warteschlange hinzu, wenn ein Spiel endet. Der Lambda-Worker, ausgelöst durch CloudWatch Ereignisse, ruft alle paar Minuten Elemente aus der Warteschlange ab und verarbeitet sie, um Spielaufzeichnungen zur Analyse in Amazon S3 zu speichern. **Topics** + [Erste Schritte mit der Scorekeep-Beispielanwendung](scorekeep-tutorial.md) + [Manuelles Instrumentieren von AWS SDK-Clients](scorekeep-sdkclients.md) + [Erstellen zusätzlicher Untersegmente](scorekeep-subsegments.md) + [Aufzeichnung von Anmerkungen, Metadaten und Benutzern IDs](scorekeep-annotations.md) + [Instrumentieren von ausgehenden HTTP-Aufrufen](scorekeep-httpclient.md) + [Instrumentieren von Aufrufen einer PostgreSQL-Datenbank](scorekeep-postgresql.md) + [Instrumentierungsfunktionen AWS Lambda](scorekeep-lambda.md) + [Instrumentieren von Startup-Code](scorekeep-startup.md) + [Instrumentieren von Skripten](scorekeep-scripts.md) + [Instrumentieren eines Web-App-Clients](scorekeep-client.md) + [Verwenden instrumentierter Clients in Auftragnehmer-Threads](scorekeep-workerthreads.md) # Erste Schritte mit der Scorekeep-Beispielanwendung **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 Tutorial wird der `xray-gettingstarted` Zweig der [Scorekeep-Beispielanwendung](xray-scorekeep.md) verwendet CloudFormation , mit dem die Ressourcen erstellt und konfiguriert werden, mit denen die Beispielanwendung und der X-Ray-Daemon auf Amazon ECS ausgeführt werden. Die Anwendung verwendet das Spring-Framework, um eine JSON-Web-API AWS SDK für Java zu implementieren und Daten in Amazon DynamoDB zu speichern. Ein Servlet-Filter in der Anwendung instrumentiert alle eingehenden Anfragen, die von der Anwendung bedient werden, und ein Anforderungshandler auf dem AWS SDK-Client instrumentiert Downstream-Aufrufe an DynamoDB. Sie können diesem Tutorial entweder mit dem oder dem AWS-Managementkonsole folgen. AWS CLI **Topics** + [Voraussetzungen](#xray-gettingstarted-prereqs) + [Installieren Sie die Scorekeep-Anwendung mit CloudFormation](#xray-gettingstarted-deploy) + [Generieren von Ablaufverfolgungsdaten](#xray-gettingstarted-generate-traces) + [Sehen Sie sich die Trace-Map im AWS-Managementkonsole](#xray-gettingstarted-console) + [Konfigurieren von Amazon-SNS-Benachrichtigungen](#xray-gettingstarted-notifications) + [Erkunden der Beispielanwendung](#xray-gettingstarted-sample) + [Optional: Richtlinie für geringste Rechte](#xray-gettingstarted-security) + [Bereinigen](#xray-gettingstarted-cleanup) + [Nächste Schritte](#xray-gettingstarted-nextsteps) ## Voraussetzungen In diesem Tutorial werden CloudFormation die Ressourcen erstellt und konfiguriert, auf denen die Beispielanwendung und der X-Ray-Daemon ausgeführt werden. Für die Installation und Ausführung des Tutorials sind die folgenden Voraussetzungen erforderlich: 1. Wenn Sie einen IAM-Benutzer mit eingeschränkten Rechten verwenden, fügen Sie die folgenden Benutzerrichtlinien in der [IAM-Konsole](https://console.aws.amazon.com/iam) hinzu: + `AWSCloudFormationFullAccess`— für den Zugriff und die Nutzung CloudFormation + `AmazonS3FullAccess`— um eine Vorlagendatei hochzuladen, CloudFormation um die AWS-Managementkonsole + `IAMFullAccess`— um die Amazon ECS- und Amazon EC2 EC2-Instance-Rollen zu erstellen + `AmazonEC2FullAccess`— um die Amazon EC2 EC2-Ressourcen zu erstellen + `AmazonDynamoDBFullAccess`— um die DynamoDB-Tabellen zu erstellen + `AmazonECS_FullAccess`— um Amazon ECS-Ressourcen zu erstellen + `AmazonSNSFullAccess`— um das Amazon SNS SNS-Thema zu erstellen + `AWSXrayReadOnlyAccess`— für die Erlaubnis, die Trace-Map und die Traces in der X-Ray-Konsole anzusehen 1. Um das Tutorial mit dem auszuführen AWS CLI, [installieren Sie die CLI-Version](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) 2.7.9 oder höher und [konfigurieren Sie die CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-quickstart.html#cli-configure-quickstart-config) mit dem Benutzer aus dem vorherigen Schritt. Stellen Sie sicher, dass die Region konfiguriert ist, wenn Sie das AWS CLI mit dem Benutzer konfigurieren. Wenn eine Region nicht konfiguriert ist, müssen Sie sie `--region AWS-REGION` an jeden CLI-Befehl anhängen. 1. Stellen Sie sicher, dass [Git](https://github.com/git-guides/install-git) installiert ist, um das Beispielanwendungs-Repo zu klonen. 1. Verwenden Sie das folgende Codebeispiel, um den `xray-gettingstarted` Zweig des Scorekeep-Repositorys zu klonen: ``` git clone https://github.com/aws-samples/eb-java-scorekeep.git xray-scorekeep -b xray-gettingstarted ``` ## Installieren Sie die Scorekeep-Anwendung mit CloudFormation ------ #### [ AWS-Managementkonsole ] **Installieren Sie die Beispielanwendung mit dem AWS-Managementkonsole** 1. Öffnen Sie die [CloudFormation-Konsole](https://console.aws.amazon.com/cloudformation/). 1. Wählen Sie **Stack erstellen** und dann im Drop-down-Menü die Option **Mit neuen Ressourcen** aus. 1. Wählen Sie im Abschnitt **Specify template (Vorlage angeben)** die Option **Upload a template file (Vorlagendatei hochladen)** aus. 1. Wähle „**Datei auswählen**“, navigiere zu dem `xray-scorekeep/cloudformation` Ordner, der beim Klonen des Git-Repositorys erstellt wurde, und wähle die `cf-resources.yaml` Datei aus. 1. Wählen Sie **Next** (Weiter), um fortzufahren. 1. Geben Sie den Text `scorekeep` in das Textfeld **Stack-Name** ein und wählen Sie dann unten auf der Seite **Weiter** aus, um fortzufahren. Beachten Sie, dass im Rest dieses Tutorials davon ausgegangen wird, dass der Stack benannt `scorekeep` ist. 1. Scrollen Sie zum Ende der Seite „**Stack-Optionen konfigurieren**“ und wählen Sie **Weiter**, um fortzufahren. 1. **Scrollen Sie zum Ende der **Überprüfungsseite**, aktivieren Sie das Kontrollkästchen zur Bestätigung, dass CloudFormation möglicherweise IAM-Ressourcen mit benutzerdefinierten Namen erstellt werden, und wählen Sie Stack erstellen aus.** 1. Der CloudFormation Stack wird jetzt erstellt. Der Stack-Status wird `CREATE_IN_PROGRESS` etwa fünf Minuten lang angezeigt, bevor er zu wechselt`CREATE_COMPLETE`. Der Status wird regelmäßig aktualisiert, oder Sie können die Seite aktualisieren. ------ #### [ AWS CLI ] **Installieren Sie die Beispielanwendung mit dem AWS CLI** 1. Navigieren Sie zu dem `cloudformation` Ordner des `xray-scorekeep` Repositorys, den Sie zuvor im Tutorial geklont haben: ``` cd xray-scorekeep/cloudformation/ ``` 1. Geben Sie den folgenden AWS CLI Befehl ein, um den CloudFormation Stack zu erstellen: ``` aws cloudformation create-stack --stack-name scorekeep --capabilities "CAPABILITY_NAMED_IAM" --template-body file://cf-resources.yaml ``` 1. Warten Sie`CREATE_COMPLETE`, bis der CloudFormation Stack-Status lautet. Dies dauert etwa fünf Minuten. Verwenden Sie den folgenden AWS CLI Befehl, um den Status zu überprüfen: ``` aws cloudformation describe-stacks --stack-name scorekeep --query "Stacks[0].StackStatus" ``` ------ ## Generieren von Ablaufverfolgungsdaten Die Beispielanwendung enthält eine Front-End-Webanwendung. Verwenden Sie die Web-App, um Traffic zur API zu generieren und Trace-Daten an X-Ray zu senden. Rufen Sie zunächst die URL der Web-App mit dem AWS-Managementkonsole oder dem ab AWS CLI: ------ #### [ AWS-Managementkonsole ] **Suchen Sie die Anwendungs-URL mit dem AWS-Managementkonsole** 1. Öffnen Sie die [CloudFormation-Konsole](https://console.aws.amazon.com/cloudformation/). 1. Wählen Sie den `scorekeep` Stapel aus der Liste aus. 1. Wählen Sie auf der `scorekeep` Stack-Seite den Tab **Outputs** und anschließend den `LoadBalancerUrl` URL-Link, um die Webanwendung zu öffnen. ------ #### [ AWS CLI ] **Suchen Sie die Anwendungs-URL mithilfe des AWS CLI** 1. Verwenden Sie den folgenden Befehl, um die URL der Webanwendung anzuzeigen: ``` aws cloudformation describe-stacks --stack-name scorekeep --query "Stacks[0].Outputs[0].OutputValue" ``` 1. Kopieren Sie diese URL und öffnen Sie sie in einem Browser, um die Scorekeep-Webanwendung anzuzeigen. ------ **Verwenden Sie die Webanwendung, um Trace-Daten zu generieren** 1. Wählen Sie **Create** aus, um einen Benutzer und eine Sitzung zu erstellen. 1. Geben Sie einen **Game Name** ein, legen Sie die **Rules** auf **Tic Tac Toe** fest und wählen Sie anschließend **Create** aus, um ein Spiel zu erstellen. 1. Wählen Sie **Play**, um das Spiel zu starten. 1. Wählen Sie eine Kachel, um einen Spielzug zu machen, und ändern Sie den Spielestatus. Jeder dieser Schritte generiert HTTP-Anfragen an die API und Downstream-Aufrufe an DynamoDB, um Benutzer-, Sitzungs-, Spiel-, Bewegungs- und Statusdaten zu lesen und zu schreiben. ## Sehen Sie sich die Trace-Map im AWS-Managementkonsole Sie können die Trace-Map und die von der Beispielanwendung generierten Traces im X-Ray und in den CloudWatch Konsolen sehen. ------ #### [ X-Ray console ] **Verwenden Sie die X-Ray-Konsole** 1. Öffnen Sie die Trace-Map-Seite der [X-Ray-Konsole](https://console.aws.amazon.com/xray/home#/service-map). 1. Die Konsole zeigt eine Darstellung des Service-Graphen, den X-Ray aus den von der Anwendung gesendeten Trace-Daten generiert. Achten Sie darauf, den Zeitraum der Trace-Map bei Bedarf anzupassen, um sicherzustellen, dass alle Traces seit dem ersten Start der Webanwendung angezeigt werden. ![\[Zeitraum der Röntgen-Trace-Map\]](http://docs.aws.amazon.com/de_de/xray/latest/devguide/images/xray-console-time-period-15-minutes.png) Die Trace-Map zeigt den Web-App-Client, die in Amazon ECS ausgeführte API und jede DynamoDB-Tabelle, die die Anwendung verwendet. Jede Anforderung an die Anwendung, bis zu einer konfigurierbaren Höchstanzahl von Anforderungen pro Sekunde, wird verfolgt, und zwar wie sie auf die API trifft, Anforderungen an nachgelagerte Services generiert und abgeschlossen wird. Sie können jeden Knoten in der Service-Grafik wählen, um Ablaufverfolgungen für Anforderungen anzusehen, die Datenverkehr zu diesem Knoten generiert haben. Derzeit ist der Amazon SNS SNS-Knoten gelb. Zeigen Sie die Details an, um herauszufinden, warum. ![\[Trace-Map-Seite für die X-Ray-Konsole\]](http://docs.aws.amazon.com/de_de/xray/latest/devguide/images/scorekeep-gettingstarted-servicemap-before-ECS.png) **So finden Sie die Ursache des Fehlers** 1. Wählen Sie den Knoten mit dem Namen **SNS**. Das Fenster mit den Knotendetails wird angezeigt. 1. Wählen Sie **View traces (Ablaufverfolgungen anzeigen)**, um auf den Bildschirm **Trace overview (Ablaufverfolgungsübersicht)** zuzugreifen. 1. Wählen Sie die Nachverfolgung aus der **Trace list**. Diese Ablaufverfolgung verfügt über keine Methode oder URL, da sie während des Startups und nicht als Reaktion auf eine eingehende Anforderung aufgezeichnet wurde. ![\[Wählen einer Ablaufverfolgung aus der Ablaufverfolgungsliste\]](http://docs.aws.amazon.com/de_de/xray/latest/devguide/images/scorekeep-gettingstarted-tracelist-sns.png) 1. Wählen Sie das Fehlerstatussymbol im Amazon SNS SNS-Segment unten auf der Seite, um die Seite **Ausnahmen** für das SNS-Subsegment zu öffnen. ![\[Wählen Sie das Fehlerstatussymbol, um die Seite Ausnahmen für das Amazon SNS SNS-Subsegment zu öffnen.\]](http://docs.aws.amazon.com/de_de/xray/latest/devguide/images/scorekeep-gettingstarted-timeline-sns-ecs.png) 1. Das X-Ray SDK erfasst automatisch Ausnahmen, die von instrumentierten AWS SDK-Clients ausgelöst werden, und zeichnet den Stack-Trace auf. ![\[Registerkarte "Exceptions (Ausnahmen)" mit erfassten Ausnahmen und aufgezeichneter Stack-Ablaufverfolgung\]](http://docs.aws.amazon.com/de_de/xray/latest/devguide/images/scorekeep-gettingstarted-exception.png) ------ #### [ CloudWatch console ] **Verwenden Sie die Konsole CloudWatch** 1. Öffnen Sie die [X-Ray-Trace-Map-Seite](https://console.aws.amazon.com/cloudwatch/home#xray:service-map/map) der CloudWatch Konsole. 1. Die Konsole zeigt eine Darstellung des Service-Graphen, den X-Ray aus den von der Anwendung gesendeten Trace-Daten generiert. Achten Sie darauf, den Zeitraum der Trace-Map bei Bedarf anzupassen, um sicherzustellen, dass alle Traces seit dem ersten Start der Webanwendung angezeigt werden. ![\[CloudWatch Zeitraum der Trace-Map\]](http://docs.aws.amazon.com/de_de/xray/latest/devguide/images/cw-console-service-map-time-period-15-minutes.png) Die Trace-Map zeigt den Web-App-Client, die in Amazon EC2 ausgeführte API und jede DynamoDB-Tabelle, die die Anwendung verwendet. Jede Anforderung an die Anwendung, bis zu einer konfigurierbaren Höchstanzahl von Anforderungen pro Sekunde, wird verfolgt, und zwar wie sie auf die API trifft, Anforderungen an nachgelagerte Services generiert und abgeschlossen wird. Sie können jeden Knoten in der Service-Grafik wählen, um Ablaufverfolgungen für Anforderungen anzusehen, die Datenverkehr zu diesem Knoten generiert haben. Derzeit ist der Amazon SNS SNS-Knoten orange. Zeigen Sie die Details an, um herauszufinden, warum. ![\[Trace-Map-Seite für die X-Ray-Konsole\]](http://docs.aws.amazon.com/de_de/xray/latest/devguide/images/scorekeep-gettingstarted-cw-servicemap-before-ECS.png) **So finden Sie die Ursache des Fehlers** 1. Wählen Sie den Knoten mit dem Namen **SNS**. Der Bereich mit den SNS-Knotendetails wird unter der Karte angezeigt. 1. Wählen Sie „**Traces anzeigen**“, um die Seite „**Traces“ aufzurufen**. 1. Fügen Sie das Ende der Seite hinzu und wählen Sie den Trace aus der **Traces-Liste** aus. Diese Ablaufverfolgung verfügt über keine Methode oder URL, da sie während des Startups und nicht als Reaktion auf eine eingehende Anforderung aufgezeichnet wurde. ![\[Wählen einer Ablaufverfolgung aus der Ablaufverfolgungsliste\]](http://docs.aws.amazon.com/de_de/xray/latest/devguide/images/scorekeep-gettingstarted-cw-tracelist-sns-ecs.png) 1. Wählen Sie das Amazon SNS SNS-Untersegment unten in der Segment-Timeline und wählen Sie den Tab **Ausnahmen** für das SNS-Untersegment, um die Ausnahmedetails anzuzeigen. ![\[Die Registerkarte „Ausnahmen“ für das Amazon SNS SNS-Untersegment anzeigen\]](http://docs.aws.amazon.com/de_de/xray/latest/devguide/images/scorekeep-gettingstarted-cw-timeline-sns-ecs.png) ------ Die Ursache gibt an, dass die E-Mail-Adresse, die in einem Aufruf von `createSubscription` in der Klasse `WebConfig` angegeben wurde, ungültig ist. Im nächsten Abschnitt werden wir das beheben. ## Konfigurieren von Amazon-SNS-Benachrichtigungen Scorekeep verwendet Amazon SNS, um Benachrichtigungen zu senden, wenn Benutzer ein Spiel abgeschlossen haben. Wenn die Anwendung gestartet wird, versucht sie, ein Abonnement für eine E-Mail-Adresse zu erstellen, die in einem CloudFormation Stack-Parameter definiert ist. Dieser Anruf schlägt derzeit fehl. Konfigurieren Sie eine Benachrichtigungs-E-Mail, um Benachrichtigungen zu aktivieren und die in der Trace-Map hervorgehobenen Fehler zu beheben. ------ #### [ AWS-Managementkonsole ] **So konfigurieren Sie Amazon SNS SNS-Benachrichtigungen mit dem AWS-Managementkonsole** 1. Öffnen Sie die [CloudFormation-Konsole](https://console.aws.amazon.com/cloudformation/). 1. Wählen Sie das Optionsfeld neben dem `scorekeep` Stack-Namen in der Liste und wählen Sie dann **Aktualisieren**. 1. Vergewissern Sie sich, dass **Aktuelle Vorlage verwenden** ausgewählt ist, und klicken Sie dann auf der Seite **Stack aktualisieren** auf **Weiter**. 1. Suchen Sie den **E-Mail-Parameter** in der Liste und ersetzen Sie den Standardwert durch eine gültige E-Mail-Adresse. ![\[E-Mail-Konfiguration aktualisieren\]](http://docs.aws.amazon.com/de_de/xray/latest/devguide/images/scorekeep-cf-email-update.png) 1. Scrollen Sie ans Seitenende und wählen Sie **Next** (Weiter). 1. **Scrollen Sie zum Ende der **Überprüfungsseite**, aktivieren Sie das Kontrollkästchen zur Bestätigung, dass CloudFormation möglicherweise IAM-Ressourcen mit benutzerdefinierten Namen erstellt werden, und wählen Sie Stack aktualisieren aus.** 1. Der CloudFormation Stack wird jetzt aktualisiert. Der Stack-Status wird `UPDATE_IN_PROGRESS` etwa fünf Minuten lang angezeigt, bevor er zu wechselt`UPDATE_COMPLETE`. Der Status wird regelmäßig aktualisiert, oder Sie können die Seite aktualisieren. ------ #### [ AWS CLI ] **So konfigurieren Sie Amazon SNS SNS-Benachrichtigungen mit dem AWS CLI** 1. Navigieren Sie zu dem `xray-scorekeep/cloudformation/` Ordner, den Sie zuvor erstellt haben, und öffnen Sie die `cf-resources.yaml` Datei in einem Texteditor. 1. Suchen Sie den `Default` Wert im **E-Mail-Parameter** und ändern Sie ihn von *UPDATE\$1ME* in eine gültige E-Mail-Adresse. ``` Parameters: Email: Type: String Default: UPDATE_ME # <- change to a valid abc@def.xyz email address ``` 1. Aktualisieren `cloudformation` Sie den CloudFormation Stack im Ordner mit dem folgenden AWS CLI Befehl: ``` aws cloudformation update-stack --stack-name scorekeep --capabilities "CAPABILITY_NAMED_IAM" --template-body file://cf-resources.yaml ``` 1. Warten Sie`UPDATE_COMPLETE`, bis der CloudFormation Stack-Status lautet. Dies kann einige Minuten dauern. Verwenden Sie den folgenden AWS CLI Befehl, um den Status zu überprüfen: ``` aws cloudformation describe-stacks --stack-name scorekeep --query "Stacks[0].StackStatus" ``` ------ Wenn die Aktualisierung abgeschlossen ist, startet Scorekeep neu und erstellt ein Abonnement für das SNS-Thema. Überprüfen Sie Ihre E-Mail-Adresse und bestätigen Sie das Abonnement, um Aktualisierungen anzuzeigen, wenn Sie ein Spiel abgeschlossen haben. Öffnen Sie die Trace-Map, um zu überprüfen, ob die Aufrufe an SNS nicht mehr fehlschlagen. ## Erkunden der Beispielanwendung Die Beispielanwendung ist eine HTTP-Web-API in Java, die für die Verwendung des X-Ray-SDK SDK for Java konfiguriert ist. Wenn Sie die Anwendung mit der CloudFormation Vorlage bereitstellen, erstellt sie die DynamoDB-Tabellen, den Amazon ECS-Cluster und andere Dienste, die für die Ausführung von Scorekeep auf ECS erforderlich sind. Eine Aufgabendefinitionsdatei für ECS wird über erstellt. CloudFormation Diese Datei definiert die Container-Images, die pro Aufgabe in einem ECS-Cluster verwendet werden. Diese Bilder stammen aus dem offiziellen öffentlichen X-Ray ECR. Das Scorekeep API-Container-Image enthält die API, die mit Gradle kompiliert wurde. Das Container-Image des Scorekeep-Frontend-Containers bedient das Frontend mithilfe des Nginx-Proxyservers. Dieser Server leitet Anfragen an Pfade, die mit /api beginnen, an die API weiter. Zum Instrumentieren eingehender HTTP-Anforderungen fügt die Anwendung den vom SDK bereitgestellten `TracingFilter` hinzu. **Example src/main/java/scorekeep/WebConfig.java — Servlet-Filter** ``` 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"); } ... ``` Dieser Filter sendet Ablaufverfolgungsdaten über alle eingehenden Anforderungen, die die Anwendung verarbeitet, einschließlich Anforderungs-URL, Methode, Antwortstatus sowie Start- und Endzeit. Die Anwendung führt auch Downstream-Aufrufe an DynamoDB mithilfe von durch. AWS SDK für Java Um diese Aufrufe zu instrumentieren, verwendet die Anwendung einfach die AWS SDK-bezogenen Submodule als Abhängigkeiten, und das X-Ray SDK for Java instrumentiert automatisch alle AWS SDK-Clients. Die Anwendung verwendet`Docker`, um den Quellcode auf der Instanz mit der `Gradle Docker Image` und der `Scorekeep API Dockerfile` Datei zu erstellen, um die ausführbare JAR auszuführen, die Gradle in ihrer eigenen Datei generiert. `ENTRYPOINT` **Example Verwendung von Docker zum Erstellen über Gradle Docker Image** ``` docker run --rm -v /PATH/TO/SCOREKEEP_REPO/home/gradle/project -w /home/gradle/project gradle:4.3 gradle build ``` **Example Dockerfile ENTRYPOINT** ``` ENTRYPOINT [ "sh", "-c", "java -Dserver.port=5000 -jar scorekeep-api-1.0.0.jar" ] ``` Die `build.gradle`-Datei lädt die SDK-Untermodule von Maven während der Kompilierung herunter, indem sie zu Abhängigkeiten erklärt werden. **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") ... } dependencyManagement { imports { mavenBom("com.amazonaws:aws-java-sdk-bom:1.11.67") mavenBom("com.amazonaws:aws-xray-recorder-sdk-bom:2.11.0") } } ``` Die Submodule Core, AWS SDK und AWS SDK Instrumentor sind alles, was erforderlich ist, um alle Downstream-Aufrufe, die mit dem SDK getätigt werden, automatisch zu instrumentieren. AWS Um die Rohsegmentdaten an die X-Ray-API weiterzuleiten, muss der X-Ray-Daemon den Datenverkehr auf dem UDP-Port 2000 abhören. *Zu diesem Zweck wird der X-Ray-Daemon in der Anwendung in einem Container ausgeführt, der zusammen mit der Scorekeep-Anwendung auf ECS als Sidecar-Container bereitgestellt wird.* Weitere Informationen finden Sie im Thema [X-Ray-Daemon](xray-daemon.md). **Example X-Ray-Daemon-Container-Definition in einer ECS-Aufgabendefinition** ``` ... Resources: ScorekeepTaskDefinition: Type: AWS::ECS::TaskDefinition Properties: ContainerDefinitions: ... - Cpu: '256' Essential: true Image: amazon/aws-xray-daemon MemoryReservation: '128' Name: xray-daemon PortMappings: - ContainerPort: '2000' HostPort: '2000' Protocol: udp ... ``` Das X-Ray-SDK SDK for Java bietet eine Klasse mit dem Namen`AWSXRay`, die den globalen Rekorder bereitstellt`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. Das Beispiel enthält einen statischen Block in der `WebConfig`-Klasse, der die globale Aufzeichnung mit Plugins und Samplingregeln konfiguriert. **Example src/main/java/scorekeep/WebConfig.java — Rekorder** ``` import com.amazonaws.xray.AWSXRay; import com.amazonaws.xray.AWSXRayRecorderBuilder; import com.amazonaws.xray.javax.servlet.AWSXRayServletFilter; import com.amazonaws.xray.plugins.ECSPlugin; import com.amazonaws.xray.plugins.EC2Plugin; import com.amazonaws.xray.strategy.sampling.LocalizedSamplingStrategy; ... @Configuration public class WebConfig { ... static { AWSXRayRecorderBuilder builder = AWSXRayRecorderBuilder.standard().withPlugin(new ECSPlugin()).withPlugin(new EC2Plugin()); URL ruleFile = WebConfig.class.getResource("/sampling-rules.json"); builder.withSamplingStrategy(new LocalizedSamplingStrategy(ruleFile)); AWSXRay.setGlobalRecorder(builder.build()); ... } } ``` In diesem Beispiel wird der Builder zum Laden von Samplingregeln aus einer Datei namens `sampling-rules.json` verwendet. Samplingregeln bestimmen die Rate, mit der das SDK Segmente für eingehende Anforderungen aufzeichnet. **Example src/main/java/resources/sampling-rules.json** ``` { "version": 1, "rules": [ { "description": "Resource creation.", "service_name": "*", "http_method": "POST", "url_path": "/api/*", "fixed_target": 1, "rate": 1.0 }, { "description": "Session polling.", "service_name": "*", "http_method": "GET", "url_path": "/api/session/*", "fixed_target": 0, "rate": 0.05 }, { "description": "Game polling.", "service_name": "*", "http_method": "GET", "url_path": "/api/game/*/*", "fixed_target": 0, "rate": 0.05 }, { "description": "State polling.", "service_name": "*", "http_method": "GET", "url_path": "/api/state/*/*/*", "fixed_target": 0, "rate": 0.05 } ], "default": { "fixed_target": 1, "rate": 0.1 } } ``` Die Samplingregeldatei definiert vier benutzerdefinierte Samplingregeln und die Standardregel. Für jede eingehende Anforderung wertet das SDK die benutzerdefinierten Regeln in der Reihenfolge aus, in der sie definiert sind. Das SDK wendet die erste Regel an, die der Methode, dem Pfad und dem Service-Namen der Anforderung entspricht. Bei Scorekeep fängt die erste Regel alle POST-Anforderungen (Aufrufe zum Erstellen von Ressourcen) ab, indem pro Sekunde ein festes Ziel einer einzelnen Anfrage und eine Rate von 1.0 angewendet wird bzw. 100 % der Anforderungen nach dem festen Ziel erfüllt sind. Die übrigen drei benutzerdefinierte Regeln wenden eine Rate von fünf Prozent ohne festes Ziel auf Sitzungs-, Spiel- und Statuslesevorgänge (GET-Anfragen) an. Dies minimiert die Anzahl der Ablaufverfolgungen für regelmäßige Aufrufe, die das Front-End automatisch alle paar Sekunden ausführt, um sicherzustellen, dass die Inhalte auf dem neuesten Stand sind. Für alle übrigen Anforderungen definiert die Datei eine Standardrate von einer einzelnen Anfrage pro Sekunde und einer Rate von 10 Prozent. Die Beispielanwendung zeigt auch, wie Sie erweiterte Funktionen wie die manuelle SDK-Client-Instrumentierung verwenden sowie zusätzliche Untersegmente und ausgehende HTTP-Aufrufe erstellen. Weitere Informationen finden Sie unter [AWS X-Ray Musteranwendung](xray-scorekeep.md). ## Optional: Richtlinie für geringste Rechte Die Scorekeep ECS-Container greifen mithilfe von Vollzugriffsrichtlinien wie und auf Ressourcen zu. `AmazonSNSFullAccess` `AmazonDynamoDBFullAccess` Die Verwendung von Richtlinien für vollen Zugriff ist nicht die beste Methode für Produktionsanwendungen. Im folgenden Beispiel wird die DynamoDB-IAM-Richtlinie aktualisiert, um die Sicherheit der Anwendung zu verbessern. Weitere Informationen zu bewährten Sicherheitsmethoden in IAM-Richtlinien finden Sie unter [Identitäts- und Zugriffsmanagement für AWS X-Ray](security-iam.md). **Example Vorlage cf-resources.yaml Rollendefinition ECSTask** ``` ECSTaskRole: Type: AWS::IAM::Role Properties: AssumeRolePolicyDocument: Version: "2012-10-17" Statement: - Effect: "Allow" Principal: Service: - "ecs-tasks.amazonaws.com" Action: - "sts:AssumeRole" ManagedPolicyArns: - "arn:aws:iam::aws:policy/AmazonDynamoDBFullAccess" - "arn:aws:iam::aws:policy/AmazonSNSFullAccess" - "arn:aws:iam::aws:policy/AWSXrayFullAccess" RoleName: "scorekeepRole" ``` Um Ihre Richtlinie zu aktualisieren, identifizieren Sie zunächst den ARN Ihrer DynamoDB-Ressourcen. Anschließend verwenden Sie den ARN in einer benutzerdefinierten IAM-Richtlinie. Schließlich wenden Sie diese Richtlinie auf Ihr Instanzprofil an. **So identifizieren Sie den ARN Ihrer DynamoDB-Ressource:** 1. Öffnen Sie die [DynamoDB-Konsole](https://console.aws.amazon.com/dynamodbv2). 1. Wählen Sie in der linken Navigationsleiste **Tabellen** aus. 1. Wählen Sie eine der Optionen`scorekeep-*`, um die Tabellendetailseite anzuzeigen. 1. Wählen Sie auf der Registerkarte **Übersicht** die Option **Zusätzliche Informationen** aus, um den Abschnitt zu erweitern und den Amazon-Ressourcennamen (ARN) anzuzeigen. Kopieren Sie diesen Wert. 1. Fügen Sie den ARN in die folgende IAM-Richtlinie ein und ersetzen Sie die `AWS_ACCOUNT_ID` Werte `AWS_REGION` und durch Ihre spezifische Region und Konto-ID. Diese neue Richtlinie erlaubt nur die angegebenen Aktionen und nicht die `AmazonDynamoDBFullAccess` Richtlinie, die alle Aktionen zulässt. **Example** ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Sid": "ScorekeepDynamoDB", "Effect": "Allow", "Action": [ "dynamodb:PutItem", "dynamodb:UpdateItem", "dynamodb:DeleteItem", "dynamodb:GetItem", "dynamodb:Scan", "dynamodb:Query" ], "Resource": "arn:aws:dynamodb:us-east-1:111122223333:table/scorekeep-*" } ] } ``` ------ Die Tabellen, die über die Anwendung erstellt werden, folgen einer einheitlichen Namenskonvention. Sie können das `scorekeep-*` Format verwenden, um alle Scorekeep-Tabellen anzugeben. **Ändern Sie Ihre IAM-Richtlinie** 1. Öffnen Sie die [Scorekeep-Aufgabenrolle (ScorekeepRole) von der IAM-Konsole aus.](https://console.aws.amazon.com/iamv2/home#/roles/details/scorekeepRole) 1. **Aktivieren Sie das Kontrollkästchen neben der Richtlinie und wählen Sie Entfernen, um diese `AmazonDynamoDBFullAccess` Richtlinie zu entfernen.** 1. Wählen Sie „**Berechtigungen hinzufügen**“, dann „**Richtlinien anhängen**“ und schließlich „**Richtlinie erstellen**“. 1. Wählen Sie die Registerkarte **JSON** und fügen Sie die oben erstellte Richtlinie ein. 1. Wählen Sie unten auf der Seite „**Weiter: Tags**“. 1. Wählen Sie unten auf der Seite „**Weiter: Bewertung**“. 1. Geben Sie unter **Name** einen Namen für die Richtlinie ein. 1. Wählen Sie unten auf der Seite **Richtlinie erstellen** aus. 1. Hängen Sie die neu erstellte Richtlinie an die `scorekeepRole` Rolle an. Es kann einige Minuten dauern, bis die angehängte Richtlinie wirksam wird. Wenn Sie die neue Richtlinie an die `scorekeepRole` Rolle angehängt haben, müssen Sie sie trennen, bevor Sie den CloudFormation Stapel löschen, da diese angehängte Richtlinie das Löschen des Stacks verhindert. Die Richtlinie kann automatisch getrennt werden, indem die Richtlinie gelöscht wird. **Entfernen Sie Ihre benutzerdefinierte IAM-Richtlinie** 1. Öffnen Sie die [IAM-Konsole](https://console.aws.amazon.com/iam). 1. Wählen Sie in der linken Navigationsleiste **Richtlinien** aus. 1. Suchen Sie nach dem benutzerdefinierten Richtliniennamen, den Sie zuvor in diesem Abschnitt erstellt haben, und wählen Sie das Optionsfeld neben dem Richtliniennamen, um ihn hervorzuheben. 1. Wählen Sie das Drop-down-Menü **Aktionen** und dann **Löschen** aus. 1. Geben Sie den Namen der benutzerdefinierten Richtlinie ein und wählen Sie dann **Löschen**, um den Löschvorgang zu bestätigen. Dadurch wird die Richtlinie automatisch von der `scorekeepRole` Rolle getrennt. ## Bereinigen Gehen Sie wie folgt vor, um die Ressourcen der Scorekeep-Anwendung zu löschen: **Anmerkung** Wenn Sie mithilfe des vorherigen Abschnitts dieses Tutorials benutzerdefinierte Richtlinien erstellt und angehängt haben, müssen Sie die Richtlinie aus dem entfernen, `scorekeepRole` bevor Sie den CloudFormation Stack löschen. ------ #### [ AWS-Managementkonsole ] **Löschen Sie die Beispielanwendung mit dem AWS-Managementkonsole** 1. Öffnen Sie die [CloudFormation-Konsole](https://console.aws.amazon.com/cloudformation/). 1. Wählen Sie das Optionsfeld neben dem `scorekeep` Stack-Namen in der Liste und wählen Sie dann **Löschen** aus. 1. Der CloudFormation Stapel wird jetzt gelöscht. Der Stack-Status bleibt `DELETE_IN_PROGRESS` einige Minuten lang bestehen, bis alle Ressourcen gelöscht sind. Der Status wird regelmäßig aktualisiert, oder Sie können die Seite aktualisieren. ------ #### [ AWS CLI ] **Löschen Sie die Beispielanwendung mit dem AWS CLI** 1. Geben Sie den folgenden AWS CLI Befehl ein, um den CloudFormation Stack zu löschen: ``` aws cloudformation delete-stack --stack-name scorekeep ``` 1. Warten Sie, bis der CloudFormation Stapel nicht mehr existiert. Dies dauert etwa fünf Minuten. Verwenden Sie den folgenden AWS CLI Befehl, um den Status zu überprüfen: ``` aws cloudformation describe-stacks --stack-name scorekeep --query "Stacks[0].StackStatus" ``` ------ ## Nächste Schritte Erfahre mehr über X-Ray im nächsten Kapitel,[AWS X-Ray Konzepte](xray-concepts.md). Um Ihre eigene App zu instrumentieren, erfahren Sie mehr über das X-Ray SDK for Java oder eines der anderen X-Ray SDKs: + **X-Ray SDK for Java** — [AWS X-Ray SDK for Java](xray-sdk-java.md) + **X-Ray-SDK für Node.js** — [AWS X-Ray-SDK für Node.js](xray-sdk-nodejs.md) + **X-Ray SDK for .NET** — [AWS X-Ray SDK for .NET](xray-sdk-dotnet.md) Informationen zum lokalen oder eingeschalteten Ausführen des X-Ray-Daemons finden Sie unter[AWS X-Ray Dämon](xray-daemon.md). AWS Wie Sie zur Beispielanwendung beitragen können GitHub, finden Sie unter [eb-java-scorekeep](https://github.com/awslabs/eb-java-scorekeep/tree/xray-gettingstarted). # Manuelles Instrumentieren von AWS SDK-Clients **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 instrumentiert automatisch alle AWS SDK-Clients, wenn Sie [das AWS SDK Instrumentor-Untermodul in Ihre Build-Abhängigkeiten aufnehmen](xray-sdk-java.md#xray-sdk-java-dependencies). Sie können die automatische Client-Instrumentierung durch Löschen des Instrumentor-Untermoduls deaktivieren. Auf diese Weise können Sie einige Clients manuell instrumentieren und andere ignorieren oder verschiedene Tracing-Handler auf unterschiedlichen Clients anwenden. Um die Unterstützung für die Instrumentierung bestimmter AWS SDK-Clients zu veranschaulichen, übergibt die Anwendung einen Tracing-Handler `AmazonDynamoDBClientBuilder` als Anforderungshandler im Benutzer-, Spiel- und Sitzungsmodell. Diese Codeänderung weist das SDK an, alle Aufrufe von DynamoDB mithilfe dieser Clients zu instrumentieren. **Example [https://github.com/awslabs/eb-java-scorekeep/tree/xray/src/main/java/scorekeep/SessionModel.java](https://github.com/awslabs/eb-java-scorekeep/tree/xray/src/main/java/scorekeep/SessionModel.java)— Manuelle AWS SDK-Client-Instrumentierung** ``` 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 SessionModel { private AmazonDynamoDB client = AmazonDynamoDBClientBuilder.standard() .withRegion(Constants.REGION) .withRequestHandlers(new TracingHandler(AWSXRay.getGlobalRecorder())) .build(); private DynamoDBMapper mapper = new DynamoDBMapper(client); ``` Wenn Sie das AWS SDK Instrumentor-Untermodul aus den Projektabhängigkeiten entfernen, werden nur die manuell instrumentierten AWS SDK-Clients in der Trace-Map angezeigt. # Erstellen zusätzlicher Untersegmente **Anmerkung** SDK/Daemon X-Ray-Wartungshinweis — Am 25. Februar 2026 wechselt das AWS X-Ray SDKs/Daemon in den Wartungsmodus, in dem die Versionen von X-Ray SDK und Daemon auf Sicherheitsprobleme beschränkt AWS werden. Weitere Informationen zum Zeitplan für den Support finden Sie unter. [Zeitplan für die Support von X-Ray SDK und Daemon](xray-sdk-daemon-timeline.md) Wir empfehlen die Migration zu OpenTelemetry. Weitere Informationen zur Migration zu OpenTelemetry finden Sie unter [Migration von X-Ray-Instrumentierung zu OpenTelemetry Instrumentierung](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html). In der Benutzermodellklasse erstellt die Anwendung manuell Untersegmente, um alle nachgelagerten Aufrufe, die innerhalb der `saveUser`-Funktion vorgenommen wurden, zu gruppieren, und fügt Metadaten hinzu. **Example [https://github.com/awslabs/eb-java-scorekeep/tree/xray/src/main/java/scorekeep/UserModel.java](https://github.com/awslabs/eb-java-scorekeep/tree/xray/src/main/java/scorekeep/UserModel.java) – Benutzerdefinierte Untersegmente** ``` 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); ... public void saveUser(User user) { // Wrap in subsegment Subsegment subsegment = AWSXRay.beginSubsegment("## UserModel.saveUser"); try { mapper.save(user); } catch (Exception e) { subsegment.addException(e); throw e; } finally { AWSXRay.endSubsegment(); } } ``` # Aufzeichnung von Anmerkungen, Metadaten und Benutzern IDs **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 der Spielmodellklasse zeichnet die Anwendung jedes Mal, wenn sie ein Spiel in DynamoDB speichert, `Game` Objekte in einem [Metadatenblock](xray-sdk-java-segment.md#xray-sdk-java-segment-metadata) auf. [Unabhängig davon zeichnet die Anwendung das Spiel IDs in [Anmerkungen](xray-sdk-java-segment.md#xray-sdk-java-segment-annotations) zur Verwendung mit Filterausdrücken auf.](xray-console-filters.md) **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(); } } ``` Im Move-Controller zeichnet die Anwendung den [Benutzer IDs](xray-sdk-java-segment.md#xray-sdk-java-segment-userid) mit `setUser` auf. Benutzer IDs werden in einem separaten Feld in Segmenten aufgezeichnet und für die Verwendung bei der Suche indexiert. **Example [src/main/java/scorekeep/MoveController.java — Benutzer-ID](https://github.com/awslabs/eb-java-scorekeep/tree/xray/src/main/java/scorekeep/MoveController.java)** ``` 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); } ``` # Instrumentieren von ausgehenden HTTP-Aufrufen **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). Die User-Factory-Klasse zeigt, wie die Anwendung das X-Ray-SDK für die Java-Version von verwendet`HTTPClientBuilder`, um ausgehende HTTP-Aufrufe zu instrumentieren. **Example [https://github.com/awslabs/eb-java-scorekeep/tree/xray/src/main/java/scorekeep/UserFactory.java](https://github.com/awslabs/eb-java-scorekeep/tree/xray/src/main/java/scorekeep/UserFactory.java)— HTTPClient Instrumentierung** ``` 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://uinames.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 derzeit `org.apache.http.impl.client.HttpClientBuilder` verwenden, können Sie einfach die Import-Anweisung für die Klasse mit einer Anweisung für `com.amazonaws.xray.proxies.apache.http.HttpClientBuilder` austauschen. # Instrumentieren von Aufrufen einer PostgreSQL-Datenbank **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). Die `application-pgsql.properties` Datei fügt der in erstellten Datenquelle den X-Ray PostgreSQL-Tracing-Interceptor hinzu. [https://github.com/awslabs/eb-java-scorekeep/tree/xray/src/main/java/scorekeep/RdsWebConfig.java](https://github.com/awslabs/eb-java-scorekeep/tree/xray/src/main/java/scorekeep/RdsWebConfig.java) **Example [https://github.com/awslabs/eb-java-scorekeep/tree/xray/src/main/resources/application-pgsql.properties](https://github.com/awslabs/eb-java-scorekeep/tree/xray/src/main/resources/application-pgsql.properties)— PostgreSQL-Datenbankinstrumentierung** ``` 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 ``` **Anmerkung** Weitere Informationen zum Hinzufügen einer PostgreSQL-Datenbank zum Anwendungsumfeld finden Sie unter [Konfiguration von Datenbanken mit Elastic Beanstalk](https://docs.aws.amazon.com/elasticbeanstalk/latest/dg/using-features.managing.db.html) im *AWS Elastic Beanstalk -Entwicklerhandbuch*. Die X-Ray-Demoseite in der `xray` Branche enthält eine Demo, die die instrumentierte Datenquelle verwendet, um Traces zu generieren, die Informationen über die von ihr generierten SQL-Abfragen enthalten. Navigieren Sie zu dem `/#/xray`-Pfad in der laufenden Anwendung oder wählen Sie in der Navigationsleiste **Powered by AWS X-Ray** aus, um die Demo-Seite anzusehen. ![\[AWS X-Ray integration demo page showing game session tracing and SQL query tracing options.\]](http://docs.aws.amazon.com/de_de/xray/latest/devguide/images/scorekeep-demo.png) Wählen Sie **SQL-Abfragen nachverfolgen** aus, um Spielsitzungen zu simulieren und die Ergebnisse in der zugehörigen Datenbank zu speichern. Wählen Sie dann „**Traces in AWS X-Ray anzeigen**“, um eine gefilterte Liste der Traces anzuzeigen, die auf die `/api/history` Route der API zutreffen. Wählen Sie eine der Ablaufverfolgungen aus der Liste aus, um die Zeitleiste, einschließlich der SQL-Abfrage, ansehen zu können. ![\[Timeline view of a trace showing method, response, duration, and age for a GET request.\]](http://docs.aws.amazon.com/de_de/xray/latest/devguide/images/scorekeep-trace-sql.png) # Instrumentierungsfunktionen AWS Lambda **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). Scorekeep verwendet zwei Funktionen. AWS Lambda Bei der ersten handelt es sich um eine Node.js-Funktion der `lambda`-Verzweigung, die zufällige Namen für neue Benutzer generiert. Wenn ein Benutzer eine Sitzung erstellt, ohne einen Namen einzugeben, ruft die Anwendung eine Funktion namens `random-name` mit dem AWS SDK für Java auf. Das X-Ray SDK for Java zeichnet Informationen über den Aufruf von Lambda in einem Untersegment auf, wie jeder andere Aufruf, der mit einem instrumentierten AWS SDK-Client getätigt wird. **Anmerkung** Die Ausführung der `random-name` Lambda-Funktion erfordert die Erstellung zusätzlicher Ressourcen außerhalb der Elastic Beanstalk Beanstalk-Umgebung. Weitere Informationen und Anweisungen finden Sie in der Readme-Datei: [AWS Lambda Integration](https://github.com/awslabs/eb-java-scorekeep/tree/xray/README.md#aws-lambda-integration). Die zweite Funktion, `scorekeep-worker`, ist eine Python-Funktion, die unabhängig von der Scorekeep-API ausgeführt wird. Wenn ein Spiel endet, schreibt die API die Sitzungs- und Spiele-ID in eine SQS-Warteschlange. Die Worker-Funktion liest Elemente aus der Warteschlange und ruft die Scorekeep-API auf, um vollständige Aufzeichnungen jeder Spielsitzung für die Speicherung in Amazon S3 zu erstellen. Scorekeep enthält CloudFormation Vorlagen und Skripte zur Erstellung beider Funktionen. Da Sie das X-Ray-SDK mit dem Funktionscode bündeln müssen, erstellen die Vorlagen die Funktionen ohne Code. Wenn Sie Scorekeep bereitstellen, erstellt eine im Ordner `.ebextensions` enthaltene Konfigurationsdatei ein Quell-Bundle, in dem das SDK enthalten ist, und aktualisiert den Funktionscode und die Konfiguration mit der AWS Command Line Interface. **Topics** + [Zufälliger Name](#scorekeep-lambda-randomname) + [Worker](#scorekeep-lambda-worker) ## Zufälliger Name Scorekeep ruft die Funktion für zufällige Namen auf, wenn ein Benutzer eine Spielesitzung beginnt, ohne dass er sich anmeldet oder einen Benutzernamen angibt. Wenn Lambda den Aufruf von verarbeitet`random-name`, liest es den [Tracing-Header](xray-concepts.md#xray-concepts-tracingheader), der die vom X-Ray SDK for Java geschriebene Trace-ID und die Sampling-Entscheidung enthält. Für jede gesampelte Anfrage führt Lambda den X-Ray-Daemon aus und schreibt zwei Segmente. Das erste Segment zeichnet Informationen über den Aufruf von Lambda auf, der die Funktion aufruft. Dieses Segment enthält dieselben Informationen wie das von Scorekeep aufgezeichnete Untersegment, jedoch aus Lambda-Sicht. Das zweite Segment repräsentiert die von der Funktion durchgeführte Arbeit. Lambda übergibt das Funktionssegment über den Funktionskontext an das X-Ray-SDK. Wenn Sie eine Lambda-Funktion instrumentieren, verwenden Sie das SDK nicht, um [ein Segment für eingehende Anfragen zu erstellen](xray-sdk-nodejs-middleware.md). Lambda stellt das Segment bereit, und Sie verwenden das SDK, um Clients zu instrumentieren und Untersegmente zu schreiben. ![\[Trace-Map, die zeigt, wie scorekeep eine Lambda-Funktion aufruft, um zufällige Namen für neue Benutzer zu erhalten\]](http://docs.aws.amazon.com/de_de/xray/latest/devguide/images/scorekeep-servicemap-lambda-node.png) Die `random-name`-Funktion wird in Node.js implementiert. Es verwendet das SDK für JavaScript in Node.js, um Benachrichtigungen mit Amazon SNS zu senden, und das X-Ray SDK für Node.js, um den SDK-Client zu AWS instrumentieren. Zum Schreiben von Anmerkungen erstellt die Funktion ein benutzerdefiniertes Untersegment mit `AWSXRay.captureFunc` und schreibt die Anmerkungen in die instrumentierte Funktion. In Lambda können Sie Anmerkungen nicht direkt in das Funktionssegment schreiben, sondern nur in ein Untersegment, das Sie erstellen. **Example [https://github.com/awslabs/eb-java-scorekeep/tree/xray/function/index.js](https://github.com/awslabs/eb-java-scorekeep/tree/xray/function/index.js) – Zufallsname-Lambda-Funktion** ``` var AWSXRay = require('aws-xray-sdk-core'); var AWS = AWSXRay.captureAWS(require('aws-sdk')); AWS.config.update({region: process.env.AWS_REGION}); var Chance = require('chance'); var myFunction = function(event, context, callback) { var sns = new AWS.SNS(); var chance = new Chance(); var userid = event.userid; var name = chance.first(); AWSXRay.captureFunc('annotations', function(subsegment){ subsegment.addAnnotation('Name', name); subsegment.addAnnotation('UserID', event.userid); }); // Notify var params = { Message: 'Created randon name "' + name + '"" for user "' + userid + '".', Subject: 'New user: ' + name, TopicArn: process.env.TOPIC_ARN }; sns.publish(params, function(err, data) { if (err) { console.log(err, err.stack); callback(err); } else { console.log(data); callback(null, {"name": name}); } }); }; exports.handler = myFunction; ``` Diese Funktion wird automatisch erstellt, wenn Sie die Beispielanwendung für Elastic Beanstalk bereitstellen. Der `xray` Zweig enthält ein Skript zum Erstellen einer leeren Lambda-Funktion. Die Konfigurationsdateien im `.ebextensions` Ordner erstellen das Funktionspaket mit `npm install` während der Bereitstellung und aktualisieren dann die Lambda-Funktion mit der AWS CLI. ## Worker Die instrumentierten Worker-Funktion wird in einer eigenen Verzweigung, `xray-worker`, bereitgestellt, da sie nur ausgeführt werden kann, wenn Sie die Worker-Funktion und verwandte Ressourcen zuerst erstellen. Detaillierte Anweisungen finden Sie in der [Readme-Datei zur Verzweigung](https://github.com/awslabs/eb-java-scorekeep/tree/xray-worker/README.md). Die Funktion wird alle 5 Minuten durch ein gebündeltes Amazon CloudWatch Events-Ereignis ausgelöst. Wenn sie ausgeführt wird, ruft die Funktion ein Element aus einer Amazon SQS SQS-Warteschlange ab, die von Scorekeep verwaltet wird. Jede Nachricht enthält Informationen zu einem abgeschlossenen Spiel. Der Worker ruft den Spieledatensatz und die Spieledokumente von anderen Tabellen ab, auf die der Spieledatensatz verweist. Beispielsweise enthält der Spieldatensatz in DynamoDB eine Liste der Züge, die während des Spiels ausgeführt wurden. Die Liste enthält nicht die Züge selbst, sondern IDs Züge, die in einer separaten Tabelle gespeichert sind. Sitzungen und Status werden ebenfalls als Referenzen gespeichert. Auf diese Weise wird verhindert, dass die Einträge in der Spieletabelle zu groß werden. Allerdings sind zusätzliche Aufrufe notwendig, um alle Informationen zum Spiel zu erhalten. Der Worker dereferenziert all diese Einträge und erstellt eine vollständige Aufzeichnung des Spiels als einzelnes Dokument in Amazon S3. Wenn Sie die Daten analysieren möchten, können Sie Abfragen direkt in Amazon S3 mit Amazon Athena ausführen, ohne leseintensive Datenmigrationen durchführen zu müssen, um Ihre Daten aus DynamoDB zu holen. ![\[Eine Trace-Map, die zeigt, wie die Scorekeep-Worker-Funktion Amazon SQS, Amazon S3 und die Scorekeep-API verwendet.\]](http://docs.aws.amazon.com/de_de/xray/latest/devguide/images/scorekeep-servicemap-lambdaworker-node.png) Für die Worker-Funktion ist die aktive Nachverfolgung in der Konfiguration in AWS Lambda aktiviert. Im Gegensatz zur Funktion mit zufälligen Namen erhält der Worker keine Anfrage von einer instrumentierten Anwendung und somit auch AWS Lambda keinen Tracing-Header. Bei aktivem Tracing erstellt Lambda die Trace-ID und trifft Stichprobenentscheidungen. Das X-Ray-SDK für Python ist nur ein paar Zeilen am Anfang der Funktion, die das SDK importieren und seine `patch_all` Funktion zum Patchen ausführen AWS SDK für Python (Boto) und HTTclients die zum Aufrufen von Amazon SQS und Amazon S3 verwendet werden. Wenn der Auftragnehmer die Scorekeep-API aufruft, fügt das SDK den [Ablaufverfolgungs-Header](xray-concepts.md#xray-concepts-tracingheader) zur Anforderung hinzu, um Aufrufe über die API nachzuverfolgen. **Example [https://github.com/awslabs/eb-java-scorekeep/tree/xray-worker/_lambda/scorekeep-worker/scorekeep-worker.py](https://github.com/awslabs/eb-java-scorekeep/tree/xray-worker/_lambda/scorekeep-worker/scorekeep-worker.py) – Worker Lambda-Funktion** ``` import os import boto3 import json import requests import time from aws_xray_sdk.core import xray_recorder from aws_xray_sdk.core import patch_all patch_all() queue_url = os.environ['WORKER_QUEUE'] def lambda_handler(event, context): # Create SQS client sqs = boto3.client('sqs') s3client = boto3.client('s3') # Receive message from SQS queue response = sqs.receive_message( QueueUrl=queue_url, AttributeNames=[ 'SentTimestamp' ], MaxNumberOfMessages=1, MessageAttributeNames=[ 'All' ], VisibilityTimeout=0, WaitTimeSeconds=0 ) ... ``` # Instrumentieren von Startup-Code **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 erstellt automatisch Segmente für eingehende Anfragen. Wenn eine Anfrage im Leistungsumfang enthalten ist, können Sie instrumentierte Clients verwenden und Untersegmente ohne Probleme aufzeichnen. Wenn Sie jedoch versuchen, einen instrumentierten Client im Startcode zu verwenden, erhalten Sie einen [SegmentNotFoundException](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/exceptions/SegmentNotFoundException.html). Startcode wird außerhalb des request/response Standardablaufs einer Webanwendung ausgeführt, sodass Sie Segmente manuell erstellen müssen, um ihn zu instrumentieren. Scorekeep stellt die Instrumentierung von Startup-Code in den `WebConfig`-Dateien dar. Scorekeep ruft beim Start eine SQL-Datenbank und Amazon SNS auf. ![\[Diagram showing client requests to Scorekeeper-init, which connects to SQL database and SNS.\]](http://docs.aws.amazon.com/de_de/xray/latest/devguide/images/scorekeep-servicemap-init.png) Die `WebConfig` Standardklasse erstellt ein Amazon SNS SNS-Abonnement für Benachrichtigungen. Um ein Segment bereitzustellen, in das das X-Ray-SDK schreiben kann, wenn der Amazon SNS-Client verwendet wird, ruft Scorekeep `endSegment` auf `beginSegment` und auf dem Global Recorder auf. **Example [https://github.com/awslabs/eb-java-scorekeep/tree/xray/src/main/java/scorekeep/WebConfig.java#L49](https://github.com/awslabs/eb-java-scorekeep/tree/xray/src/main/java/scorekeep/WebConfig.java#L49)— Instrumentierter AWS SDK-Client im Startcode** ``` AWSXRay.beginSegment("Scorekeep-init"); if ( System.getenv("NOTIFICATION_EMAIL") != null ){ try { Sns.createSubscription(); } catch (Exception e ) { logger.warn("Failed to create subscription for email "+ System.getenv("NOTIFICATION_EMAIL")); } } AWSXRay.endSegment(); ``` In`RdsWebConfig`, das Scorekeep verwendet, wenn eine Amazon RDS-Datenbank verbunden ist, erstellt die Konfiguration auch ein Segment für den SQL-Client, den Hibernate verwendet, wenn es das Datenbankschema beim Start anwendet. **Example [https://github.com/awslabs/eb-java-scorekeep/tree/xray/src/main/java/scorekeep/RdsWebConfig.java#L83](https://github.com/awslabs/eb-java-scorekeep/tree/xray/src/main/java/scorekeep/RdsWebConfig.java#L83)— Instrumentierter SQL-Datenbank-Client im Startcode** ``` @PostConstruct public void schemaExport() { EntityManagerFactoryImpl entityManagerFactoryImpl = (EntityManagerFactoryImpl) localContainerEntityManagerFactoryBean.getNativeEntityManagerFactory(); SessionFactoryImplementor sessionFactoryImplementor = entityManagerFactoryImpl.getSessionFactory(); StandardServiceRegistry standardServiceRegistry = sessionFactoryImplementor.getSessionFactoryOptions().getServiceRegistry(); MetadataSources metadataSources = new MetadataSources(new BootstrapServiceRegistryBuilder().build()); metadataSources.addAnnotatedClass(GameHistory.class); MetadataImplementor metadataImplementor = (MetadataImplementor) metadataSources.buildMetadata(standardServiceRegistry); SchemaExport schemaExport = new SchemaExport(standardServiceRegistry, metadataImplementor); AWSXRay.beginSegment("Scorekeep-init"); schemaExport.create(true, true); AWSXRay.endSegment(); } ``` `SchemaExport` wird automatisch ausgeführt und verwendet einen SQL-Client. Da der Client instrumentiert ist, muss Scorekeep die Standardimplementierung überschreiben und ein Segment bereitstellen, das das SDK verwenden kann, wenn der Client aufgerufen wird. # Instrumentieren von Skripten **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 auch Code instrumentieren, der nicht Teil Ihrer Anwendung ist. Wenn der X-Ray-Daemon läuft, leitet er alle Segmente, die er empfängt, an X-Ray weiter, auch wenn sie nicht vom X-Ray-SDK generiert wurden. Scorekeep nutzt seine eigenen Skripte zur Instrumentierung des Builds, der die Anwendung während der Bereitstellung kompiliert. **Example [https://github.com/awslabs/eb-java-scorekeep/tree/xray/bin/build.sh](https://github.com/awslabs/eb-java-scorekeep/tree/xray/bin/build.sh)— Instrumentiertes Build-Skript** ``` SEGMENT=$(python bin/xray_start.py) gradle build --quiet --stacktrace &> /var/log/gradle.log; GRADLE_RETURN=$? if (( GRADLE_RETURN != 0 )); then echo "Gradle failed with exit status $GRADLE_RETURN" >&2 python bin/xray_error.py "$SEGMENT" "$(cat /var/log/gradle.log)" exit 1 fi python bin/xray_success.py "$SEGMENT" ``` [https://github.com/awslabs/eb-java-scorekeep/tree/xray/bin/xray_start.py](https://github.com/awslabs/eb-java-scorekeep/tree/xray/bin/xray_start.py), [https://github.com/awslabs/eb-java-scorekeep/tree/xray/bin/xray_error.py](https://github.com/awslabs/eb-java-scorekeep/tree/xray/bin/xray_error.py) und [https://github.com/awslabs/eb-java-scorekeep/tree/xray/bin/xray_success.py](https://github.com/awslabs/eb-java-scorekeep/tree/xray/bin/xray_success.py) sind einfache Python-Skripte, die Segmentobjekte erstellen, diese in JSON-Dokumente konvertieren und über UDP an den Daemon senden. Wenn der Gradle-Build fehlschlägt, können Sie die Fehlermeldung finden, indem Sie in der Trace-Map der X-Ray-Konsole auf den **Scorekeep-Build-Knoten** klicken. ![\[Diagram showing client connection to Scorekeep-build with average time of 14.6s and 0.07/min.\]](http://docs.aws.amazon.com/de_de/xray/latest/devguide/images/scorekeep-servicemap-builderror.png) ![\[Timeline view showing Scorekeep-build process with 14.6 second duration and warning icon.\]](http://docs.aws.amazon.com/de_de/xray/latest/devguide/images/scorekeep-timeline-builderror.png) ![\[Error message showing build failure due to missing ElasticBeanstalkPlugin symbol in RdsWebConfig class.\]](http://docs.aws.amazon.com/de_de/xray/latest/devguide/images/scorekeep-exception-builderror.png) # Instrumentieren eines Web-App-Clients **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 der [https://github.com/awslabs/eb-java-scorekeep/tree/xray-cognito](https://github.com/awslabs/eb-java-scorekeep/tree/xray-cognito)Filiale verwendet Scorekeep Amazon Cognito, damit Benutzer ein Konto erstellen und sich damit anmelden können, um ihre Benutzerinformationen aus einem Amazon Cognito Cognito-Benutzerpool abzurufen. Wenn sich ein Benutzer anmeldet, verwendet Scorekeep einen Amazon Cognito Cognito-Identitätspool, um temporäre AWS Anmeldeinformationen für die Verwendung mit dem zu erhalten. AWS SDK für JavaScript Der Identitätenpool ist so konfiguriert, dass angemeldete Benutzer Ablaufverfolgungsdaten in AWS X-Ray schreiben können. Die Web-App nutzt diese Anmeldeinformationen, um die Benutzer-ID des angemeldeten Benutzers, den Browserpfad und die Client-Ansicht von Aufrufen der Scorekeep-API aufzuzeichnen. Der Großteil der Vorgänge wird in einer Service-Klasse mit dem Namen `xray` ausgeführt. Diese Serviceklasse bietet Methoden zum Generieren der erforderlichen Identifikatoren, zum Erstellen von Segmenten in Bearbeitung, zum Finalisieren von Segmenten und zum Senden von Segmentdokumenten an die X-Ray-API. **Example [https://github.com/awslabs/eb-java-scorekeep/tree/xray-cognito/public/app/xray.js](https://github.com/awslabs/eb-java-scorekeep/tree/xray-cognito/public/app/xray.js)— Segmente aufzeichnen und hochladen** ``` ... service.beginSegment = function() { var segment = {}; var traceId = '1-' + service.getHexTime() + '-' + service.getHexId(24); var id = service.getHexId(16); var startTime = service.getEpochTime(); segment.trace_id = traceId; segment.id = id; segment.start_time = startTime; segment.name = 'Scorekeep-client'; segment.in_progress = true; segment.user = sessionStorage['userid']; segment.http = { request: { url: window.location.href } }; var documents = []; documents[0] = JSON.stringify(segment); service.putDocuments(documents); return segment; } service.endSegment = function(segment) { var endTime = service.getEpochTime(); segment.end_time = endTime; segment.in_progress = false; var documents = []; documents[0] = JSON.stringify(segment); service.putDocuments(documents); } service.putDocuments = function(documents) { var xray = new AWS.XRay(); var params = { TraceSegmentDocuments: documents }; xray.putTraceSegments(params, function(err, data) { if (err) { console.log(err, err.stack); } else { console.log(data); } }) } ``` Diese Methoden werden im Header und in `transformResponse`-Funktionen in den Ressourcen-Services aufgerufen, die die Web-App zum Aufrufen der Scorekeep-API verwendet. Um das Clientsegment in denselben Trace aufzunehmen wie das von der API generierte Segment, muss die Web-App die Trace-ID und die Segment-ID in einen [Tracing-Header](xray-concepts.md#xray-concepts-tracingheader) (`X-Amzn-Trace-Id`) aufnehmen, den das X-Ray-SDK lesen kann. Wenn die instrumentierte Java-Anwendung eine Anfrage mit diesem Header empfängt, verwendet das X-Ray SDK for Java dieselbe Trace-ID und macht das Segment vom Web-App-Client zum übergeordneten Segment. **Example [https://github.com/awslabs/eb-java-scorekeep/tree/xray-cognito/public/app/services.js](https://github.com/awslabs/eb-java-scorekeep/tree/xray-cognito/public/app/services.js)— Aufzeichnen von Segmenten für Angular Resource Calls und Schreiben von Tracing-Headern** ``` var module = angular.module('scorekeep'); module.factory('SessionService', function($resource, api, XRay) { return $resource(api + 'session/:id', { id: '@_id' }, { segment: {}, get: { method: 'GET', headers: { 'X-Amzn-Trace-Id': function(config) { segment = XRay.beginSegment(); return XRay.getTraceHeader(segment); } }, transformResponse: function(data) { XRay.endSegment(segment); return angular.fromJson(data); }, }, ... ``` Die resultierende Trace-Map enthält einen Knoten für den Web-App-Client. ![\[\]](http://docs.aws.amazon.com/de_de/xray/latest/devguide/images/scorekeep-servicemap-client.png) Ablaufverfolgungen, die Segmente aus der Web-App einschließen, zeigen die URL an, die der Benutzer im Browser sieht (Pfad beginnend mit `/#/`). Ohne Client-Instrumentierung erhalten Sie nur die URL der API-Ressource, die die Web-App aufruft (Pfade beginnend mit `/api/`). ![\[\]](http://docs.aws.amazon.com/de_de/xray/latest/devguide/images/scorekeep-traces-client.png) # Verwenden instrumentierter Clients in Auftragnehmer-Threads **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). Scorekeep verwendet einen Worker-Thread, um eine Benachrichtigung an Amazon SNS zu veröffentlichen, wenn ein Benutzer ein Spiel gewinnt. Die Veröffentlichung der Benachrichtigung dauert länger als alle übrigen Anfragevorgänge zusammen und wirkt sich nicht auf den Client oder Benutzer aus. Die Aufgabe asynchron auszuführen ist daher eine gute Möglichkeit, die Reaktionszeit zu verbessern. Das X-Ray-SDK SDK for Java weiß jedoch nicht, welches Segment aktiv war, als der Thread erstellt wurde. Wenn Sie also versuchen, den instrumentierten AWS SDK für Java Client innerhalb des Threads zu verwenden, wird ein `SegmentNotFoundException` Fehler ausgelöst, wodurch der Thread abstürzt. **Example Web-1.error.log** ``` Exception in thread "Thread-2" com.amazonaws.xray.exceptions.SegmentNotFoundException: Failed to begin subsegment named 'AmazonSNS': segment cannot be found. at sun.reflect.NativeConstructorAccessorImpl.newInstance0(Native Method) at sun.reflect.NativeConstructorAccessorImpl.newInstance(NativeConstructorAccessorImpl.java:62) at sun.reflect.DelegatingConstructorAccessorImpl.newInstance(DelegatingConstructorAccessorImpl.java:45) ... ``` Um dieses Problem zu beheben, verwendet die Anwendung, `GetTraceEntity` um einen Verweis auf das Segment im Haupt-Thread abzurufen und `Entity.run()` den Worker-Thread-Code mit Zugriff auf den Kontext des Segments sicher auszuführen. **Example [https://github.com/awslabs/eb-java-scorekeep/tree/xray/src/main/java/scorekeep/MoveFactory.java#L70](https://github.com/awslabs/eb-java-scorekeep/tree/xray/src/main/java/scorekeep/MoveFactory.java#L70)— Übergibt den Trace-Kontext an einen Worker-Thread** ``` 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.AWSXRayRecorder](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/AWSXRayRecorder.html); import [com.amazonaws.xray.entities.Entity](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/entities/Entity.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); ... Entity segment = recorder.getTraceEntity(); Thread comm = new Thread() { public void run() { segment.run(() -> { Subsegment subsegment = AWSXRay.beginSubsegment("## Send notification"); Sns.sendNotification("Scorekeep game completed", "Winner: " + userId); AWSXRay.endSubsegment(); } } ``` Da die Anfrage nun vor dem Aufruf von Amazon SNS gelöst wird, erstellt die Anwendung ein separates Untersegment für den Thread. Dadurch wird verhindert, dass das X-Ray-SDK das Segment schließt, bevor es die Antwort von Amazon SNS aufzeichnet. Wenn zum Zeitpunkt der Bearbeitung der Anfrage durch Scorekeep kein Untersegment geöffnet war, ging die Antwort von Amazon SNS möglicherweise verloren. ![\[\]](http://docs.aws.amazon.com/de_de/xray/latest/devguide/images/scorekeep-workerthread.png) Weitere Informationen zu Multithreading finden Sie unter [Übermitteln von Segmentkontext zwischen Threads in einer Multithread-Anwendung](xray-sdk-java-multithreading.md).