Konfiguration des X-Ray-SDK SDK for .NET

Sie können das X-Ray SDK for .NET mit Plug-ins so konfigurieren, dass es Informationen über den Dienst enthält, auf dem Ihre Anwendung ausgeführt wird, das standardmäßige Sampling-Verhalten ändern oder Sampling-Regeln hinzufügen, die für Anfragen an bestimmte Pfade gelten.

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 — Recorder-Konfiguration

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

Wenn Sie eine .NET Core-Webanwendung instrumentieren, können Sie das Konfigurationsobjekt auch an dieUseXRay Methode übergeben, wenn Sie den Message-Handler konfigurieren. Verwenden Sie für Lambda-Funktionen die oben gezeigteInitializeInstance Methode.

Weitere Informationen zur .NET Core-Konfigurations-API finden Sie unter Konfigurieren einer ASP.NET Core-App auf docs.microsoft.com.

Plug-ins

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

Plug-ins

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

• Elastic Beanstalk —ElasticBeanstalkPlugin fügt den Umgebungsnamen, die Versionsbezeichnung und die Deployment-ID hinzu.

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

Um ein Plugin zu verwenden, konfigurieren Sie das X-Ray-SDK SDK for .NET Client, indem Sie dieAWSXRayPlugins Einstellung hinzufügen. 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 — Erweiterungen

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

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 Standardregel verfolgt die erste 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 Backup-Regeln zu konfigurieren, weisen Sie das X-Ray SDK for .NET an, Sampling-Regeln aus einer Datei mit derSamplingRuleManifest Einstellung zu laden.

Beispiel .NET Web.config – Samplingregeln

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

Beispiel .NET Core appsettings.json — Stichprobenregeln

{
  "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 Stichprobenregeln

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

Beispiel .NET Core Program.cs — Lokale Sampling-Regeln

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

Protokollierung (.NET)

Das X-Ray-SDK SDK for .NET verwendet den gleichen Logging-Mechanismus wie das AWS SDK for .NET. Wenn Sie Ihre Anwendung bereits für die Protokollierung derAWS SDK for .NET Ausgabe konfiguriert haben, gilt dieselbe Konfiguration für die Ausgabe aus dem X-Ray-SDK 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 SDK for .NET verwendet dieselben Logging-Optionen wie das AWS SDK for .NET. 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 unter Konfiguration auf logging.apache.org.

Umgebungsvariablen

Sie können Umgebungsvariablen verwenden, um das X-Ray-SDK für .NET 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:2000 das 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:port udp:address:port

• AWS_XRAY_CONTEXT_MISSING— Auf setzen,RUNTIME_ERROR um 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.