Konfigurieren des X-Ray SDK for 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.

Konfigurieren des X-Ray SDK for Java

Das X-Ray SDK for Java enthält eine Klasse mit dem NamenAWSXRaydas stellt den globalen Rekorder bereit. Dies ist ein 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.

Service-Plugins

Verwenden vonpluginsum Informationen über den Dienst aufzuzeichnen, der Ihre Anwendung hostet.

Plug-ins

  • Amazon EC2 -2 -EC2Pluginfügt die Instanz-ID, Availability Zone und CloudWatch Protokollgruppe.

  • Elastic Beanstalk -ElasticBeanstalkPluginfügt den Umgebungsnamen, die Versionsbezeichnung und die Bereitstellungs-ID hinzu.

  • Amazon ECS -2ECSPluginfügt die Container-ID hinzu.

  • Amazon EKS -EKSPluginfügt die Container-ID, den Clusternamen, die Pod-ID und CloudWatch Protokollgruppe.


        Segmentieren Sie Ressourcendaten mit Amazon EC2- und Elastic Beanstalk Beanstalk-Plugins.

Um ein Plugin zu verwenden, rufen Sie withPlugin im AWSXRayRecorderBuilder auf.

Beispiel src/main/java/scorekeep/WebConfig.java - Rekorder

import com.amazonaws.xray.AWSXRay; import com.amazonaws.xray.AWSXRayRecorderBuilder; import com.amazonaws.xray.plugins.EC2Plugin; import com.amazonaws.xray.plugins.ElasticBeanstalkPlugin; import com.amazonaws.xray.strategy.sampling.LocalizedSamplingStrategy; @Configuration public class WebConfig { ... static { AWSXRayRecorderBuilder builder = AWSXRayRecorderBuilder.standard().withPlugin(new EC2Plugin()).withPlugin(new ElasticBeanstalkPlugin()); URL ruleFile = WebConfig.class.getResource("/sampling-rules.json"); builder.withSamplingStrategy(new LocalizedSamplingStrategy(ruleFile)); AWSXRay.setGlobalRecorder(builder.build()); } }

Das SDK verwendet auch Plugin-Einstellungen, um dieoriginFeld im Segment. Dies gibt den Typ der AWS-Ressource an, auf der Ihre Anwendung ausgeführt wird. Der Ressourcentyp wird unter dem Namen Ihrer Anwendung in der Service Map angezeigt. Zum Beispiel AWS::ElasticBeanstalk::Environment.

Dienstknoten mit Ressourcentyp.

Wenn Sie mehrere Plugins verwenden, verwendet das SDK die folgende Auflösungsreihenfolge, um den Ursprung zu ermitteln: ElasticBeanstalk > EKS > ECS > EC2.

Samplingregeln

Das SDK verwendet die in der X-Ray-Konsole definierten Sampling-Regeln, um zu bestimmen, welche Anforderungen aufgezeichnet werden sollen. Die Standardregel verfolgt jede Sekunde die erste Anforderung und fünf Prozent aller zusätzlichen Anforderungen über alle Dienste hinweg, die Traces an X-Ray senden. Erstellen Sie zusätzliche Regeln in der X-Ray-Konsoleum die für jede Ihrer Anwendungen aufgezeichnete Datenmenge anzupassen.

Das SDK wendet benutzerdefinierte Regeln in der Reihenfolge an, in der sie definiert sind. Wenn eine Anforderung mit mehreren benutzerdefinierten Regeln übereinstimmt, wendet das SDK nur die erste Regel an.

Anmerkung

Wenn das SDK X-Ray nicht erreichen kann, um Sampling-Regeln abzurufen, wird es auf eine lokale Standardregel für die erste Anforderung pro Sekunde und auf fünf Prozent aller zusätzlichen Anforderungen pro Host zurückgesetzt. Dies kann auftreten, wenn der Host keine Berechtigung zum Aufrufen von Sampling-APIs hat oder keine Verbindung zum X-Ray-Daemon herstellen kann, der als TCP-Proxy für API-Aufrufe vom SDK fungiert.

Sie können das SDK auch so konfigurieren, dass Sampling-Regeln aus einem JSON-Dokument geladen werden. Das SDK kann lokale Regeln als Backup für Fälle verwenden, in denen X-Ray-Sampling nicht verfügbar ist, oder ausschließlich lokale Regeln verwenden.

Beispiel sampling-rules.json

{ "version": 2, "rules": [ { "description": "Player moves.", "host": "*", "http_method": "*", "url_path": "/api/move/*", "fixed_target": 0, "rate": 0.05 } ], "default": { "fixed_target": 1, "rate": 0.1 } }

In diesem Beispiel werden eine benutzerdefinierte Regel und eine Standardregel definiert. Die benutzerdefinierte Regel wendet eine Abtastrate von fünf Prozent an, ohne dass die Mindestanzahl von Anforderungen für die Verfolgung von Pfaden unter/api/move/. Die Standardregel verfolgt jede Sekunde die erste Anforderung und 10 Prozent aller weiteren Anforderungen.

Der Nachteil der lokalen Definition von Regeln besteht darin, dass das feste Ziel von jeder Instanz des Rekorders unabhängig angewendet wird, anstatt vom X-Ray-Dienst verwaltet zu werden. Wenn Sie mehr Hosts bereitstellen, wird die feste Rate vervielfacht, wodurch es schwieriger wird, die aufgezeichnete Datenmenge zu kontrollieren.

EinAWS Lambdakönnen Sie die Abtastrate nicht ändern. Wenn Ihre Funktion von einem instrumentierten Dienst aufgerufen wird, werden Aufrufe, die Anforderungen generiert haben, die von diesem Dienst abgetastet wurden, von Lambda aufgezeichnet. Wenn die aktive Ablaufverfolgung aktiviert ist und kein Tracing-Header vorhanden ist, trifft Lambda die Stichprobenentscheidung.

Um Sicherungsregeln in Spring bereitzustellen, konfigurieren Sie den globalen Recorder mit einer CentralizedSamplingStrategy in einer Konfigurationsklasse.

Beispiel src/main/java/myapp/WebConfig.java - Rekorder-Konfiguration

import com.amazonaws.xray.AWSXRay; import com.amazonaws.xray.AWSXRayRecorderBuilder; import com.amazonaws.xray.javax.servlet.AWSXRayServletFilter; import com.amazonaws.xray.plugins.EC2Plugin; import com.amazonaws.xray.strategy.sampling.LocalizedSamplingStrategy; @Configuration public class WebConfig { static { AWSXRayRecorderBuilder builder = AWSXRayRecorderBuilder.standard().withPlugin(new EC2Plugin()); URL ruleFile = WebConfig.class.getResource("/sampling-rules.json"); builder.withSamplingStrategy(new CentralizedSamplingStrategy(ruleFile)); AWSXRay.setGlobalRecorder(builder.build()); }

Für Tomcat fügen Sie einen Listener hinzu, der ServletContextListener erweitert, und registrieren den Listener in der Bereitstellungsbeschreibung.

Beispiel src/com/myapp/web/Startup.java

import com.amazonaws.xray.AWSXRay; import com.amazonaws.xray.AWSXRayRecorderBuilder; import com.amazonaws.xray.plugins.EC2Plugin; import com.amazonaws.xray.strategy.sampling.LocalizedSamplingStrategy; import java.net.URL; import javax.servlet.ServletContextEvent; import javax.servlet.ServletContextListener; public class Startup implements ServletContextListener { @Override public void contextInitialized(ServletContextEvent event) { AWSXRayRecorderBuilder builder = AWSXRayRecorderBuilder.standard().withPlugin(new EC2Plugin()); URL ruleFile = Startup.class.getResource("/sampling-rules.json"); builder.withSamplingStrategy(new CentralizedSamplingStrategy(ruleFile)); AWSXRay.setGlobalRecorder(builder.build()); } @Override public void contextDestroyed(ServletContextEvent event) { } }

Beispiel WEB-INF/web.xml

... <listener> <listener-class>com.myapp.web.Startup</listener-class> </listener>

Um nur lokale Regeln zu verwenden, ersetzen Sie die CentralizedSamplingStrategy durch eine LocalizedSamplingStrategy.

builder.withSamplingStrategy(new LocalizedSamplingStrategy(ruleFile));

Protokollierung

Standardmäßig gibt das SDK ausERROR-Level-Meldungen an Ihre Anwendungsprotokolle. Sie können die Protokollierung auf Debug-Ebene im SDK aktivieren, um detailliertere Protokolle in Ihre Anwendungsprotokolldatei auszugeben. Gültige Protokollstufen sindDEBUG,INFO,WARN,ERROR, undFATAL.FATALAuf Protokollebene werden alle Protokollmeldungen stummgeschaltet, da das SDK nicht auf fataler Ebene protokolliert.

Beispiel application.properties

Legen Sie die Protokollierungsebene mit der logging.level.com.amazonaws.xray-Eigenschaft fest.

logging.level.com.amazonaws.xray = DEBUG

Verwenden Sie Debug-Protokolle, um Probleme wie nicht geschlossene Untersegmente zu identifizieren, wenn Sie Untersegmente manuell generieren.

Trace-ID-Injection in Protokolle

Wenn Sie den Protokollanweisungen Ihre aktuelle vollqualifizierte Trace-ID zur Verfügung stellen möchten, können Sie die ID in den zugeordneten Diagnosekontext (MDC) einfügen. Über die SegmentListener-Schnittstelle werden Methoden während der Ereignisse des Segmentlebenszyklus aus dem X-Ray-Recorder aufgerufen. Wenn ein Segment oder Teilsegment beginnt, wird die qualifizierte Trace-ID mit dem Schlüssel AWS-XRAY-TRACE-ID in den MDC injiziert. Wenn dieses Segment endet, wird der Schlüssel aus dem MDC entfernt. Dadurch wird die Trace-ID der verwendeten Protokollierungsbibliothek verfügbar gemacht. Wenn ein Teilsegment endet, wird seine übergeordnete ID in den MDC injiziert.

Beispiel vollqualifizierte Trace-ID

Die vollqualifizierte ID wird als TraceID@EntityID dargestellt.

1-5df42873-011e96598b447dfca814c156@541b3365be3dafc3

Diese Funktion funktioniert mit Java-Anwendungen, die mitAWSX-Ray SDK for Java und unterstützt die folgenden Protokollkonfigurationen:

  • SLF4J Frontend-API mit Logback-Backend

  • SLF4J Frontend-API mit Log4J2-Backend

  • Log4J2 Frontend-API mit Log4J2-Backend

In den folgenden Registerkarten finden Sie die Anforderungen jedes Frontends und jedes Backends.

SLF4J Frontend
  1. Fügen Sie Ihrem Projekt die folgende Maven-Abhängigkeit hinzu.

    <dependency> <groupId>com.amazonaws</groupId> <artifactId>aws-xray-recorder-sdk-slf4j</artifactId> <version>2.11.0</version> </dependency>
  2. Schließen Sie beim Erstellen von AWSXRayRecorder die withSegmentListener-Methode ein. Dadurch wird eine SegmentListener-Klasse hinzugefügt, die automatisch neue Trace-IDs in das SLF4J MDC einfügt.

    Der SegmentListener akzeptiert eine optionale Zeichenfolge als Parameter, um das Präfix der Log-Anweisung zu konfigurieren. Das Präfix kann auf folgende Weise konfiguriert werden:

    • Keine-verwendet den Standard-.AWS-XRAY-TRACE-IDpräfix.

    • Leer-verwendet einen leeren String (z."") enthalten.

    • Benutzerdefiniert— Verwendet ein benutzerdefiniertes Präfix, wie in der Zeichenfolge definiert.

    Beispiel AWSXRayRecorderBuilder-Anweisung

    AWSXRayRecorderBuilder builder = AWSXRayRecorderBuilder .standard().withSegmentListener(new SLF4JSegmentListener("CUSTOM-PREFIX"));
Log4J2 front end
  1. Fügen Sie Ihrem Projekt die folgende Maven-Abhängigkeit hinzu.

    <dependency> <groupId>com.amazonaws</groupId> <artifactId>aws-xray-recorder-sdk-log4j</artifactId> <version>2.11.0</version> </dependency>
  2. Schließen Sie beim Erstellen von AWSXRayRecorder die withSegmentListener-Methode ein. Auf diese Weise wird eine SegmentListener-Klasse hinzugefügt, die automatisch neue vollqualifizierte Trace-IDs in das SLF4J MDC einfügt.

    Der SegmentListener akzeptiert eine optionale Zeichenfolge als Parameter, um das Präfix der Log-Anweisung zu konfigurieren. Das Präfix kann auf folgende Weise konfiguriert werden:

    • Keine-verwendet den Standard-.AWS-XRAY-TRACE-IDpräfix.

    • Leer-verwendet einen leeren String (z."") und entfernt das Präfix.

    • Benutzerdefiniert— Verwendet das benutzerdefinierte Präfix, das in der Zeichenfolge definiert ist.

    Beispiel AWSXRayRecorderBuilder-Anweisung

    AWSXRayRecorderBuilder builder = AWSXRayRecorderBuilder .standard().withSegmentListener(new Log4JSegmentListener("CUSTOM-PREFIX"));
Logback backend

Um die Trace-ID in die Protokollereignisse einzufügen, müssen Sie das PatternLayout des Loggers ändern, der jede Protokollierungsanweisung formatiert.

  1. Suchen Sie, wo das patternLayout konfiguriert ist. Sie können dies programmgesteuert oder über eine XML-Konfigurationsdatei erreichen. Weitere Informationen finden Sie unter Logback-Konfiguration.

  2. Fügen Sie %X{AWS-XRAY-TRACE-ID} an einer beliebigen Stelle in patternLayout ein, um die Trace-ID in zukünftige Protokollierungsanweisungen einzufügen. %X{} gibt an, dass Sie mit dem aus dem MDC bereitgestellten Schlüssel einen Wert abrufen. Für weitere Informationen über PatternLayouts finden Sie unter Protokollback unterPatternLayout.

Log4J2 backend
  1. Suchen Sie, wo das patternLayout konfiguriert ist. Sie können dies programmgesteuert oder über eine im XML-, JSON-, YAML- oder Eigenschaftenformat geschriebene Konfigurationsdatei erreichen.

    Weitere Informationen zum Konfigurieren von Log4J2 über eine Konfigurationsdatei finden Sie unter Konfiguration.

    Weitere Informationen zur programmgesteuerten Konfiguration von Log4J2 finden Sie unter Programmatische Konfiguration.

  2. Fügen Sie %X{AWS-XRAY-TRACE-ID} an einer beliebigen Stelle in PatternLayout ein, um die Trace-ID in zukünftige Protokollierungsanweisungen einzufügen. %X{} gibt an, dass Sie mit dem aus dem MDC bereitgestellten Schlüssel einen Wert abrufen. Für weitere Informationen über PatternLayoutsin Log4J2 siehePattern Layout.

Beispiel für Trace-ID-Injection

Im Folgenden wird eine PatternLayout-Zeichenfolge angezeigt, die geändert wurde, sodass die Trace-ID enthalten ist. Die Trace-ID wird nach dem Thread-Namen (%t) und vor der Protokollebene (%-5p) ausgegeben.

Beispiel PatternLayout mit ID-Injection

%d{HH:mm:ss.SSS} [%t] %X{AWS-XRAY-TRACE-ID} %-5p %m%n

AWS X-Ray gibt automatisch den Schlüssel und die Trace-ID in der Protokollanweisung aus, um die Analyse zu erleichtern. Im Folgenden wird eine Protokollanweisung dargestellt, die das modifizierte PatternLayout verwendet.

Beispiel Protokollanweisung mit ID-Injection

2019-09-10 18:58:30.844 [nio-5000-exec-4] AWS-XRAY-TRACE-ID: 1-5d77f256-19f12e4eaa02e3f76c78f46a@1ce7df03252d99e1 WARN 1 - Your logging message here

Die Protokollierungsnachricht selbst ist im Muster %m eingebettet und wird beim Aufruf des Loggers festgelegt.

Segment-Listeners

Segment-Listeners sind eine Schnittstelle zum Abfangen von Lebenszyklusereignissen, wie Anfang und Ende von Segmenten, die von AWSXRayRecorder erstellt werden. Die Implementierung einer Segment-Listener-Ereignisfunktion könnte darin bestehen, allen Teilsegmenten dieselbe Anmerkung hinzuzufügen, wenn sie mit onBeginSubsegment erstellt werden, eine Meldung zu protokollieren, nachdem jedes Segment mit afterEndSegment an den Daemon gesendet wurde, oder von SQL Interceptors mit beforeEndSubsegment gesendete Abfragen aufzuzeichnen, um zu überprüfen, ob das Teilsegment eine SQL-Abfrage darstellt, wobei zusätzliche Metadaten hinzugefügt werden, falls dies der Fall ist.

Sehen Sie die vollständige Liste derSegmentListenerFunktionen finden Sie in der Dokumentation zumAWS X-RayRekorder SDK for Java API.

Das folgende Beispiel zeigt, wie Sie allen Teilsegmenten bei der Erstellung eine konsistente Anmerkung mit onBeginSubsegment hinzufügen und mit afterEndSegment eine Protokollmeldung am Ende jedes Segments drucken.

Beispiel MySegmentListener.java-Version

import com.amazonaws.xray.entities.Segment; import com.amazonaws.xray.entities.Subsegment; import com.amazonaws.xray.listeners.SegmentListener; public class MySegmentListener implements SegmentListener { ..... @Override public void onBeginSubsegment(Subsegment subsegment) { subsegment.putAnnotation("annotationKey", "annotationValue"); } @Override public void afterEndSegment(Segment segment) { // Be mindful not to mutate the segment logger.info("Segment with ID " + segment.getId()); } }

Dieser benutzerdefinierte Segment-Listener wird dann beim Erstellen des AWSXRayRecorder referenziert.

Beispiel AWSXRayRecorderBuilder Aussage

AWSXRayRecorderBuilder builder = AWSXRayRecorderBuilder .standard().withSegmentListener(new MySegmentListener());

Umgebungsvariablen

Sie können Umgebungsvariablen verwenden, um das X-Ray SDK for Java zu konfigurieren. Das SDK unterstützt die folgenden Variablen.

  • AWS_XRAY_TRACING_NAME— Legen Sie einen Dienstnamen fest, den das SDK für Segmente verwendet. Überschreibt den für die Segmentbenennungsstrategie des Servlet-Filters festgelegten Dienstnamen.

  • AWS_XRAY_DAEMON_ADDRESS— Stellen Sie den Host und den Port des X-Ray-Daemon-Listeners ein. Standardmäßig verwendet das SDK127.0.0.1:2000sowohl für Trace-Daten (UDP) als auch für Sampling (TCP). Verwenden Sie diese Variable, wenn Sie den Daemon konfiguriert habenauf einem anderen Port hörenoder wenn es auf einem anderen Host läuft.

    Format

    • Gleicher Portaddress:port

    • Verschiedene Porttcp:address:port udp:address:port

  • AWS_XRAY_CONTEXT_MISSING-Setzen Sie aufLOG_ERRORum zu vermeiden, dass Ausnahmen ausgelöst werden, wenn Ihr instrumentierter Code versucht, Daten aufzuzeichnen, wenn kein Segment geöffnet ist.

    Zulässige Werte

    • RUNTIME_ERROR— Löst eine Laufzeitausnahme aus (Standard).

    • LOG_ERROR— Einen Fehler protokollieren und fortfahren.

    Fehler im Zusammenhang mit fehlenden Segmenten oder Untersegmenten können auftreten, wenn Sie versuchen, einen instrumentierten Client im Startcode zu verwenden, der ausgeführt wird, wenn keine Anforderung geöffnet ist, oder in Code, der einen neuen Thread erzeugt.

Umgebungsvariablen überschreiben äquivalente Systemeigenschaften und Werte in Code.

Systemeigenschaften

Sie können Systemeigenschaften als JVM-spezifische Alternative zu Umgebungsvariablen verwenden. Das SDK unterstützt die folgenden Eigenschaften:

  • com.amazonaws.xray.strategy.tracingName-Äquivalent mitAWS_XRAY_TRACING_NAME.

  • com.amazonaws.xray.emitters.daemonAddress-Äquivalent mitAWS_XRAY_DAEMON_ADDRESS.

  • com.amazonaws.xray.strategy.contextMissingStrategy-Äquivalent mitAWS_XRAY_CONTEXT_MISSING.

Wenn eine Systemeigenschaft und die entsprechende Umgebungsvariable eingerichtet sind, wird der Wert der Umgebungsvariablen verwendet. Bei beiden Methoden werden Werte in Code überschrieben.