X-Ray SDK für Java konfigurieren

Das X-Ray SDK für 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 den globalen Rekorder so konfigurieren, AWSXRayServletFilter dass er den, der Segmente für eingehende HTTP Anrufe erstellt, individuell anpassen kann.

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());
  }
}

Der verwendet SDK 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 Plug-ins verwenden, SDK verwendet das die folgende Auflösungsreihenfolge, um den Ursprung zu bestimmen: ElasticBeanstalk EKS > > ECS >EC2.

Samplingregeln

Der 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, SDK gilt nur die erste Regel.

Sie können den auch so konfigurierenSDK, dass Sampling-Regeln aus einem JSON Dokument geladen werden. Sie SDK können lokale Regeln als Backup für Fälle verwenden, in denen Röntgenproben nicht verfügbar sind, 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
  }
}

In diesem Beispiel werden eine benutzerdefinierte Regel und eine Standardregel definiert. 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 SDK gibt das Meldungen auf ERROR -Ebene in Ihre Anwendungsprotokolle aus. Sie können die Protokollierung auf Debug-Ebene für aktivierenSDK, um detailliertere Protokolle in Ihrer Anwendungsprotokolldatei auszugeben. Gültige Protokollebenen sindDEBUG,, INFOWARN, ERROR und. FATAL FATALBei der Protokollebene werden alle Protokollmeldungen stummgeschaltet, da die SDK Protokollierung nicht auf fataler Ebene erfolgt.

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

Um die aktuelle vollqualifizierte Trace-ID für Ihre Protokollanweisungen verfügbar zu machen, können Sie die ID in den zugewiesenen Diagnosekontext einfügen (). MDC Über die SegmentListener-Schnittstelle werden Methoden während der Ereignisse des Segmentlebenszyklus aus dem X-Ray-Recorder aufgerufen. Wenn ein Segment oder Untersegment beginnt, wird die qualifizierte Trace-ID MDC zusammen mit dem Schlüssel in den eingefügt. AWS-XRAY-TRACE-ID 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 Untersegment endet, wird seine übergeordnete ID in das MDC eingefügt.

1-5df42873-011e96598b447dfca814c156@541b3365be3dafc3

Diese Funktion funktioniert mit Java-Anwendungen, die mit 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-Listener sind eine Schnittstelle zum Abfangen von Lebenszyklusereignissen wie dem Anfang und Ende von Segmenten, die von der erzeugt werden. AWSXRayRecorder Die Implementierung einer Segment-Listener-Ereignisfunktion könnte darin bestehen, allen Untersegmenten dieselbe Anmerkung hinzuzufügen, wenn sie mit erstellt wurden, eine Nachricht zu protokollieren onBeginSubsegment, nachdem jedes Segment an den Daemon gesendet wurde, oder Abfragen aufzuzeichnen, die von den SQL Interzeptoren gesendet wurden afterEndSegment, um beforeEndSubsegmentzu überprüfen, ob das Untersegment eine SQL Abfrage darstellt, und zusätzliche Metadaten hinzuzufügen, falls dies der Fall ist.

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