AWS X-Ray SDK for Java

X-Ray SDK for Java ist eine 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 von HTTP Clients oder einem SQL Datenbank-Connector an nachgeschaltete Dienste sendet. AWS SDK Sie können Segmente auch manuell erstellen und Debug-Informationen Anmerkungen und Metadaten hinzufügen.

Das X-Ray SDK für Java ist ein Open-Source-Projekt. Du kannst 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. Solange das Segment geöffnet ist, kannst du die Methoden des SDK Clients verwenden, um dem Segment Informationen hinzuzufügen und Untersegmente zu erstellen, um Downstream-Aufrufe zu verfolgen. Das zeichnet SDK auch automatisch Ausnahmen auf, die Ihre Anwendung auslöst, während das Segment geöffnet ist.

Ab Version 1.3 können Sie Ihre Anwendung mit aspektorientierter 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 hinzuzufügen.

Verwenden Sie als Nächstes X-Ray SDK für Java, um Ihre AWS SDK for Java Clients zu instrumentieren, indem Sie das SDK Instrumentor-Submodul in Ihre Build-Konfiguration aufnehmen. Immer wenn Sie mit einem instrumentierten Client einen Downstream AWS-Service oder eine Ressource aufrufen, SDK zeichnet der Client 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 Service-Client einen hinzufügen.

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

Nachdem Sie den verwendet habenSDK, passen Sie sein Verhalten an, indem Sie den Rekorder und den Servlet-Filter konfigurieren. Sie können Plugins hinzufügen, um Daten über die Rechenressourcen aufzuzeichnen, auf denen Ihre Anwendung ausgeführt wird, das Sampling-Verhalten durch Definition von Sampling-Regeln anpassen und die Protokollebene so einstellen, dass mehr oder weniger Informationen aus den SDK Anwendungsprotokollen angezeigt werden.

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 restriktiv und können ganze Objekte und Arrays aufzeichnen — alles, in das serialisiert werden kann. JSON

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 für Java von Maven herunterladen. Das X-Ray SDK für Java ist je nach Anwendungsfall in Submodule aufgeteilt und enthält eine Materialliste für die Versionsverwaltung:

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

Eine Referenzdokumentation der Klassen und Methoden SDK von finden Sie unter AWS X-Ray SDKAPIJava-Referenz.

Voraussetzungen

Das X-Ray SDK für Java benötigt Java 8 oder höher, Servlet API 3 AWS SDK, The und Jackson.

Das SDK hängt bei der Kompilierung und Laufzeit von den folgenden Bibliotheken ab:

Diese Abhängigkeiten sind in der SDK pom.xml 's-Datei deklariert und werden automatisch aufgenommen, wenn Sie mit Maven oder Gradle bauen.

Wenn Sie eine Bibliothek verwenden, die in X-Ray SDK für Java enthalten ist, müssen Sie die mitgelieferte Version verwenden. Wenn Sie beispielsweise bereits zur Laufzeit von Jackson abhängig sind und JAR Dateien für diese Abhängigkeit in Ihr Deployment aufnehmen, müssen Sie diese JAR Dateien entfernen, da das eigene Versionen von Jackson-Bibliotheken SDK JAR enthält.

Abhängigkeitsmanagement

Das X-Ray SDK für Java ist bei Maven erhältlich:

Wenn Sie Maven verwenden, um Ihre Anwendung zu erstellen, fügen Sie das SDK als Abhängigkeit zu 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ügen Sie für Gradle die SDK als Abhängigkeit zur Kompilierzeit in Ihre Datei ein. build.gradle

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.

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

In diesem Thema werden der AWS X-Ray Namespace, die Metriken und die Dimensionen beschrieben. Sie können X-Ray SDK für 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.