Konfigurieren des X-Ray-SDK SDK for .NET - AWS X-Ray

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.

Konfigurieren des X-Ray-SDK SDK for .NET

Sie können das X-Ray SDK for .NET mit Plugins konfigurieren, um Informationen über den Service, über den Ihre Anwendung ausgeführt wird, zu berücksichtigen, das Standard-Samplingverhalten zu ändern oder Samplingregeln, die für Anforderungen an bestimmte Pfade gelten, hinzuzufügen.

Für .NET-Webanwendungen fügen Sie dem Abschnitt appSettings Ihrer Web.config-Datei Schlüssel hinzu.

Beispiel Web.config

<configuration> <appSettings> <add key="AWSXRayPlugins" value="EC2Plugin"/> <add key="SamplingRuleManifest" value="sampling-rules.json"/> </appSettings> </configuration>

Erstellen Sie für .NET Core eine Datei mit dem Namen appsettings.json mit einem Top-Level-Schlüssel namens XRay.

Beispiel .NET appsettings.json

{ "XRay": { "AWSXRayPlugins": "EC2Plugin", "SamplingRuleManifest": "sampling-rules.json" } }

Erstellen Sie dann in Ihrem Anwendungscode ein Konfigurationsobjekt und verwenden Sie es, um den X-Ray-Recorder zu initialisieren. Führen Sie dies aus, bevor Sie den Recorder initialisieren.

Beispiel .NET Core Program.cs — Konfiguration des Recorders

using Amazon.XRay.Recorder.Core; ... AWSXRayRecorder.InitializeInstance(configuration);

Wenn Sie eine .NET Core-Webanwendung instrumentieren, können Sie das Konfigurationsobjekt auch anUseXRayMethode wenn duKonfigurieren Sie den Message-Handleraus. Für Lambda-Funktionen verwenden Sie dasInitializeInstance-Methode wie oben gezeigt.

Weitere Informationen zur .NET Core-Konfigurations-API finden Sie unterKonfigurieren einer ASP.NET Core-Appauf docs.microsoft.com.

Plug-ins

Verwenden Sie Plugins zum Hinzufügen von Daten über den Service, der Ihre Anwendung hostet.

Plug-ins

  • Amazon EC2 —EC2Pluginfügt die Instance-ID, die Availability Zone und die CloudWatch Logs Logs-Gruppe hinzu.

  • Elastic Beanstalk —ElasticBeanstalkPluginfügt den Umgebungsnamen, die Versionsbezeichnung und die Bereitstellungs-ID hinzu.

  • Amazon ECS —ECSPluginfügt die Container-ID hinzu.

Um ein Plugin zu verwenden, konfigurieren Sie das X-Ray SDK for .NET -Client, indem SieAWSXRayPlugins-Einstellung. Wenn mehrere Plugins auf Ihre Anwendung zutreffen, geben Sie alle Plugins in der gleichen Einstellung an (getrennt durch Kommata).

Beispiel Web.config – Plugins

<configuration> <appSettings> <add key="AWSXRayPlugins" value="EC2Plugin,ElasticBeanstalkPlugin"/> </appSettings> </configuration>

Beispiel .NET Core appsettings.json — Plugins

{ "XRay": { "AWSXRayPlugins": "EC2Plugin,ElasticBeanstalkPlugin" } }

Samplingregeln

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

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

Anmerkung

Wenn das SDK X-Ray nicht erreichen kann, um Stichprobenregeln zu erhalten, wird es auf eine lokale Standardregel der ersten Anforderung jede Sekunde und fünf Prozent aller zusätzlichen Anforderungen pro Host zurückgesetzt. Dies kann auftreten, wenn der Host keine Berechtigung zum Aufrufen von Sampling-APIs hat oder 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 zum Laden von Samplingregeln aus einem JSON-Dokument konfigurieren. 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.

Beispiel sampling-rules.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 wird eine benutzerdefinierte Regel und eine Standardregel definiert. Die benutzerdefinierte Regel wendet eine Abtastrate von fünf Prozent ohne Mindestanzahl von Anfragen an, die für Pfade unter verfolgt werden sollen/api/move/aus. Die Standardregel verfolgt jede Sekunde die erste Anfrage und 10 Prozent aller zusätzlichen 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-Dienst verwaltet zu werden. Wenn Sie mehr Hosts bereitstellen, wird der feste Zinssatz multipliziert, wodurch es schwieriger wird, die Menge der aufgezeichneten Daten zu kontrollieren.

InAWS Lambdakönnen Sie die Samplingrate 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 die aktive Ablaufverfolgung aktiviert ist und kein Tracing-Header vorhanden ist, trifft Lambda die Stichprobenentscheidung.

Um die Sicherungsregeln zu konfigurieren, weisen Sie das X-Ray SDK for .NET an, Samplingregeln aus einer Datei mitSamplingRuleManifest-Einstellung.

Beispiel .NET Web.config – Samplingregeln

<configuration> <appSettings> <add key="SamplingRuleManifest" value="sampling-rules.json"/> </appSettings> </configuration>

Beispiel .NET Core appsettings.json — Samplingregeln

{ "XRay": { "SamplingRuleManifest": "sampling-rules.json" } }

Um nur lokale Regeln zu verwenden, erstellen Sie den Recorder mit einer LocalizedSamplingStrategy. Wenn Sie Sicherungsregeln konfiguriert haben, entfernen Sie die Konfiguration.

Beispiel .NET global.asax — lokale Samplingregeln

var recorder = new AWSXRayRecorderBuilder().WithSamplingStrategy(new LocalizedSamplingStrategy("samplingrules.json")).Build(); AWSXRayRecorder.InitializeInstance(recorder: recorder);

Beispiel .NET Core Program.cs — lokale Samplingregeln

var recorder = new AWSXRayRecorderBuilder().WithSamplingStrategy(new LocalizedSamplingStrategy("sampling-rules.json")).Build(); AWSXRayRecorder.InitializeInstance(configuration,recorder);

Protokollierung (.NET)

Das X-Ray SDK for .NET verwendet denselben Protokollierungsmechanismus wieAWS SDK for .NETaus. Wenn Sie Ihre Anwendung bereits für die Protokollierung konfiguriert habenAWS SDK for .NET-Ausgabe gilt die gleiche Konfiguration für Ausgaben aus dem X-Ray SDK for .NET.

Zum Konfigurieren von Protokollierung fügen Sie einen Konfigurationsabschnitt mit dem Namen aws Ihrer App.config-Datei oder Web.config-Datei hinzu.

Beispiel Web.config – Protokollierung

... <configuration> <configSections> <section name="aws" type="Amazon.AWSSection, AWSSDK.Core"/> </configSections> <aws> <logging logTo="Log4Net"/> </aws> </configuration>

Weitere Informationen finden Sie unter Konfigurieren Ihrer AWS SDK for .NET-Anwendung im AWS SDK for .NET-Entwicklerhandbuch.

Protokollierung (.NET Core)

Das X-Ray SDK for .NET verwendet dieselben Protokollierungsoptionen wieAWS SDK for .NETaus. Um die Protokollierung für .NET-Core-Anwendungen zu konfigurieren, übergeben Sie die Protokollierungsoption an dieAWSXRayRecorder.RegisterLogger-Methode.

Um beispielsweise log4net zu verwenden, erstellen Sie eine Konfigurationsdatei, die den Logger, das Ausgabeformat und den Speicherort der Datei definiert.

Beispiel .NET Core log4net.config

<?xml version="1.0" encoding="utf-8" ?> <log4net> <appender name="FileAppender" type="log4net.Appender.FileAppender,log4net"> <file value="c:\logs\sdk-log.txt" /> <layout type="log4net.Layout.PatternLayout"> <conversionPattern value="%date [%thread] %level %logger - %message%newline" /> </layout> </appender> <logger name="Amazon"> <level value="DEBUG" /> <appender-ref ref="FileAppender" /> </logger> </log4net>

Erstellen Sie dann den Logger und übernehmen Sie die Konfiguration in Ihren Programmcode.

Beispiel .NET Core Program.cs — Protokollierung

using log4net; using Amazon.XRay.Recorder.Core; class Program { private static ILog log; static Program() { var logRepository = LogManager.GetRepository(Assembly.GetEntryAssembly()); XmlConfigurator.Configure(logRepository, new FileInfo("log4net.config")); log = LogManager.GetLogger(typeof(Program)); AWSXRayRecorder.RegisterLogger(LoggingOptions.Log4Net); } static void Main(string[] args) { ... } }

Weitere Informationen zur Konfiguration von log4net finden Sie unterKonfigurationauf logging.apache.org.

Umgebungsvariablen

Sie können Umgebungsvariablen zum Konfigurieren des X-Ray-SDK SDK for .NET verwenden. Das SDK unterstützt die folgenden Variablen.

  • AWS_XRAY_TRACING_NAME— Legt einen Servicenamen fest, der vom SDK für Segmente verwendet wird. Überschreibt den für die Segmentbenennungsstrategie des Servlet-Filters festgelegten Dienstnamen.

  • AWS_XRAY_DAEMON_ADDRESS— Legt den Host und den Port des X-Ray -Daemon-Listeners fest. Standardmäßig verwendet das SDK127.0.0.1:2000sowohl für Trace-Daten (UDP) als auch für Sampling (TCP). Verwenden Sie diese Variable, wenn Sie den Daemon für konfiguriert habenhören Sie an einem anderen Portoder wenn es auf einem anderen Host läuft.

    Format

    • Gleicher Portaddress:port

    • Verschiedene Portstcp:address:port udp:address:port

  • AWS_XRAY_CONTEXT_MISSING— Stellen Sie aufLOG_ERRORum das Auslösen von Ausnahmen zu vermeiden, wenn Ihr instrumentierter Code versucht, Daten aufzuzeichnen, wenn kein Segment geöffnet ist.

    Zulässige Werte

    • RUNTIME_ERROR— Löst eine Laufzeitausnahme (Standard).

    • LOG_ERROR— Protokollieren Sie einen Fehler und fahren Sie fort.

    Fehler aufgrund fehlender Segmente oder Untersegmente können auftreten, wenn Sie versuchen, einen instrumentierten Client in Startup-Code zu verwenden, der ausgeführt wird, wenn keine Anfrage geöffnet ist, oder in Code, der einen neuen Thread aufruft.