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.

1. Führen Sie den X-Ray-Daemon in Ihrer Umgebung aus. Weitere Informationen finden Sie unter AWS X-Ray Dämon.

2. Laden Sie die neueste Version des Agenten herunter. Entpacken Sie das Archiv und notieren Sie sich seinen Speicherort in Ihrem Dateisystem. Sein Inhalt sollte wie folgt aussehen.

   disco 
   ├── disco-java-agent.jar 
   └── disco-plugins 
       ├── aws-xray-agent-plugin.jar 
       ├── disco-java-agent-aws-plugin.jar 
       ├── disco-java-agent-sql-plugin.jar 
       └── disco-java-agent-web-plugin.jar

3. Ändern Sie die JVM Argumente Ihrer Anwendung so, dass sie Folgendes enthalten, wodurch der Agent aktiviert wird. Stellen Sie sicher, dass das -javaagent Argument vor dem -jar Argument steht, falls zutreffend. Der Prozess zum Ändern von JVM Argumenten hängt von den Tools und Frameworks ab, die Sie zum Starten Ihres Java-Servers verwenden. Spezifische Anleitungen finden Sie in der Dokumentation Ihres Server-Frameworks.

   -javaagent:/<path-to-disco>/disco-java-agent.jar=pluginPath=/<path-to-disco>/disco-plugins

4. Um festzulegen, wie der Name Ihrer Anwendung auf der X-Ray-Konsole angezeigt wird, legen Sie die AWS_XRAY_TRACING_NAME Umgebungsvariable oder die com.amazonaws.xray.strategy.tracingName Systemeigenschaft fest. Wenn kein Name angegeben wird, wird ein Standardname verwendet.

5. Starten Sie Ihren Server oder Container neu. Eingehende Anfragen und ihre Downstream-Aufrufe werden jetzt verfolgt. Wenn Sie nicht die erwarteten Ergebnisse sehen, finden Sie weitere Informationen unterFehlerbehebung.

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.

Name der Eigenschaft	Typ	Zulässige Werte	Beschreibung	Umgebungsvariable	Systemeigenschaft	Standard
serviceName	String	Jede Zeichenfolge	Der Name Ihres instrumentierten Dienstes, so wie er in der X-Ray-Konsole angezeigt wird.	AWS_XRAY_TRACING_NAME	com.amazonaws.xray.strategy. tracingName	XRayInstrumentedService
contextMissingStrategy	String	LOG_ERROR, IGNORE_ERROR	Die Aktion, die der Agent ausführt, wenn er versucht, den X-Ray-Segmentkontext zu verwenden, aber keiner vorhanden ist.	AWS_XRAY_CONTEXT_MISSING	com.amazonaws.xray.strategy. contextMissingStrategy	LOG_ERROR
daemonAddress	String	Formatierte IP-Adresse und Port oder Liste von TCP IP-Adressen UDP	Die Adresse, die der Agent für die Kommunikation mit dem X-Ray-Daemon verwendet.	AWS_XRAY_DAEMON_ADDRESS	com.amazonaws.xray.emitter. daemonAddress	127,0.0. 1:2000
tracingEnabled	Boolesch	Wahr, falsch	Ermöglicht die Instrumentierung durch den X-Ray-Agenten.	AWS_XRAY_TRACING_ENABLED	com.amazonaws.xray. tracingEnabled	TRUE
samplingStrategy	String	CENTRAL, LOCAL, NONE, ALL	Die vom Agenten verwendete Probenahmestrategie. ALLerfasst alle Anfragen, NONE erfasst keine Anfragen. Siehe Regeln für die Probenahme.	N/A	N/A	CENTRAL
traceIdInjectionPräfix	String	Jede Zeichenfolge	Schließt das angegebene Präfix vor der Eingabe von Trace IDs in die Protokolle ein.	N/A	N/A	Keine (leere Zeichenfolge)
samplingRulesManifest	String	Ein absoluter Dateipfad	Der Pfad zu einer Datei mit benutzerdefinierten Stichprobenregeln, die als Quelle für Stichprobenregeln für die lokale Stichprobenstrategie oder als Ausweichregeln für die zentrale Strategie verwendet werden soll.	N/A	N/A	DefaultSamplingRules.json
awsServiceHandlerManifest	String	Ein absoluter Dateipfad	Der Pfad zu einer Zulassungsliste für benutzerdefinierte Parameter, die zusätzliche Informationen von AWS SDK Clients erfasst.	N/A	N/A	DefaultOperationParameterWhitelist.json
awsSdkVersion	Ganzzahl	1, 2	Version von AWS SDKfür Java, die Sie verwenden. Wird ignoriert, wenn awsServiceHandlerManifest es nicht auch gesetzt ist.	N/A	N/A	2
maxStackTraceLänge	Ganzzahl	Nichtnegative Ganzzahlen	Die maximale Anzahl von Zeilen eines Stack-Trace, die in einem Trace aufgezeichnet werden sollen.	N/A	N/A	50
streamingThreshold	Ganzzahl	Nichtnegative Ganzzahlen	Nachdem mindestens so viele Untersegmente geschlossen wurden, werden sie an den Daemon gestreamt, um zu verhindern, dass die Blöcke out-of-band zu groß werden.	N/A	N/A	100
traceIdInjection	Boolesch	Wahr, falsch	Aktiviert die X-Ray-Trace-ID-Injektion in Protokolle, wenn die in der Protokollierungskonfiguration beschriebenen Abhängigkeiten und die Konfiguration ebenfalls hinzugefügt werden. Sonst tut nichts.	N/A	N/A	TRUE
pluginsEnabled	Boolesch	Wahr, falsch	Aktiviert Plugins, die Metadaten über die AWS Umgebungen aufzeichnen, in denen Sie arbeiten. Siehe Plugins.	N/A	N/A	TRUE
collectSqlQueries	Boolesch	Wahr, Falsch	Zeichnet SQL Abfragezeichenfolgen nach bestem Wissen und Gewissen in SQL Untersegmenten auf.	N/A	N/A	FALSE
contextPropagation	Boolesch	Wahr, falsch	Gibt automatisch den X-Ray-Kontext zwischen Threads weiter, falls der Wert wahr ist. Andernfalls verwendet Thread Local, um den Kontext zu speichern, und eine manuelle Weitergabe zwischen Threads ist erforderlich.	N/A	N/A	TRUE

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.

Anmerkung

Sie müssen die neueste Version von X-Ray verwendenSDK, um die manuelle Instrumentierung durchzuführen und gleichzeitig den Agenten zu verwenden.

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

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