AWS X-Ray SDK für Java

Das X-Ray SDK for Java besteht aus einer Reihe von Bibliotheken für Java Webanwendungen, die Klassen und Methoden zum Generieren und Senden von Trace-Daten an den X-Ray-Daemon bereitstellen. Zu den Trace-Daten gehören Informationen über eingehende HTTP-Anfragen, die von der Anwendung bedient werden, sowie über Aufrufe, die die Anwendung mithilfe des AWS SDK, HTTP-Clients oder eines SQL-Datenbank-Connectors an Downstream-Dienste sendet. Sie können Segmente auch manuell erstellen und Debug-Informationen Anmerkungen und Metadaten hinzufügen.

Das X-Ray SDK for Java ist ein Open-Source-Projekt. Sie können das Projekt verfolgen und Issues und Pull-Requests einreichen unter GitHub: github.com/aws/ aws-xray-sdk-java

Fügen Sie zunächst AWSXRayServletFilter als Servlet-Filter hinzu, um eingehende Anforderungen zu verfolgen. Ein Servlet-Filter erstellt ein Segment. Während das Segment geöffnet ist, können Sie die SDK-Client-Methoden nutzen, um dem Segment Informationen hinzuzufügen, Untersegmente zu erstellen und nachgelagerte Aufrufe rückzuverfolgen. Das SDK erfasst auch automatisch Ausnahmen, die Ihre Anwendung ausgibt, während das Segment geöffnet ist.

Ab Version 1.3 können Sie Ihre Anwendung mit aspekt-orientierter Programmierung (AOP) in Spring instrumentieren. Das bedeutet, dass Sie Ihre Anwendung instrumentieren können, während sie läuft AWS, ohne der Laufzeit Ihrer Anwendung Code hinzufügen zu müssen.

Verwenden Sie als Nächstes das X-Ray-SDK SDK for Java, um Ihre AWS SDK for Java Clients zu instrumentieren, indem Sie das SDK Instrumentor-Untermodul in Ihre Build-Konfiguration aufnehmen. Immer wenn Sie mit einem instrumentierten Client einen Downstream AWS-Service oder eine Ressource aufrufen, zeichnet das SDK Informationen über den Anruf in einem Untersegment auf. AWS-Services und die Ressourcen, auf die Sie innerhalb der Services zugreifen, werden in der Trace-Map als Downstream-Knoten angezeigt, sodass Sie Fehler und Drosselungsprobleme bei einzelnen Verbindungen leichter identifizieren können.

Wenn Sie nicht alle Downstream-Aufrufe instrumentieren möchten AWS-Services, können Sie das Instrumentor-Untermodul weglassen und auswählen, welche Clients instrumentiert werden sollen. Instrumentieren Sie einzelne Clients, indem Sie einem TracingHandler AWS SDK-Serviceclient einen hinzufügen.

Andere Submodule des X-Ray SDK for Java bieten Instrumentierung für Downstream-Aufrufe von HTTP-Web-APIs und SQL-Datenbanken. Sie können das X-Ray-SDK SDK for Java Java-Versionen von HTTPClient und HTTPClientBuilder im Apache HTTP-Submodul verwenden, um Apache HTTP-Clients zu instrumentieren. Um SQL-Anfragen zu instrumentieren, fügen Sie der Datenquelle den SDK-Interceptor hinzu.

Nachdem Sie das SDK verwendet haben, passen Sie sein Verhalten an, indem Sie den Rekorder und den Servlet-Filter konfigurieren. Sie können Plugins zum Festhalten von Daten über die Datenverarbeitungsressourcen, auf denen Ihre Anwendung ausgeführt wird, hinzufügen, das Samplingverhalten durch Samplingregeln anpassen und Protokollebenen einrichten, um mehr oder weniger Informationen von dem SDK in Ihren Anwendungsprotokollen zu sehen.

Zeichnen Sie zusätzliche Informationen zu Anforderungen und den Aufgaben, die Ihre Anwendung ausführt, in Anmerkungen und Metadaten auf. Anmerkungen sind einfache Schlüsselwertpaare, die für die Verwendung mit Filterausdrücken indiziert werden, damit Sie nach Ablaufverfolgen mit bestimmten Daten suchen können. Metadateneinträge sind weniger einschränkend und können ganze Objekte und Arrays aufzeichnen – alle Daten, die in eine JSON zusammengefasst werden können.

Wenn Sie viele instrumentierte Clients in Ihrem Code haben, kann ein einzelnes Anfragesegment viele Untersegmente enthalten, eines für jeden Aufruf mit einem instrumentierten Client. Sie können Untersegmente organisieren und gruppieren, indem Sie Client-Aufrufe in benutzerdefinierten Untersegmenten zusammenfassen. Sie können ein benutzerdefiniertes Untersegment für eine ganze Funktion oder eine Code-Abschnitt erstellen und Metadaten und Anmerkungen im Untersegment festhalten, anstatt alles im übergeordneten Segment aufzuzeichnen.

Untermodule

Sie können das X-Ray SDK for Java von Maven herunterladen. Das X-Ray-SDK SDK for Java ist je nach Anwendungsfall in Untermodule aufgeteilt und enthält eine Materialliste für die Versionsverwaltung:

Wenn Sie Maven oder Gradle verwenden, um Ihre Anwendung zu erstellen, fügen Sie das X-Ray SDK for Java zu Ihrer Build-Konfiguration hinzu.

Eine Referenzdokumentation der Klassen und Methoden des SDK finden Sie unter AWS X-Ray SDK for Java API Reference.

Voraussetzungen

Das X-Ray SDK for Java benötigt Java 8 oder höher, Servlet API 3, das AWS SDK und Jackson.

Das SDK hängt von den folgenden Bibliotheken zur Kompilierungs- und Laufzeit ab:

Diese Abhängigkeiten werden in der pom.xml-Datei des SDK deklariert und automatisch eingefügt, wenn Sie Maven oder Gradle für die Build-Erstellung verwenden.

Wenn Sie eine Bibliothek verwenden, die im X-Ray SDK for Java enthalten ist, müssen Sie die mitgelieferte Version verwenden. Wenn Sie beispielsweise bereits zur Laufzeit von Jackson abhängen und für diese Abhängigkeit JAR-Dateien in Ihre Bereitstellung aufnehmen, müssen Sie diese JAR-Dateien entfernen, da das SDK JAR eigene Versionen von Jackson-Bibliotheken umfasst.

Abhängigkeitsmanagement

Das X-Ray SDK for Java ist bei Maven erhältlich:

Wenn Sie Ihre Anwendung mit Maven erstellen, fügen Sie das SDK als Abhängigkeit in Ihrer pom.xml-Datei hinzu.

<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>com.amazonaws</groupId>
      <artifactId>aws-xray-recorder-sdk-bom</artifactId>
      <version>2.11.0</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>
<dependencies>
  <dependency>
    <groupId>com.amazonaws</groupId>
    <artifactId>aws-xray-recorder-sdk-core</artifactId>
  </dependency>
  <dependency>
    <groupId>com.amazonaws</groupId>
    <artifactId>aws-xray-recorder-sdk-apache-http</artifactId>
  </dependency>
  <dependency>
    <groupId>com.amazonaws</groupId>
    <artifactId>aws-xray-recorder-sdk-aws-sdk</artifactId>
  </dependency>
  <dependency>
    <groupId>com.amazonaws</groupId>
    <artifactId>aws-xray-recorder-sdk-aws-sdk-instrumentor</artifactId>
  </dependency>
  <dependency>
    <groupId>com.amazonaws</groupId>
    <artifactId>aws-xray-recorder-sdk-sql-postgres</artifactId>
  </dependency>
  <dependency>
    <groupId>com.amazonaws</groupId>
    <artifactId>aws-xray-recorder-sdk-sql-mysql</artifactId>
  </dependency>
</dependencies>

Für Gradle fügen Sie das SDK als Kompilierungszeitabhängigkeit in Ihrer build.gradle-Datei hinzu.

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")
  compile("com.amazonaws:aws-xray-recorder-sdk-apache-http")
  compile("com.amazonaws:aws-xray-recorder-sdk-sql-postgres")
  compile("com.amazonaws:aws-xray-recorder-sdk-sql-mysql")
  testCompile("junit:junit:4.11")
}
dependencyManagement {
    imports {
        mavenBom('com.amazonaws:aws-java-sdk-bom:1.11.39')
        mavenBom('com.amazonaws:aws-xray-recorder-sdk-bom:2.11.0')
    }
}

Wenn Sie Elastic Beanstalk für die Bereitstellung Ihrer Anwendung verwenden, können Sie Maven oder Gradle verwenden, um bei jeder Bereitstellung eine On-Instance zu erstellen, anstatt ein großes Archiv mit all Ihren Abhängigkeiten zu erstellen und hochzuladen. Für ein Beispiel, bei dem Gradle verwendet wird, sehen Sie sich die Beispielanwendung an.

Konfiguration des X-Ray SDK for Java

Das X-Ray-SDK SDK for Java enthält eine Klasse mit dem NamenAWSXRay, die den globalen Rekorder bereitstellt. 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

Wird verwendetplugins, um Informationen über den Dienst aufzuzeichnen, der Ihre Anwendung hostet.

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

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 das Feld für das Segment festzulegen. origin Dies gibt den AWS Ressourcentyp an, auf dem Ihre Anwendung ausgeführt wird. Wenn Sie mehrere Plugins verwenden, verwendet das SDK die folgende Auflösungsreihenfolge, um den Ursprung zu bestimmen: ElasticBeanstalk > EKS > ECS > EC2.

Samplingregeln

Das SDK verwendet die Sampling-Regeln, die Sie in der X-Ray-Konsole definieren, um zu bestimmen, welche Anfragen aufgezeichnet werden sollen. Die Standardregel verfolgt die erste Anfrage jede Sekunde und fünf Prozent aller weiteren Anfragen aller Dienste, die Traces an X-Ray senden. Erstellen Sie zusätzliche Regeln in der X-Ray-Konsole, um die Menge der aufgezeichneten Daten für jede Ihrer Anwendungen anzupassen.

Das SDK wendet benutzerdefinierte Regeln in der Reihenfolge an, in der sie definiert sind. Wenn eine Anfrage mehreren benutzerdefinierten Regeln entspricht, wendet das SDK nur die erste Regel an.

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.

{
  "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
  }
}

Dieses Beispiel definiert eine benutzerdefinierte Regel und eine Standardregel. Die benutzerdefinierte Regel wendet eine Stichprobenrate von fünf Prozent an, ohne dass eine Mindestanzahl von Anfragen für Pfade verfolgt werden muss, unter /api/move/ denen Pfade verfolgt werden müssen. Die Standardregel verfolgt die erste Anfrage jede Sekunde und 10 Prozent der weiteren Anfragen.

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 Menge der aufgezeichneten Daten zu kontrollieren.

Bei AWS Lambda aktivierter Option können Sie die Samplerate nicht ändern. Wenn Ihre Funktion von einem instrumentierten Dienst aufgerufen wird, werden Aufrufe, die Anfragen generierten, die von diesem Dienst abgetastet wurden, von Lambda aufgezeichnet. Wenn aktives Tracing 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.

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.

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) { }
}

...
  <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 Meldungen auf -Ebene in Ihre Anwendungsprotokolle aus. ERROR Sie können die Protokollierung auf Debug-Ebene im SDK aktivieren, um detailliertere Protokolle in Ihrer Anwendungsprotokolldatei auszugeben. Gültige Protokollebenen sindDEBUG,, INFOWARN, ERROR und. FATAL FATALBei der Protokollebene werden alle Protokollmeldungen stummgeschaltet, da das SDK nicht auf fataler Ebene protokolliert.

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.

1-5df42873-011e96598b447dfca814c156@541b3365be3dafc3

Diese Funktion funktioniert mit Java-Anwendungen, die mit dem AWS X-Ray SDK for Java instrumentiert sind, und unterstützt die folgenden Logging-Konfigurationen:

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

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.

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

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

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.

Die vollständige Liste der SegmentListener Funktionen finden Sie in der Dokumentation für das AWS X-Ray Recorder 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.

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.

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.

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:

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

Nachverfolgung eingehender Anfragen mit dem X-Ray SDK for Java

Sie können das X-Ray SDK verwenden, um eingehende HTTP-Anfragen zu verfolgen, die Ihre Anwendung auf einer EC2-Instance in Amazon EC2 oder Amazon ECS bearbeitet. AWS Elastic Beanstalk

Verwenden Sie einen Filter, um eingehende HTTP-Anforderungen zu instrumentieren. Wenn Sie den X-Ray-Servlet-Filter zu Ihrer Anwendung hinzufügen, erstellt das X-Ray SDK for Java ein Segment für jede gesampelte Anfrage. Dieses Segment umfasst Dauer, Methode und Status der HTTP-Anforderung. Die zusätzliche Instrumentierung schafft Untersegmente zu diesem Segment.

Jedes Segment hat einen Namen, der Ihre Anwendung in der Service Map identifiziert. Das Segment kann statisch benannt werden, oder Sie können das SDK so konfigurieren, dass es dynamisch auf der Grundlage des Host-Headers in der eingehenden Anfrage benannt wird. Mit der dynamischen Benennung können Sie Traces auf der Grundlage des Domainnamens in der Anfrage gruppieren und einen Standardnamen anwenden, wenn der Name nicht einem erwarteten Muster entspricht (z. B. wenn der Host-Header gefälscht ist).

Wenn eine Anfrage weitergeleitet wird, legt das SDK ein zusätzliches Feld im Segment fest, um dies anzuzeigen. Wenn das Segment das Feld enthält, das auf x_forwarded_for gesetzt isttrue, wurde die Client-IP aus dem X-Forwarded-For Header in der HTTP-Anfrage übernommen.

Der Meldungshandler erzeugt für jede eingehende Anforderung ein Segment mit einem http-Block, der die folgenden Informationen enthält:

Hinzufügen eines Ablaufverfolgungsfilters zu Ihrer Anwendung (Tomcat)

Im Fall von Tomcat fügen Sie einen <filter> zur web.xml-Datei Ihres Projekts hinzu. Legen Sie mit dem fixedName Parameter einen Servicenamen fest, damit die erstellten Segmente auf eingehende Anforderungen angewendet werden.

<filter>
  <filter-name>AWSXRayServletFilter</filter-name>
  <filter-class>com.amazonaws.xray.javax.servlet.AWSXRayServletFilter</filter-class>
  <init-param>
    <param-name>fixedName</param-name>
    <param-value>MyApp</param-value>
  </init-param>
</filter>
<filter-mapping>
  <filter-name>AWSXRayServletFilter</filter-name>
  <url-pattern>*</url-pattern>
</filter-mapping>

Hinzufügen eines Ablaufverfolgungsfilters zu Ihrer Anwendung (Spring)

Für Spring fügen Sie einen Filter zu Ihrer WebConfig-Klasse hinzu. Übermitteln Sie den Segmentnamen als Zeichenfolge an den AWSXRayServletFilter-Konstruktor.

package myapp;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Bean;
import javax.servlet.Filter;
import com.amazonaws.xray.javax.servlet.AWSXRayServletFilter;

@Configuration
public class WebConfig {

  @Bean
  public Filter TracingFilter() {
    return new AWSXRayServletFilter("Scorekeep");
  }
}

Konfiguration einer Segmentbenennungsstrategie

AWS X-Ray verwendet einen Dienstnamen, um Ihre Anwendung zu identifizieren und sie von den anderen Anwendungen, Datenbanken, externen APIs und Ressourcen zu unterscheiden, die Ihre Anwendung verwendet. AWS Wenn das X-Ray SDK Segmente für eingehende Anfragen generiert, zeichnet es den Dienstnamen Ihrer Anwendung im Namensfeld des Segments auf.

Das X-Ray SDK kann Segmente nach dem Hostnamen im HTTP-Anforderungsheader benennen. Dieser Header kann jedoch gefälscht sein, was zu unerwarteten Knoten in Ihrer Service Map führen kann. Um zu verhindern, dass das SDK Segmente aufgrund von Anfragen mit gefälschten Host-Headern falsch benennt, müssen Sie einen Standardnamen für eingehende Anfragen angeben.

Wenn Ihre Anwendung Anfragen für mehrere Domänen bearbeitet, können Sie das SDK so konfigurieren, dass es eine dynamische Benennungsstrategie verwendet, um dies in Segmentnamen widerzuspiegeln. Eine dynamische Benennungsstrategie ermöglicht es dem SDK, den Hostnamen für Anfragen zu verwenden, die einem erwarteten Muster entsprechen, und den Standardnamen auf Anfragen anzuwenden, bei denen dies nicht der Fall ist.

Beispielsweise könnten Sie eine einzige Anwendung haben, die Anfragen an drei Subdomänen — www.example.comapi.example.com, und — bedient. static.example.com Sie können eine dynamische Benennungsstrategie mit dem Muster verwenden*.example.com, um Segmente für jede Subdomain mit einem anderen Namen zu identifizieren, was zu drei Dienstknoten auf der Service-Map führt. Wenn Ihre Anwendung Anfragen mit einem Hostnamen empfängt, der nicht dem Muster entspricht, wird auf der Service Map ein vierter Knoten mit einem von Ihnen angegebenen Fallback-Namen angezeigt.

Wenn Sie denselben Namen für alle Segmente verwenden möchten, geben Sie bei der Initialisierung des Servlet-Filters den Namen Ihrer Anwendung, wie im vorherigen Abschnitt gezeigt, ein. Dies hat den gleichen Effekt wie das Erstellen eines Fixed SegmentNamingStrategydurch Aufrufen SegmentNamingStrategy.fixed() und Übergeben an den AWSXRayServletFilterKonstruktor.

Eine dynamische Benennungsstrategie definiert ein Muster, dem Hostnamen entsprechen sollten, sowie einen Standardnamen, der verwendet wird, wenn der Hostname in der HTTP-Anforderung nicht mit diesem Muster übereinstimmt. Alternativ können Sie dynamicNamingRecognizedHosts und dynamicNamingFallbackName nutzen, um das Muster und den Standardnamen zu bestimmen und Segmente in Tomcat dynamisch zu benennen.

<filter>
  <filter-name>AWSXRayServletFilter</filter-name>
  <filter-class>com.amazonaws.xray.javax.servlet.AWSXRayServletFilter</filter-class>
  <init-param>
    <param-name>dynamicNamingRecognizedHosts</param-name>
    <param-value>*.example.com</param-value>
  </init-param>
  <init-param>
    <param-name>dynamicNamingFallbackName</param-name>
    <param-value>MyApp</param-value>
  </init-param>
</filter>
<filter-mapping>
  <filter-name>AWSXRayServletFilter</filter-name>
  <url-pattern>*</url-pattern>
</filter-mapping>

Erstellen Sie für Spring eine Dynamik, SegmentNamingStrategyindem Sie sie aufrufenSegmentNamingStrategy.dynamic(), und übergeben Sie sie an den AWSXRayServletFilter Konstruktor.

package myapp;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Bean;
import javax.servlet.Filter;
import com.amazonaws.xray.javax.servlet.AWSXRayServletFilter;
import com.amazonaws.xray.strategy.SegmentNamingStrategy;

@Configuration
public class WebConfig {

  @Bean
  public Filter TracingFilter() {
    return new AWSXRayServletFilter(SegmentNamingStrategy.dynamic("MyApp", "*.example.com"));
  }
}

Verfolgen von AWS SDK-Aufrufen mit dem X-Ray SDK for Java

Wenn Ihre Anwendung Aufrufe tätigt, um Daten AWS-Services zu speichern, in eine Warteschlange zu schreiben oder Benachrichtigungen zu senden, verfolgt das X-Ray SDK for Java die Aufrufe im Downstream in Untersegmenten. Verfolgte Ressourcen AWS-Services und Ressourcen, auf die Sie innerhalb dieser Services zugreifen (z. B. ein Amazon S3 S3-Bucket oder eine Amazon SQS SQS-Warteschlange), werden als Downstream-Knoten auf der Trace-Map in der X-Ray-Konsole angezeigt.

Das X-Ray-SDK SDK for Java instrumentiert automatisch alle AWS-SDK-Clients, wenn Sie die aws-sdk und die aws-sdk-instrumentor Submodule in Ihren Build aufnehmen. Wenn Sie das Instrumentor-Untermodul nicht einbeziehen, können Sie auswählen, welche Clients Sie instrumentieren möchten, und andere ausschließen.

Um einzelne Clients zu instrumentieren, entfernen Sie das aws-sdk-instrumentor Submodul aus Ihrem Build und fügen Sie mithilfe des Client-Builders des Services ein XRayClient AS TracingHandler auf Ihrem AWS SDK-Client hinzu.

Wenn Sie beispielsweise einen AmazonDynamoDB-Client instrumentieren möchten, übergeben Sie einen Ablaufverfolgungshandler an AmazonDynamoDBClientBuilder.

import com.amazonaws.xray.AWSXRay;
import com.amazonaws.xray.handlers.TracingHandler;

...
public class MyModel {
  private AmazonDynamoDB client = AmazonDynamoDBClientBuilder.standard()
        .withRegion(Regions.fromName(System.getenv("AWS_REGION")))
        .withRequestHandlers(new TracingHandler(AWSXRay.getGlobalRecorder()))
        .build();
...

Für alle Dienste können Sie den Namen der aufgerufenen API in der X-Ray-Konsole sehen. Für eine Untergruppe von Diensten fügt das X-Ray SDK dem Segment Informationen hinzu, um die Service Map detaillierter zu gestalten.

Wenn Sie beispielsweise einen Aufruf mit einem instrumentierten DynamoDB-Client tätigen, fügt das SDK den Tabellennamen dem Segment für Aufrufe hinzu, die auf eine Tabelle abzielen. In der Konsole wird jede Tabelle als separater Knoten in der Service Map angezeigt, mit einem generischen DynamoDB-Knoten für Aufrufe, die nicht auf eine Tabelle abzielen.

{
  "id": "24756640c0d0978a",
  "start_time": 1.480305974194E9,
  "end_time": 1.4803059742E9,
  "name": "DynamoDB",
  "namespace": "aws",
  "http": {
    "response": {
      "content_length": 60,
      "status": 200
    }
  },
  "aws": {
    "table_name": "scorekeep-user",
    "operation": "UpdateItem",
    "request_id": "UBQNSO5AEM8T4FDA4RQDEB94OVTDRVV4K4HIRGVJF66Q9ASUAAJG",
  }
}

Um Downstream-Aufrufe AWS-Services mit AWS SDK for Java 2.2 und höher zu instrumentieren, können Sie das aws-xray-recorder-sdk-aws-sdk-v2-instrumentor Modul aus Ihrer Build-Konfiguration weglassen. Fügen Sie stattdessen das aws-xray-recorder-sdk-aws-sdk-v2 module ein und instrumentieren Sie dann einzelne Clients, indem Sie sie mit einem TracingInterceptor konfigurieren.

import com.amazonaws.xray.interceptors.TracingInterceptor;
import software.amazon.awssdk.core.client.config.ClientOverrideConfiguration
import software.amazon.awssdk.services.dynamodb.DynamoDbClient;
//...
public class MyModel {
private DynamoDbClient client = DynamoDbClient.builder()
.region(Region.US_WEST_2)
.overrideConfiguration(ClientOverrideConfiguration.builder()
.addExecutionInterceptor(new TracingInterceptor())
.build()
)
.build();
//...

Rückverfolgung von Aufrufen an Downstream-HTTP-Webservices mit dem X-Ray SDK for Java

Wenn Ihre Anwendung Microservices oder öffentliche HTTP-APIs aufruft, können Sie die Version von X-Ray SDK für Java verwenden, HttpClient um diese Aufrufe zu instrumentieren und die API als Downstream-Service zum Service Graph hinzuzufügen.

Das X-Ray-SDK SDK for Java umfasst DefaultHttpClient HttpClientBuilder Klassen, die anstelle der HttpComponents Apache-Äquivalente verwendet werden können, um ausgehende HTTP-Aufrufe zu instrumentieren.

Diese Bibliotheken befinden sich im aws-xray-recorder-sdk-apache-http-Untermodul.

Sie können Ihre vorhandenen Importanweisungen durch das X-Ray-Äquivalent ersetzen, um alle Clients zu instrumentieren, oder den vollqualifizierten Namen verwenden, wenn Sie einen Client für die Instrumentierung bestimmter Clients initialisieren.

import com.fasterxml.jackson.databind.ObjectMapper;
import org.apache.http.HttpEntity;
import org.apache.http.client.methods.CloseableHttpResponse;
import org.apache.http.client.methods.HttpGet;
import org.apache.http.impl.client.CloseableHttpClient;
import org.apache.http.util.EntityUtils;
import com.amazonaws.xray.proxies.apache.http.HttpClientBuilder;
...
  public String randomName() throws IOException {
    CloseableHttpClient httpclient = HttpClientBuilder.create().build();
    HttpGet httpGet = new HttpGet("http://names.example.com/api/");
    CloseableHttpResponse response = httpclient.execute(httpGet);
    try {
      HttpEntity entity = response.getEntity();
      InputStream inputStream = entity.getContent();
      ObjectMapper mapper = new ObjectMapper();
      Map<String, String> jsonMap = mapper.readValue(inputStream, Map.class);
      String name = jsonMap.get("name");
      EntityUtils.consume(entity);
      return name;
    } finally {
      response.close();
    }
  }

Wenn Sie einen Aufruf einer Downstream-Web-API instrumentieren, zeichnet das X-Ray SDK for Java ein Untersegment mit Informationen über die HTTP-Anfrage und -Antwort auf. X-Ray verwendet das Untersegment, um ein abgeleitetes Segment für die Remote-API zu generieren.

{
  "id": "004f72be19cddc2a",
  "start_time": 1484786387.131,
  "end_time": 1484786387.501,
  "name": "names.example.com",
  "namespace": "remote",
  "http": {
    "request": {
      "method": "GET",
      "url": "https://names.example.com/"
    },
    "response": {
      "content_length": -1,
      "status": 200
    }
  }
}

{
  "id": "168416dc2ea97781",
  "name": "names.example.com",
  "trace_id": "1-62be1272-1b71c4274f39f122afa64eab",
  "start_time": 1484786387.131,
  "end_time": 1484786387.501,
  "parent_id": "004f72be19cddc2a",
  "http": {
    "request": {
      "method": "GET",
      "url": "https://names.example.com/"
    },
    "response": {
      "content_length": -1,
      "status": 200
    }
  },
  "inferred": true
}

Verfolgen von SQL-Abfragen mit dem X-Ray SDK for Java

SQL-Interzeptoren

Instrumentieren Sie SQL-Datenbankabfragen, indem Sie den X-Ray SDK for Java JDBC Interceptor zu Ihrer Datenquellenkonfiguration hinzufügen.

Diese Interceptors befinden sich im aws-xray-recorder-sql-postgres- bzw. aws-xray-recorder-sql-mysql-Untermodul. Sie implementieren org.apache.tomcat.jdbc.pool.JdbcInterceptor und sind mit Tomcat-Verbindungspools kompatibel.

Für Spring fügen Sie der Eigenschaftendatei einen Interceptor hinzu und erstellen Sie die Datenquelle mit dem DataSourceBuilder von Spring Boot.

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

import org.springframework.boot.autoconfigure.EnableAutoConfiguration;
import org.springframework.boot.autoconfigure.jdbc.DataSourceBuilder;
import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.data.jpa.repository.config.EnableJpaRepositories;

import javax.servlet.Filter;
import javax.sql.DataSource;
import java.net.URL;

@Configuration
@EnableAutoConfiguration
@EnableJpaRepositories("myapp")
public class RdsWebConfig {

  @Bean
  @ConfigurationProperties(prefix = "spring.datasource")
  public DataSource dataSource() {
      logger.info("Initializing PostgreSQL datasource");
      return DataSourceBuilder.create()
              .driverClassName("org.postgresql.Driver")
              .url("jdbc:postgresql://" + System.getenv("RDS_HOSTNAME") + ":" + System.getenv("RDS_PORT") + "/ebdb")
              .username(System.getenv("RDS_USERNAME"))
              .password(System.getenv("RDS_PASSWORD"))
              .build();
  }
...
}

Rufen Sie für Tomcat die JDBC-Datenquelle mit einem Verweis setJdbcInterceptors auf die Klasse X-Ray SDK for Java auf.

import org.apache.tomcat.jdbc.pool.DataSource;
...
DataSource source = new DataSource();
source.setUrl(url);
source.setUsername(user);
source.setPassword(password);
source.setDriverClassName("com.mysql.jdbc.Driver");
source.setJdbcInterceptors("com.amazonaws.xray.sql.mysql.TracingInterceptor;");

Die Tomcat JDBC Data Source-Bibliothek ist im X-Ray SDK for Java enthalten, aber Sie können sie als bereitgestellte Abhängigkeit von dem Dokument deklarieren, in dem Sie sie verwenden.

<dependency>
  <groupId>org.apache.tomcat</groupId>
  <artifactId>tomcat-jdbc</artifactId>
  <version>8.0.36</version>
  <scope>provided</scope>
</dependency>

Nativer SQL Tracing Decorator

Generieren von benutzerdefinierten Untersegmenten mit dem X-Ray SDK for Java

Untersegmente erweitern das Segment eines Traces um Details über die Arbeit, die zur Bearbeitung einer Anfrage geleistet wurde. Jedes Mal, wenn Sie einen Anruf mit einem instrumentierten Client tätigen, zeichnet das X-Ray-SDK die in einem Untersegment generierten Informationen auf. Sie können zusätzliche Untersegmente erstellen, um andere Untersegmente zu gruppieren, die Leistung eines Codeabschnitts zu messen oder Anmerkungen und Metadaten aufzuzeichnen.

Um Untersegmente zu verwalten, verwenden Sie die Methoden beginSubsegment und endSubsegment.

import com.amazonaws.xray.AWSXRay;
...
  public void saveGame(Game game) throws SessionNotFoundException {
    // wrap in subsegment
    Subsegment subsegment = AWSXRay.beginSubsegment("Save Game");
    try {
      // check session
      String sessionId = game.getSession();
      if (sessionModel.loadSession(sessionId) == null ) {
        throw new SessionNotFoundException(sessionId);
      }
      mapper.save(game);
    } catch (Exception e) {
      subsegment.addException(e);
      throw e;
    } finally {
      AWSXRay.endSubsegment();
    }
  }

In diesem Beispiel lädt der Code innerhalb des Untersegments die Spielsitzung aus DynamoDB mit einer Methode auf dem Sitzungsmodell und verwendet den DynamoDB-Mapper AWS SDK for Java des Spiels, um das Spiel zu speichern. Wenn Sie diesen Code in ein Untersegment einbinden, werden die Aufrufe zu DynamoDB-Unterelementen des Save Game Untersegments in der Trace-Ansicht in der Konsole.

Wenn der Code in Ihrem Untersegment geprüfte Ausnahmen auslöst, verpacken Sie ihn in einen try-Block und rufen Sie AWSXRay.endSubsegment() in einem finally-Block auf, um sicherzustellen, dass das Untersegment immer geschlossen ist. Wenn ein Untersegment nicht geschlossen ist, kann das übergeordnete Segment nicht abgeschlossen werden und wird nicht an X-Ray gesendet.

Für Code, der keine geprüften Ausnahmen auslöst, können Sie den Code AWSXRay.CreateSubsegment als Lambda-Funktion übergeben.

import com.amazonaws.xray.AWSXRay;

AWSXRay.createSubsegment("getMovies", (subsegment) -> {
    // function code
});

Wenn Sie ein Untersegment innerhalb eines Segments oder eines anderen Untersegments erstellen, generiert das X-Ray SDK for Java eine ID dafür und zeichnet die Start- und Endzeit auf.

"subsegments": [{
  "id": "6f1605cd8a07cb70",
  "start_time": 1.480305974194E9,
  "end_time": 1.4803059742E9,
  "name": "Custom subsegment for UserModel.saveUser function",
  "metadata": {
    "debug": {
      "test": "Metadata string from UserModel.saveUser"
    }
  },

Bei asynchroner Programmierung und Multithread-Programmierung müssen Sie das Teilsegment manuell an die endSubsegment() Methode übergeben, um sicherzustellen, dass es korrekt geschlossen wird, da der X-Ray-Kontext während der asynchronen Ausführung geändert werden kann. Wenn ein asynchrones Teilsegment geschlossen wird, nachdem das übergeordnete Segment geschlossen wurde, streamt diese Methode automatisch das gesamte Segment an den X-Ray-Daemon.

@GetMapping("/api")
public ResponseEntity<?> api() {
  CompletableFuture.runAsync(() -> {
      Subsegment subsegment = AWSXRay.beginSubsegment("Async Work");
      try {
          Thread.sleep(3000);
      } catch (InterruptedException e) {
          subsegment.addException(e);
          throw e;
      } finally {
          AWSXRay.endSubsegment(subsegment);
      }
  });
  return ResponseEntity.ok().build();
}

Hinzufügen von Anmerkungen und Metadaten zu Segmenten mit dem X-Ray SDK for Java

Sie können Anmerkungen und Metadaten verwenden, um zusätzliche Informationen über Anfragen, die Umgebung oder Ihre Anwendung aufzuzeichnen. Sie können Anmerkungen und Metadaten zu den Segmenten hinzufügen, die das X-Ray SDK erstellt, oder zu benutzerdefinierten Untersegmenten, die Sie erstellen.

Anmerkungen sind Schlüssel-Wert-Paare mit Zeichenfolgen-, Zahlen- oder booleschen Werten. Anmerkungen sind für die Verwendung mit Filterausdrücken indexiert. Berücksichtigen Sie Anmerkungen, um Daten zur Gruppierung von Ablaufverfolgungen in der Konsole zu verwenden, oder wenn Sie die GetTraceSummaries-API aufrufen.

Metadaten sind Schlüssel-Wert-Paare, die Werte beliebigen Typs enthalten können, einschließlich Objekte und Listen, aber nicht für die Verwendung mit Filterausdrücken indexiert sind. Verwenden Sie Metadaten, um zusätzliche Daten aufzuzeichnen, die Sie im Trace speichern möchten, aber nicht für die Suche verwenden müssen.

Zusätzlich zu Anmerkungen und Metadaten können Sie auch Benutzer-ID-Zeichenfolgen in Segmenten aufzeichnen. Benutzer-IDs werden in einem eigenen Feld aufgezeichnet und zur Suche indiziert.

Anmerkungen mit dem X-Ray SDK for Java aufnehmen

Verwenden Sie Anmerkungen, um Informationen zu Segmenten oder Untersegmenten, die zur Suche indiziert werden sollten, aufzuzeichnen.

Das SDK zeichnet Anmerkungen als Schlüssel-Wert-Paare in einem annotations-Objekt im Segmentdokument auf. Wenn putAnnotation zweimal mit demselben Schlüssel aufgerufen wird, werden zuvor aufgezeichnete Werte im gleichen Segment oder Untersegment überschrieben.

Nutzen Sie das annotations.key-Schlüsselwort in einem Filterausdruck, um Ablaufverfolgungen durch Anmerkungen mit bestimmten Werten zu finden.

import com.amazonaws.xray.AWSXRay;
import com.amazonaws.xray.entities.Segment;
import com.amazonaws.xray.entities.Subsegment;
...
  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();
    }
  }

Metadaten mit dem X-Ray SDK for Java aufzeichnen

Verwenden Sie Metadaten, um Segment- oder Untersegmentinformationen aufzuzeichnen, die nicht zur Suche indiziert werden müssen. Metadatenwerte sind Zeichenfolgen, Zahlen, boolesche Werte oder andere Objekte, die in Form eines JSON-Objekts oder eines Arrays angeordnet sein können.

Wenn Sie keinen Namespace angeben, verwendet SDK default. Wenn putMetadata zweimal mit demselben Schlüssel aufgerufen wird, werden zuvor aufgezeichnete Werte im gleichen Segment oder Untersegment überschrieben.

import com.amazonaws.xray.AWSXRay;
import com.amazonaws.xray.entities.Segment;
import com.amazonaws.xray.entities.Subsegment;
...
  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();
    }
  }

Aufzeichnen von Benutzer-IDs mit dem X-Ray SDK for Java

Zeichnen Sie Benutzer-IDs in Anforderungssegmenten auf, um den Benutzer zu identifizieren, der die Anforderung gesendet hat.

Sie können setUser in Ihrem Controller aufrufen, um die Benutzer-ID aufzuzeichnen, sobald die Anwendung mit der Bearbeitung einer Anfrage beginnt. Wenn Sie das Segment nur zur Einrichtung der Benutzer-ID verwenden, können Sie die Aufrufe in einer einzelnen Zeile anordnen.

import com.amazonaws.xray.AWSXRay;
...
  @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);
  }

Nutzen Sie das user-Schlüsselwort in einem Filterausdruck, um Ablaufverfolgungen einer Benutzer-ID zu finden.

AWS X-Ray Metriken für das X-Ray SDK for Java

In diesem Thema werden der AWS X-Ray Namespace, die Metriken und die Dimensionen beschrieben. Sie können das X-Ray SDK for Java verwenden, um CloudWatch Amazon-Metriken ohne Stichproben aus Ihren gesammelten X-Ray-Segmenten zu veröffentlichen. Diese Metriken werden von der Start- und Endzeit des Segments sowie den Status-Flags für Fehler, Ausfall und Ablehnung abgeleitet. Mit diesen Trace-Metriken können Sie Wiederholungen und Abhängigkeitsprobleme in Teilsegmenten anzeigen.

CloudWatch ist ein Metrik-Repository. Eine Metrik ist das grundlegende Konzept von Datenpunkten CloudWatch und stellt eine zeitlich geordnete Menge von Datenpunkten dar. Sie (oder AWS-Services) veröffentlichen Metrikdatenpunkte in CloudWatch und rufen Statistiken über diese Datenpunkte als geordneten Satz von Zeitreihendaten ab.

Metriken werden eindeutig durch einen Namen, ein Namespace und eine oder mehrere Dimensionen definiert. Jeder Datenpunkt verfügt über einen Zeitstempel und optional über eine Maßeinheit. Wenn Sie Statistiken anfordern, wird der zurückgegebene Datenstrom durch den Namespace, den Metrik-Namen und die Dimension identifiziert.

Weitere Informationen zu CloudWatch finden Sie im CloudWatch Amazon-Benutzerhandbuch.

CloudWatch Röntgenmetriken

Der ServiceMetrics/SDK-Namespace enthält die folgenden Metriken.

CloudWatch Röntgenabmessungen

Verwenden Sie die Dimensionen in der folgenden Tabelle, um die für Ihre Java Anwendungen mit Röntgeninstrumenten zurückgegebenen Metriken zu verfeinern.

CloudWatch X-Ray-Metriken aktivieren

Gehen Sie wie folgt vor, um Trace-Metriken in Ihrer instrumentierten Java Anwendung zu aktivieren.

Übermitteln von Segmentkontext zwischen Threads in einer Multithread-Anwendung

Beim Erstellen eines neuen Threads in Ihrer Anwendung behält AWSXRayRecorder eine Referenz zur aktuellen Segment- oder Untersegment-Entity nicht bei. Wenn Sie im neuen Thread einen instrumentierten Client verwenden, versucht das SDK, in ein Segment zu schreiben, das nicht existiert, was zu einem führt. SegmentNotFoundException

Um zu vermeiden, dass während der Entwicklung Ausnahmen ausgelöst werden, können Sie den Rekorder so konfigurieren ContextMissingStrategy, dass er stattdessen einen Fehler protokollieren soll. Sie können die Strategie im Code mit einer SetContextMissingStrategyUmgebungsvariablen oder einer Systemeigenschaft konfigurieren oder entsprechende Optionen konfigurieren.

Eine Möglichkeit zur Behebung des Fehlers ist die Verwendung eines neuen Segments, indem Sie beginSegment aufrufen, wenn Sie den Thread starten, und endSegment, wenn Sie ihn schließen. Dies funktioniert, wenn Sie Code instrumentieren, der nicht als Reaktion auf eine HTTP-Anforderung ausgeführt wird, z. B. Code, der beim Starten Ihrer Anwendung ausgeführt wird.

Wenn Sie mehrere Threads zur Verarbeitung eingehender Anfragen verwenden, können Sie das aktuelle Segment oder Untersegment an den neuen Thread übergeben und für die globale Aufzeichnung bereitstellen. Auf diese Weise wird sichergestellt, dass die im neuen Thread aufgezeichneten Informationen mit demselben Segment verknüpft werden wie die übrigen zu dieser Anfrage aufgezeichneten Informationen. Sobald das Segment im neuen Thread verfügbar ist, können Sie mithilfe der Methode jedes Runnable ausführen, das Zugriff auf den segment.run(() -> { ... }) Kontext dieses Segments hat.

Ein Beispiel finden Sie unter Verwenden instrumentierter Clients in Auftragnehmer-Threads.

X-Ray mit asynchroner Programmierung verwenden

Das X-Ray SDK for Java kann in asynchronen Java-Programmen mit SegmentContextExecutorsverwendet werden. Das SegmentContextExecutor implementiert das Executor-Interface, was bedeutet, dass es an alle asynchronen Operationen von a übergeben werden kann. CompletableFuture Dadurch wird sichergestellt, dass alle asynchronen Operationen mit dem richtigen Segment in ihrem Kontext ausgeführt werden.

DynamoDbAsyncClient client = DynamoDbAsyncClient.create();

AWSXRay.beginSegment();

// ...

client.getItem(request).thenComposeAsync(response -> {
    // If we did not provide the segment context executor, this request would not be traced correctly.
    return client.getItem(request2);
}, SegmentContextExecutors.newSegmentContextExecutor());

AOP mit Spring und dem X-Ray SDK for Java

In diesem Thema wird beschrieben, wie Sie das X-Ray SDK und das Spring Framework verwenden, um Ihre Anwendung zu instrumentieren, ohne ihre Kernlogik zu ändern. Das bedeutet, dass es jetzt eine nichtinvasive Methode zur Instrumentierung Ihrer Anwendungen gibt, die remote ausgeführt werden. AWS

Konfigurieren von Spring

Sie können Maven oder Gradle verwenden, um Spring zu konfigurieren, um AOP für die Instrumentierung Ihrer Anwendung verwenden zu können.

Wenn Sie Ihre Anwendung mit Maven erstellen, fügen Sie die folgende Abhängigkeit in Ihrer pom.xml-Datei hinzu.

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

Für Gradle fügen Sie die folgende Abhängigkeit in Ihre build.gradle-Datei ein.

compile 'com.amazonaws:aws-xray-recorder-sdk-spring:2.11.0'

Spring Boot konfigurieren

Wenn Sie Spring Boot verwenden, fügen Sie zusätzlich zu der im vorherigen Abschnitt beschriebenen Spring-Abhängigkeit die folgende Abhängigkeit hinzu, sofern sie nicht bereits in Ihrem Klassenpfad enthalten ist.

Maven:

<dependency> 
     <groupId>org.springframework.boot</groupId> 
     <artifactId>spring-boot-starter-aop</artifactId> 
     <version>2.5.2</version> 
</dependency>

Gradle:

compile 'org.springframework.boot:spring-boot-starter-aop:2.5.2'

Hinzufügen eines Tracing-Filters zu Ihrer Anwendung

Fügen Sie Ihrer WebConfig Klasse eine Filter hinzu. Übermitteln Sie den Segmentnamen als Zeichenfolge an den AWSXRayServletFilter-Konstruktor. Weitere Informationen zur Verfolgung von Filtern und zur Instrumentierung eingehender Anfragen finden Sie unter. Nachverfolgung eingehender Anfragen mit dem X-Ray SDK for Java

package myapp;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Bean;
import javax.servlet.Filter;
import com.amazonaws.xray.javax.servlet.AWSXRayServletFilter;

@Configuration
public class WebConfig {

  @Bean
  public Filter TracingFilter() {
    return new AWSXRayServletFilter("Scorekeep");
  }
}

Jakarta-Unterstützung

Spring 6 verwendet Jakarta anstelle von Javax für seine Enterprise Edition. Um diesen neuen Namespace zu unterstützen, hat X-Ray einen parallel Satz von Klassen erstellt, die in ihrem eigenen Jakarta-Namespace leben.

Ersetzen Sie für die Filterklassen durch. javax jakarta Wenn Sie eine Segmentbenennungsstrategie konfigurieren, fügen Sie jakarta vor der Benennungsstrategie den Klassennamen hinzu, wie im folgenden Beispiel:

package myapp;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Bean;
import jakarta.servlet.Filter;
import com.amazonaws.xray.jakarta.servlet.AWSXRayServletFilter;
import com.amazonaws.xray.strategy.jakarta.SegmentNamingStrategy;

@Configuration
public class WebConfig {
    @Bean
    public Filter TracingFilter() {
        return new AWSXRayServletFilter(SegmentNamingStrategy.dynamic("Scorekeep"));
    }
}

Kommentieren Ihres Codes oder Implementieren einer Schnittstelle

Ihre Klassen müssen entweder mit der @XRayEnabled Anmerkung versehen sein oder die XRayTraced Schnittstelle implementieren. Damit wird das AOP-System angewiesen, die Funktionen der betroffenen Klasse für die X-Ray-Instrumentierung zu kapseln.

X-Ray in Ihrer Anwendung aktivieren

Um X-Ray Tracing in Ihrer Anwendung zu aktivieren, muss Ihr Code die abstrakte Klasse erweitern, BaseAbstractXRayInterceptor indem er die folgenden Methoden überschreibt.

Wenn Ihr Projekt Spring Data JPA verwendet, sollten Sie eine Erweiterung von AbstractXRayInterceptor anstelle von in Betracht ziehen. BaseAbstractXRayInterceptor

Beispiel

Der folgende Code erweitert die abstrakte KlasseBaseAbstractXRayInterceptor.

@Aspect
@Component
public class XRayInspector extends BaseAbstractXRayInterceptor {    
    @Override    
    protected Map<String, Map<String, Object>> generateMetadata(ProceedingJoinPoint proceedingJoinPoint, Subsegment subsegment) throws Exception {      
        return super.generateMetadata(proceedingJoinPoint, subsegment);    
    }    
  
  @Override    
  @Pointcut("@within(com.amazonaws.xray.spring.aop.XRayEnabled) && bean(*Controller)")    
  public void xrayEnabledClasses() {}
  
}

Der folgenden Code ist eine Klasse, die von X-Ray instrumentiert wird.

@Service
@XRayEnabled
public class MyServiceImpl implements MyService {    
    private final MyEntityRepository myEntityRepository;    
    
    @Autowired    
    public MyServiceImpl(MyEntityRepository myEntityRepository) {        
        this.myEntityRepository = myEntityRepository;    
    }    
    
    @Transactional(readOnly = true)    
    public List<MyEntity> getMyEntities(){        
        try(Stream<MyEntity> entityStream = this.myEntityRepository.streamAll()){            
            return entityStream.sorted().collect(Collectors.toList());        
        }    
    }
}

Wenn Sie Ihre Anwendung ordnungsgemäß konfiguriert haben, sollten Sie den vollständigen Aufruf-Stack der Anwendung sehen, vom Controller bis zu den Service-Aufrufe, wie im folgenden Screenshot der Konsole gezeigt.