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.
Konfiguration des X-Ray-SDK SDK for Java
Das X-Ray SDK for Java enthält eine Klasse namensAWSXRay, die den Global Recorder 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.
Abschnitte
Service-Plugins
Dientplugins zum Aufzeichnen von Informationen über den Dienst, der Ihre Anwendung hostet.
Plug-ins
Amazon EC2 —
EC2Pluginfügt die Instance-ID, Availability Zone und die CloudWatch Logs-Gruppe hinzu.Elastic Beanstalk —
ElasticBeanstalkPluginfügt den Umgebungsnamen, die Versionsbezeichnung und die Deployment-ID hinzu.Amazon ECS —
ECSPluginfügt die Container-ID hinzu.Amazon EKS —
EKSPluginfügt die Container-ID, den Clusternamen, die Pod-ID und die CloudWatch Logs-Gruppe hinzu.
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 dasorigin Feld im Segment festzulegen. Dies gibt den Typ derAWS Ressource an, auf der 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 für jede Ihrer Anwendungen aufgezeichnete Datenmenge 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.
Anmerkung
Wenn das SDK X-Ray nicht erreichen kann, um Sampling-Regeln zu erhalten, kehrt es zu einer lokalen Standardregel zurück, bei der die erste Anfrage jede Sekunde und fünf Prozent aller weiteren Anfragen pro Host gelten. Dies kann vorkommen, wenn der Host keine Berechtigung hat, Sampling-APIs aufzurufen, oder wenn er keine Verbindung zum X-Ray-Daemon herstellen kann, der als TCP-Proxy für API-Aufrufe des 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 keine X-Ray-Sampling verfügbar ist, oder ausschließlich lokale Regeln verwenden.
Beispiel Sampling-Regeln.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 Sampling-Rate von fünf Prozent an, ohne dass eine Mindestanzahl von Trace-Requests für Pfade unter diesem Wert erforderlich ist/api/move/. Die standardmäßige Sampling-Regel beträgt 1 Anforderung pro Sekunde und 10 Prozent aller weiteren Anforderungen.
Der Nachteil der lokalen Definition von Regeln besteht darin, dass das feste Ziel von jeder Instanz des Recorders unabhängig angewendet wird, anstatt vom X-Ray-Service verwaltet zu werden. Wenn Sie mehr Hosts bereitstellen, vervielfacht sich die feste Rate, wodurch es schwieriger wird, die aufgezeichnete Datenmenge zu kontrollieren.
Wenn diese Option aktiviert istAWS Lambda, können Sie die Sampling-Rate nicht ändern. Wenn Ihre Funktion von einem instrumentierten Dienst aufgerufen wird, werden Aufrufe, die Anfragen generiert haben, die von diesem Dienst abgetastet wurden, von Lambda aufgezeichnet. Wenn aktives Tracing aktiviert ist und kein Tracing-Header vorhanden ist, trifft Lambda die Sampling-Entscheidung.
Um Sicherungsregeln in Spring bereitzustellen, konfigurieren Sie den globalen Recorder mit einer CentralizedSamplingStrategy in einer Konfigurationsklasse.
Beispiel src/main/java/myapp/WebConfig .java-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(newLocalizedSamplingStrategy(ruleFile));
Protokollierung
Standardmäßig gibt das SDK MeldungenERROR auf -Ebene an Ihre Anwendungsprotokolle aus. Sie können die Protokollierung auf Debug-Ebene im SDK aktivieren, um detailliertere Protokolle in Ihre Anwendungsprotokolldatei auszugeben. GültigeDEBUG Protokollebenen sindINFOWARN,,ERROR, undFATAL. FATALBei der Protokollebene werden alle Protokollmeldungen stummgeschaltet, da das SDK nicht auf der Ebene „Fatal“ protokolliert.
Beispiel application.properties
Legen Sie die Protokollierungsebene mit der logging.level.com.amazonaws.xray-Eigenschaft fest.
logging.level.com.amazonaws.xray = DEBUGVerwenden 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@541b3365be3dafc3Diese Funktion funktioniert mit Java-Anwendungen, die mit demAWS X-Ray SDK for Java instrumentiert sind, und unterstützt die folgenden Logging-Konfigurationen:
-
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.
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.
Die vollständige Liste derSegmentListener Funktionen finden Sie in der Dokumentation für das AWS X-RayRecorder 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
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 für Java zu konfigurieren. Das SDK unterstützt die folgenden Variablen.
-
AWS_XRAY_TRACING_NAME— Legt 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 verwendet127.0.0.1:2000das SDK sowohl Trace-Daten (UDP) als auch Sampling (TCP). Verwenden Sie diese Variable, wenn Sie den Daemon so konfiguriert haben, dass er an einem anderen Port abhört, oder wenn er auf einem anderen Host läuft.Format
-
Derselbe Port —
address:port -
Verschiedene Häfen —
tcp:address:portudp:address:port
-
AWS_XRAY_CONTEXT_MISSING— Auf setzen,RUNTIME_ERRORum Ausnahmen auszulösen, wenn Ihr instrumentierter Code versucht, Daten aufzuzeichnen, wenn kein Segment geöffnet ist.Zulässige Werte
-
RUNTIME_ERROR— Löst eine Laufzeit-Exception aus. -
LOG_ERROR— Loggen Sie einen Fehler und fahren Sie fort (Standard). -
IGNORE_ERROR— Ignorieren Sie den Fehler und fahren Sie fort.
Fehler im Zusammenhang mit fehlenden Segmenten oder Untersegmenten können auftreten, wenn Sie versuchen, einen instrumentierten Client in Startcode zu verwenden, der ausgeführt wird, wenn keine Anfrage geöffnet ist, oder in Code, der einen neuen Thread generiert.
-
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— EntsprichtAWS_XRAY_TRACING_NAME. -
com.amazonaws.xray.emitters.daemonAddress— EntsprichtAWS_XRAY_DAEMON_ADDRESS. -
com.amazonaws.xray.strategy.contextMissingStrategy— EntsprichtAWS_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.
