AWS X-RayAgent zur automatischen Instrumentierung für Java - AWS X-Ray

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-RayAgent zur automatischen Instrumentierung für Java

DieAWS X-RayAuto-Instrumentierungs-Agent für Java ist eine Tracing-Lösung, die Ihre Java-Webanwendungen mit minimalem Entwicklungsaufwand instrumentiert. Der Agent ermöglicht die Verfolgung für servletbasierte Anwendungen und alle nachgelagerten Anforderungen des Agenten, die mit unterstützten Frameworks und Bibliotheken gestellt werden. Dies beinhaltet Downstream-Apache HTTP-Anfragen,AWSSDK-Anfragen und SQL-Abfragen mit einem JDBC-Treiber. Der Agent verbreitet den Röntgenkontext, einschließlich aller aktiven Segmente und Teilsegmente, über Threads hinweg. Alle Konfigurationen und Vielseitigkeit des X-Ray SDK sind weiterhin mit dem Java-Agenten verfügbar. Es wurden geeignete Standardwerte gewählt, um sicherzustellen, dass der Agent mit minimalem Aufwand arbeitet.

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

Der X-Ray-Agent wird mit dem Toolkit Distributed Systems Comprehension oder DisCo erstellt. DisCo ist ein Open-Source-Framework zum Erstellen von Java-Agenten, die in verteilten Systemen verwendet werden können. Obwohl es nicht notwendig ist, DisCo für die Verwendung des Röntgen-Agenten zu verstehen, können Sie mehr über das Projekt erfahren, indem Sie dieHomepage auf GitHubaus. Der Röntgenagent ist ebenfalls vollständig Open Source. Um den Quellcode einzusehen, Beiträge zu leisten oder Probleme über den Agenten aufzusprechen, besuchen Sie die-Repository auf GitHubaus.

Beispielanwendung

Dieeb-java-scorekeepDie Probenanwendung ist angepasst, um mit dem Röntgenmittel instrumentiert zu werden. Dieser Zweig enthält keinen Servletfilter oder Recorder-Konfiguration, da diese Funktionen vom Agenten ausgeführt werden. So führen Sie die Anwendung lokal aus oder verwendenAWS-Ressourcen, führen Sie die Schritte in der Readme-Datei der Beispielanwendung aus. Die Anweisungen zur Verwendung der Beispiel-App zum Generieren von Röntgenspuren finden Sie imBeispiel-App-Tutorialaus.

Erste Schritte

Gehen Sie folgendermaßen vor, um mit dem Java-Agenten für X-Ray Auto-Instrumentierung in Ihrer eigenen Anwendung zu beginnen.

  1. Führen Sie den X-Ray-Daemon in Ihrer Umgebung aus. Weitere Informationen finden Sie unterX-Ray-Daemonaus.

  2. Herunterladen desletzte Verteilung des Agentenaus. Entpacken Sie das Archiv und notieren Sie sich dessen Speicherort in Ihrem Dateisystem. Der 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-javaagent-Argumentvordie-jargegebenenfalls Argument. Der Prozess zum Ändern von JVM-Argumenten hängt von den Tools und Frameworks ab, die Sie zum Starten Ihres Java-Servers verwenden. Konkrete 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 dieAWS_XRAY_TRACING_NAMEUmgebungsvariable odercom.amazonaws.xray.strategy.tracingNamesystem-Eigenschaft. Wenn kein Name angegeben ist, wird ein Standardname verwendet.

  5. Starten Sie Ihren Server oder Container neu. Eingehende Anfragen und ihre nachgelagerten Anrufe werden jetzt verfolgt. Falls Sie die erwarteten Ergebnisse nicht sehen, finden Sie unterFehlerbehebungaus.

Konfiguration

Der X-Ray-Agent wird durch eine externe, vom Benutzer bereitgestellte JSON-Datei konfiguriert. Standardmäßig befindet sich diese Datei im Stammverzeichnis des Klassenpfads des Benutzers (z. B. inresourcesVerzeichnis) mit dem Namenxray-agent.jsonaus. Sie können einen benutzerdefinierten Speicherort für die Konfigurationsdatei konfigurieren, indem Siecom.amazonaws.xray.configFilesystemeigenschaft für den absoluten Dateisystempfad Ihrer Konfigurationsdatei.

Eine Beispielkonfigurationsdatei wird nachstehend 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 }

Spezifikation der Konfiguration

In der folgenden Tabelle werden gültige Werte für jede Eigenschaft beschrieben. Eigenschaftsnamen berücksichtigen Groß- und Kleinschreibung, ihre Schlüssel jedoch nicht. Für Eigenschaften, die durch Umgebungsvariablen und Systemeigenschaften überschrieben werden können, ist die Reihenfolge der Priorität immer die Umgebungsvariable, dann die Systemeigenschaft und dann die Konfigurationsdatei. Sehen Sie dieUmgebungsvariablenfür Informationen über Eigenschaften, die Sie überschreiben können. Alle Felder sind optional.

Name der Eigenschaft Typ Zulässige Werte Beschreibung Umgebungsvariable Systemeigenschaft Standard

serviceName

String (Zeichenfolge)

Jede Zeichenfolge

Der Name Ihres instrumentierten Dienstes, wie er in der X-Ray-Konsole angezeigt wird.

AWS_XRAY_TRACING_NAME

com.amazonaws.xray.strategy.TracingName

XrayInstrumentedService

ContextMissingStrategy

String (Zeichenfolge)

LOG_ERROR, IGNORE_ERROR

Die Aktion des Agenten, wenn er versucht, den X-Ray-Segmentkontext zu verwenden, aber keiner ist vorhanden.

AWS_XRAY_CONTEXT_FEHLT

com.amazonaws.xray.strategy.contextMissingStrategy

LOG_ERROR

DaemonAddress

String (Zeichenfolge)

Formatierte IP-Adresse und Port oder Liste der TCP- und UDP-Adresse

Die Adresse, mit der der Agent mit dem X-Ray-Daemon kommuniziert.

AWS_XRAY_DAEMON_ADRESSE

com.amazonaws.xray.Emitter.DaemonAddress

127.0.0. 1:2000

TracingEnabled

Boolesch

TRUE, FALSE

Aktiviert die Instrumentierung durch den Röntgen-Agenten.

AWS_XRAY_TRACING_ENABLED

com.amazonaws.xray.tracingenEnabled

TRUE

SamplingStrategy

String (Zeichenfolge)

ZENTRAL, LOKAL, KEINE, ALLE

Die vom Agenten verwendete Stichprobenstrategie. ALL erfasst alle Anfragen, NONE erfasst keine Anfragen. Siehe .Samplingregelnaus.

N/A

N/A

ZENTRALE

traceIdInjectionPrefix

String (Zeichenfolge)

Jede Zeichenfolge

Schließt das bereitgestellte Präfix vor injizierten Trace-IDs in Protokolle ein.

N/A

N/A

Keine (leere Zeichenfolge)

SamplingRulesManifest

String (Zeichenfolge)

Ein absoluter Dateipfad

Der Pfad zu einer benutzerdefinierten Stichprobenregeldatei, die als Quelle für Stichprobenregeln für die lokale Stichprobenstrategie oder die Fallback-Regeln für die zentrale Strategie verwendet werden soll.

N/A

N/A

DefaultSamplingRules.json

awsServiceHandlerManifest

String (Zeichenfolge)

Ein absoluter Dateipfad

Der Pfad zu einer benutzerdefinierten Parameter-Zulassungsliste, die zusätzliche Informationen erfasstAWSSDK-Clients

N/A

N/A

DefaultOperationParameterWhiteList.json

awsSdkVersion

Ganzzahl

1, 2

Version desAWSSDK für Javadu benutzt. IgnoriertawsServiceHandlerManifestist nicht auch eingestellt.

N/A

N/A

2

MaxStackTraceLength

Ganzzahl

Nicht negative Ganzzahlen

Die maximalen Zeilen einer Stack-Trace, die in einem Trace aufgezeichnet werden sollen.

N/A

N/A

50

StreamingThreshold

Ganzzahl

Nicht negative Ganzzahlen

Nachdem zumindest so viele Teilsegmente geschlossen wurden, werden sie in den Daemon Out-of-Band gestreamt, um zu vermeiden, dass Chunks zu groß sind.

N/A

N/A

100

TraceIdInjection

Boolesch

TRUE, FALSE

Aktiviert die X-Ray-Trace-ID-Injektion in Protokolle, wenn die inProtokollierungskonfigwerden ebenfalls hinzugefügt. Sonst tut nichts.

N/A

N/A

TRUE

PluginsEnabled

Boolesch

TRUE, FALSE

Aktiviert Plugins, die Metadaten über dasAWSUmgebungen, in denen Sie arbeiten. Siehe .Pluginsaus.

N/A

N/A

TRUE

collectSqlQueries

Boolesch

TRUE, FALSE

Zeichnet SQL-Abfragezeichenfolgen in SQL-Teilsegmenten auf bestmögliche Weise auf.

N/A

N/A

FALSE

ContextPropagation

Boolesch

TRUE, FALSE

Verbreitet automatisch den Röntgenkontext zwischen Threads, wenn dies zutrifft. Ansonsten,verwendet Thread Local, um Kontext zu speichern, und eine manuelle Verbreitung über Threads ist erforderlich.

N/A

N/A

TRUE

Protokollierungskonfiguration

Die Protokollstufe des X-Ray-Agenten kann auf die gleiche Weise konfiguriert werden wie das X-Ray SDK for Java. Siehe .ProtokollierungWeitere Informationen zum Konfigurieren der Protokollierung mit dem X-Ray-SDK SDK for Java.

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 benutzerdefinierten Servlet-Filter des SDK, die in erwähnt werdenNachverfolgen eingehender Anforderungensind nicht mit dem X-Ray-Agent kompatibel.

Anmerkung

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

Wenn Sie in einem Maven-Projekt arbeiten, fügen Sie die folgenden Abhängigkeiten zu Ihrempom.xmlfile.

<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 die folgenden Abhängigkeiten zu Ihrembuild.gradlefile.

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

Sie könnenBenutzerdefinierte UntersegmenteZusätzlich zuAnmerkungen, Metadaten und Benutzer-IDswährend Sie den Agenten verwenden, genau wie beim normalen SDK. Der Agent verteilt automatisch den Kontext über Threads hinweg, daher sollten keine Problemumgehungen zum Propagieren von Kontext erforderlich sein, wenn Sie mit Multithread-Anwendungen arbeiten.

Fehlerbehebung

Da der Agent eine vollautomatische Instrumentierung anbietet, kann es schwierig sein, die Ursache eines Problems zu identifizieren, wenn Probleme auftreten. Wenn der X-Ray-Agent für Sie nicht wie erwartet funktioniert, überprüfen Sie die folgenden Probleme und Lösungen. Der X-Ray Agent und das SDK verwenden Jakarta Commons Logging (JCL). Um die Protokollierungsausgabe anzuzeigen, stellen Sie sicher, dass sich eine Bridge, die JCL mit Ihrem Logging-Backend verbindet, wie im folgenden Beispiel im Klassenpfad befindet:log4j-jcloderjcl-over-slf4jaus.

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?

Wenn nicht, sehen Sie sich dieX-Ray-Daemon-Dokumentationum es 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 Nachricht beim Start Ihrer Anwendung auf INFO-Ebene protokolliert, bevor sie Anfragen entgegennimmt. Wenn diese Nachricht nicht vorhanden ist, läuft der Java-Agent nicht mit Ihrem Java-Prozess. Stellen Sie sicher, dass Sie alle Einrichtungsschritte ohne Tippfehler korrekt ausgeführt haben.

Sehen Sie in Ihren Anwendungsprotokollen mehrere Fehlermeldungen, die etwas wie „Unterdrücken“ besagenAWS X-RayKontext fehlt Ausnahme“?

Diese Fehler treten auf, weil der Agent versucht, nachgelagerte Anfragen wieAWSSDK-Anfragen oder SQL-Abfragen, aber der Agent konnte kein Segment automatisch erstellen. Wenn viele dieser Fehler auftreten, ist der Agent möglicherweise nicht das beste Werkzeug für Ihren Anwendungsfall, und Sie sollten stattdessen die manuelle Instrumentierung mit dem X-Ray SDK in Betracht ziehen. Alternativ können Sie X-Ray SDK aktivierenDebug-Protokolleum den Stack-Trace zu sehen, wo die kontextfehlenden Ausnahmen auftreten. Sie können diese Teile Ihres Codes mit benutzerdefinierten Segmenten umschließen, wodurch diese Fehler behoben werden sollen. Ein Beispiel für das Umschließen von Downstream-Anfragen mit benutzerdefinierten Segmenten finden Sie im Beispiel-Code unterInstrumentieren von Startup-Codeaus.

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

Verwendet Ihre Anwendung Multithreading?

Wenn einige Segmente, die Sie erwarten, dass sie erstellt werden, nicht in Ihrer Konsole angezeigt werden, sind möglicherweise Hintergrund-Threads in Ihrer Anwendung die Ursache. Wenn Ihre Anwendung Aufgaben mit Hintergrund-Threads ausführt, die „Feuer und Vergessen“ sind, z. B. einen einmaligen Aufruf einer Lambda-Funktion mit demAWSSDK oder regelmäßige Abfrage eines HTTP-Endpunkts, das den Agenten verwirren kann, während er den Kontext über Threads verteilt. Um zu überprüfen, ob dies Ihr Problem ist, aktivieren Sie X-Ray SDK-Debug-Protokolle und suchen Sie nach Nachrichten wie: Segment wird nicht emittiert, das benannt ist, <NAME >da es untergeordnete Teilsegmente inaus. Um dies zu umgehen, können Sie versuchen, den Hintergrund-Threads beizutreten, bevor Ihr Server zurückkehrt, um sicherzustellen, dass die gesamte darin geleistete Arbeit aufgezeichnet wird. Oder Sie können den Agenten einstellencontextPropagationKonfiguration auffalseum die Kontextpropagation in Hintergrund-Threads zu deaktivieren. Wenn Sie dies tun, müssen Sie diese Threads manuell mit benutzerdefinierten Segmenten instrumentieren oder den Kontext ignorieren, die Ausnahmen fehlen, die sie erzeugen.

Haben Sie Samplingregeln aufgestellt?

Wenn auf der X-Ray-Konsole scheinbar zufällige oder unerwartete Segmente erscheinen oder die Segmente, die Sie voraussichtlich auf der Konsole befinden, nicht vorhanden sind, treten möglicherweise ein Stichprobenproblem auf. Der X-Ray-Agent wendet zentralisierte Sampling auf alle von ihm erstellten Segmente an, wobei er die Regeln der Röntgenkonsole verwendet. Die Standardregel ist 1 Segment pro Sekunde, plus 5% der Segmente danach werden abgetastet. Dies bedeutet, dass Segmente, die schnell mit dem Agenten erstellt werden, möglicherweise nicht abgetastet werden. Um dies zu beheben, sollten Sie auf der X-Ray-Konsole benutzerdefinierte Stichprobenregeln erstellen, die die gewünschten Segmente entsprechend abrufen. Weitere Informationen finden Sie unterProbenahmeaus.