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 Agent für automatische Instrumentierung für Java

Der AWS X-Ray Autoinstrumentation-Agent für Java ist eine Tracing-Lösung, die Ihre Java-Webanwendungen mit minimalem Entwicklungsaufwand instrumentiert. Der Agent ermöglicht die Ablaufverfolgung für Servlet-basierte Anwendungen und alle Downstream-Anfragen des Agenten, die mit unterstützten Frameworks und Bibliotheken gestellt wurden. Dazu gehören auch HTTP Downstream-Anfragen, AWS SDK Anfragen und SQL Abfragen von Apache, die mithilfe eines Treibers gestellt wurden. JDBC Der Agent verbreitet den X-Ray-Kontext, einschließlich aller aktiven Segmente und Untersegmente, über Threads hinweg. Alle Konfigurationen und die Vielseitigkeit des X-Ray SDK sind weiterhin mit dem Java-Agenten verfügbar. Es wurden geeignete Standardeinstellungen gewählt, um sicherzustellen, dass der Agent mit minimalem Aufwand arbeitet.

Die X-Ray Agent-Lösung eignet sich am besten für Servlet-basierte Java-Webanwendungsserver mit Request-Response. Wenn Ihre Anwendung ein asynchrones Framework verwendet oder nicht gut als Request-Response-Service modelliert ist, sollten Sie stattdessen eine manuelle Instrumentierung mit dem in Betracht ziehen. SDK 

Der X-Ray-Agent wird mit dem Distributed Systems Comprehension Toolkit (D) erstellt. iSCo D iSCo ist ein Open-Source-Framework zum Erstellen von Java-Agenten, die in verteilten Systemen verwendet werden können. Es ist zwar nicht notwendig, D zu verstehen, iSCo um den X-Ray-Agenten zu verwenden, aber Sie können mehr über das Projekt erfahren, indem Sie die Homepage unter besuchen GitHub. Der X-Ray-Agent ist ebenfalls vollständig als Open Source verfügbar. Um den Quellcode einzusehen, Beiträge zu leisten oder Probleme mit dem Agenten zu äußern, besuchen Sie das entsprechende Repository unter GitHub.

Beispielanwendung

Die eb-java-scorekeepProbenapplikation ist so angepasst, dass sie mit dem Röntgenmittel instrumentiert werden kann. Dieser Zweig enthält keine Servlet-Filter- oder Rekorderkonfiguration, da diese Funktionen vom Agenten ausgeführt werden. Um die Anwendung lokal oder mithilfe von AWS Ressourcen auszuführen, folgen Sie den Schritten in der Readme-Datei der Beispielanwendung. Die Anweisungen zur Verwendung der Beispiel-App zum Generieren von Röntgenspuren finden Sie im Tutorial der Beispiel-App.

Erste Schritte

Gehen Sie wie folgt vor, um mit dem X-Ray-Java-Agenten für automatische Instrumentierung in Ihrer eigenen Anwendung zu beginnen.

Konfiguration

Der X-Ray-Agent wird durch eine externe, vom Benutzer bereitgestellte JSON Datei konfiguriert. Standardmäßig wird diese Datei im Stammverzeichnis des Klassenpfads des Benutzers (z. B. in seinem resources Verzeichnis) benannt. xray-agent.json Sie können einen benutzerdefinierten Speicherort für die Konfigurationsdatei konfigurieren, indem Sie die com.amazonaws.xray.configFile Systemeigenschaft auf den absoluten Dateisystempfad Ihrer Konfigurationsdatei setzen.

Als Nächstes wird ein Beispiel für eine Konfigurationsdatei angezeigt.

{     
    "serviceName": "XRayInstrumentedService", 
    "contextMissingStrategy": "LOG_ERROR", 
    "daemonAddress": "127.0.0.1:2000", 
    "tracingEnabled": true, 
    "samplingStrategy": "CENTRAL",     
    "traceIdInjectionPrefix": "prefix",     
    "samplingRulesManifest": "/path/to/manifest",     
    "awsServiceHandlerManifest": "/path/to/manifest",     
    "awsSdkVersion": 2,     
    "maxStackTraceLength": 50,     
    "streamingThreshold": 100,     
    "traceIdInjection": true,     
    "pluginsEnabled": true,     
    "collectSqlQueries": false 
}

Konfigurationsspezifikation

In der folgenden Tabelle werden gültige Werte für jede Eigenschaft beschrieben. Bei Eigenschaftsnamen wird zwischen Groß- und Kleinschreibung unterschieden, bei ihren Schlüsseln jedoch nicht. Bei Eigenschaften, die durch Umgebungsvariablen und Systemeigenschaften außer Kraft gesetzt werden können, ist die Prioritätsreihenfolge immer die Umgebungsvariable, dann die Systemeigenschaft und dann die Konfigurationsdatei. Hinweise zu Eigenschaften, die Sie überschreiben können, finden Sie unter. Umgebungsvariablen Alle Felder sind optional.

Konfiguration der Protokollierung

Die Protokollebene des X-Ray-Agenten kann auf die gleiche Weise wie X-Ray SDK für Java konfiguriert werden. Weitere Informationen Protokollierung zur Konfiguration der Protokollierung mit X-Ray SDK für Java finden Sie unter.

Manuelle Instrumentierung

Wenn Sie zusätzlich zur automatischen Instrumentierung des Agenten eine manuelle Instrumentierung durchführen möchten, fügen Sie das X-Ray SDK als Abhängigkeit zu Ihrem Projekt hinzu. Beachten Sie, dass die SDK unter Tracing Incoming Requests genannten benutzerdefinierten Servlet-Filter nicht mit dem X-Ray-Agenten kompatibel sind.

Wenn Sie in einem Maven-Projekt arbeiten, fügen Sie Ihrer pom.xml Datei die folgenden Abhängigkeiten hinzu.

<dependencies> 
  <dependency> 
    <groupId>com.amazonaws</groupId> 
    <artifactId>aws-xray-recorder-sdk-core</artifactId> 
    <version>2.11.0</version> 
  </dependency> 
  </dependencies>

Wenn Sie in einem Gradle-Projekt arbeiten, fügen Sie Ihrer build.gradle Datei die folgenden Abhängigkeiten hinzu.

implementation 'com.amazonaws:aws-xray-recorder-sdk-core:2.11.0' 

Sie können benutzerdefinierte Untersegmente zusätzlich zu Anmerkungen, Metadaten und Benutzern hinzufügen, IDs während Sie den Agenten verwenden, genau wie beim normalen. SDK Der Agent verbreitet den Kontext automatisch zwischen Threads, sodass bei der Arbeit mit Multithread-Anwendungen keine Behelfslösungen für die Übertragung des Kontexts erforderlich sein sollten.

Fehlerbehebung

Da der Agent über eine vollautomatische Instrumentierung verfügt, kann es schwierig sein, die Ursache eines Problems zu ermitteln, wenn Probleme auftreten. Wenn der X-Ray-Agent bei Ihnen nicht wie erwartet funktioniert, überprüfen Sie die folgenden Probleme und Lösungen. Der X-Ray-Agent und SDK verwende Jakarta Commons Logging (JCL). Um die Logging-Ausgabe zu sehen, stellen Sie sicher, dass JCL sich eine Bridge, die mit Ihrem Logging-Backend verbindet, im Klassenpfad befindet, wie im folgenden Beispiel: oder. log4j-jcl jcl-over-slf4j

Problem: Ich habe den Java-Agenten in meiner Anwendung aktiviert, sehe aber nichts auf der X-Ray-Konsole

Läuft der X-Ray-Daemon auf demselben Computer?

Falls nicht, lesen Sie in der Dokumentation zum X-Ray-Daemon nach, um ihn einzurichten.

Sehen Sie in Ihren Anwendungsprotokollen eine Meldung wie „Initialisierung des X-Ray Agent Recorders“?

Wenn Sie den Agenten korrekt zu Ihrer Anwendung hinzugefügt haben, wird diese Meldung auf der INFO Ebene protokolliert, wenn Ihre Anwendung gestartet wird, bevor sie Anfragen entgegennimmt. Wenn diese Meldung nicht angezeigt wird, läuft der Java-Agent nicht zusammen mit Ihrem Java-Prozess. Stellen Sie sicher, dass Sie alle Einrichtungsschritte korrekt und ohne Tippfehler ausgeführt haben.

Sehen Sie in Ihren Anwendungsprotokollen mehrere Fehlermeldungen mit der Aufschrift „Ausnahme fehlt AWS X-Ray im Kontext unterdrücken“?

Diese Fehler treten auf, weil der Agent versucht, nachgelagerte Anfragen wie AWS SDK Anfragen oder SQL Abfragen zu instrumentieren, der Agent aber nicht in der Lage war, automatisch ein Segment zu erstellen. Wenn Sie viele dieser Fehler sehen, ist der Agent möglicherweise nicht das beste Tool für Ihren Anwendungsfall und Sie sollten SDK stattdessen eine manuelle Instrumentierung mit dem X-Ray in Betracht ziehen. Alternativ können Sie SDK X-Ray-Debug-Logs aktivieren, um den Stack-Trace zu sehen, wo die kontextlosen Ausnahmen auftreten. Sie können diese Teile Ihres Codes mit benutzerdefinierten Segmenten umschließen, wodurch diese Fehler behoben werden sollten. Ein Beispiel für das Umschließen von Downstream-Anfragen mit benutzerdefinierten Segmenten finden Sie im Beispielcode unter Instrumentieren von Startcode.

Problem: Einige der Segmente, die ich erwarte, erscheinen nicht auf der X-Ray-Konsole

Verwendet Ihre Anwendung Multithreading?

Wenn einige Segmente, von denen Sie erwarten, dass sie erstellt werden, nicht in Ihrer Konsole erscheinen, könnte dies an Hintergrund-Threads in Ihrer Anwendung liegen. Wenn Ihre Anwendung Aufgaben mithilfe von Hintergrund-Threads ausführt, die „Fire and Forget“ sind, wie z. B. einen einmaligen Aufruf einer Lambda-Funktion mit dem oder das regelmäßige Abrufen einiger HTTP Endpunkte AWS SDK, kann dies den Agenten verwirren, während er den Kontext zwischen Threads verbreitet. Um zu überprüfen, ob dies Ihr Problem ist, aktivieren Sie die SDK X-Ray-Debug-Logs und suchen Sie nach Meldungen wie: Segment mit dem Namen < NAME > wird nicht ausgegeben, da es Untersegmente in Bearbeitung übergeordnet hat. Um dieses Problem zu umgehen, können Sie versuchen, den Hintergrund-Threads beizutreten, bevor Ihr Server zurückkehrt, um sicherzustellen, dass die gesamte in ihnen geleistete Arbeit aufgezeichnet wird. Oder Sie können die contextPropagation Konfiguration des Agenten so einstellen, dass die false Kontextweiterleitung in Hintergrund-Threads deaktiviert wird. In diesem Fall müssen Sie diese Threads manuell mit benutzerdefinierten Segmenten instrumentieren oder die Ausnahmen ignorieren, die sie erzeugen, wenn der Kontext fehlt.

Haben Sie Stichprobenregeln eingerichtet?

Wenn scheinbar zufällige oder unerwartete Segmente auf der X-Ray-Konsole erscheinen oder die Segmente, von denen Sie erwarten, dass sie sich auf der Konsole befinden, nicht, liegt möglicherweise ein Sampling-Problem vor. Der X-Ray-Agent wendet zentralisierte Stichproben auf alle von ihm erstellten Segmente an und verwendet dabei die Regeln der X-Ray-Konsole. Die Standardregel lautet, dass 1 Segment pro Sekunde plus 5% der nachfolgenden Segmente abgetastet werden. Das bedeutet, dass Segmente, die schnell mit dem Agenten erstellt werden, möglicherweise nicht gesampelt werden. Um dieses Problem zu lösen, sollten Sie auf der X-Ray-Konsole benutzerdefinierte Sampling-Regeln erstellen, die die gewünschten Segmente entsprechend abtasten. Weitere Informationen finden Sie unter Sampling.