AWS X-Ray SDK for Java - AWS X-Ray
UntermoduleVoraussetzungenAbhängigkeitsmanagementÜberwachen

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

Anmerkungen und Metadaten

Anmerkungen und Metadaten sind beliebiger Text, den Sie mit dem X-Ray SDK zu Segmenten hinzufügen. Anmerkungen werden für die Verwendung mit Filterausdrücken indexiert. Metadaten werden nicht indexiert, können aber im Rohsegment mit der X-Ray-Konsole oder API angezeigt werden. Jeder, dem Sie Lesezugriff auf X-Ray gewähren, kann diese Daten einsehen.

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:

  • AWS SDKfür Java-Version 1.11.398 oder höher

  • Servlet 3.1.0 API

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:

  • Gruppe — com.amazonaws

  • Artifact — aws-xray-recorder-sdk-bom

  • Version – 2.11.0

Wenn Sie Maven verwenden, um Ihre Anwendung zu erstellen, fügen Sie das SDK als Abhängigkeit zu Ihrer pom.xml Datei hinzu.

Beispiel pom.xml - Abhängigkeiten
<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

Beispiel build.gradle – Abhängigkeiten
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.

Metrik Verfügbare Statistiken Beschreibung Einheiten

Latency

Durchschnitt, Minimum, Maximum, Anzahl

Die Differenz zwischen der Start- und Endzeit Durchschnitt, Minimum und Maximum beschreiben Betriebslatenz. „Anzahl“ beschreibt die Anzahl der Aufrufe.

Millisekunden

ErrorRate

Durchschnitt, Summe

Die Rate der Anforderungen, die mit dem Statuscode „4xx Client Error“ fehlgeschlagen sind, was zu einem Fehler führt.

Prozent

FaultRate

Durchschnitt, Summe

Die Rate der Traces, die mit dem Statuscode „5xx Server Error“ fehlgeschlagen sind, was zu einem Fehler führte.

Prozent

ThrottleRate

Durchschnitt, Summe

Die Rate der abgelehnten Traces, die einen 429-Statuscode zurückgeben. Dies ist eine Teilmenge der ErrorRate-Metrik.

Prozent

OkRate

Durchschnitt, Summe

Die Rate der verfolgten Anforderungen, die zu einem OK-Statuscode führen.

Prozent

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.

Dimension Beschreibung

ServiceType

Der Service-Typ, z. B. AWS::EC2::Instance oder NONE, falls nicht bekannt.

ServiceName

Der kanonische Name für den Service.

CloudWatch X-Ray-Metriken aktivieren

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

So konfigurieren Sie Trace-Metriken

  1. Fügen Sie das aws-xray-recorder-sdk-metrics Paket als Apache Maven Abhängigkeit hinzu. Weitere Informationen finden Sie unter X-Ray SDK für Java-Submodule.

  2. Aktivieren Sie ein neues MetricsSegmentListener() als Teil des globalen Recorder-Builds.

    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.plugins.ElasticBeanstalkPlugin;
import com.amazonaws.xray.strategy.sampling.LocalizedSamplingStrategy;

@Configuration
public class WebConfig {
...
  static {
    AWSXRayRecorderBuilder builder = AWSXRayRecorderBuilder
                                        .standard()
                                        .withPlugin(new EC2Plugin())
                                        .withPlugin(new ElasticBeanstalkPlugin())
                                        .withSegmentListener(new MetricsSegmentListener());

    URL ruleFile = WebConfig.class.getResource("/sampling-rules.json");
    builder.withSamplingStrategy(new LocalizedSamplingStrategy(ruleFile));

    AWSXRay.setGlobalRecorder(builder.build());
  }
}

  3. Stellen Sie den CloudWatch Agenten bereit, um Metriken mithilfe von Amazon Elastic Compute Cloud (AmazonEC2), Amazon Elastic Container Service (AmazonECS) oder Amazon Elastic Kubernetes Service (AmazonEKS) zu sammeln:

  4. Konfigurieren Sie den SDK für die Kommunikation mit dem CloudWatch Agenten. Standardmäßig SDK kommuniziert der mit dem CloudWatch Agenten über die Adresse127.0.0.1. Sie können alternative Adressen konfigurieren, indem Sie die Umgebungsvariable oder die Java-Eigenschaft auf address:port festlegen.

    Beispiel Umgebungsvariable
    AWS_XRAY_METRICS_DAEMON_ADDRESS=address:port
    Beispiel Java-Eigenschaft
    com.amazonaws.xray.metrics.daemonAddress=address:port
So überprüfen Sie die Konfiguration

  1. Melden Sie sich bei der an AWS Management Console und öffnen Sie die CloudWatch Konsole unter https://console.aws.amazon.com/cloudwatch/.

  2. Öffnen Sie die Registerkarte Metriken, um den Zustrom Ihrer Metriken zu überwachen.

  3. (Optional) Öffnen Sie in der CloudWatch Konsole auf der Registerkarte Protokolle die ServiceMetricsSDK Protokollgruppe. Suchen Sie nach einem Protokolldatenstrom, der den Host-Metriken entspricht, und bestätigen Sie die Protokollmeldungen.