Konfiguration des X-Ray SDK für. NET

Sie können das X-Ray SDK für konfigurieren. NETmit Plug-ins, um Informationen über den Dienst aufzunehmen, auf dem Ihre Anwendung läuft, das standardmäßige Sampling-Verhalten zu ändern oder Sampling-Regeln hinzuzufügen, die für Anfragen an bestimmte Pfade gelten.

Für. NETWebanwendungen, fügen Sie Schlüssel zum appSettings Abschnitt Ihrer Web.config Datei hinzu.

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

Für. NETCore, erstellen Sie eine Datei appsettings.json mit dem Namen eines Schlüssels der obersten Ebene namensXRay.

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

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

Wenn Sie eine instrumentieren. NETCore-Webanwendung: Sie können das Konfigurationsobjekt auch an die UseXRay Methode übergeben, wenn Sie den Message-Handler konfigurieren. Verwenden Sie für Lambda-Funktionen die oben gezeigte InitializeInstance Methode.

Für weitere Informationen über die. NETKernkonfiguration API finden Sie unter Konfiguration einesASP. NETCore-App auf docs.microsoft.com.

Plug-ins

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

Um ein Plugin zu verwenden, konfigurieren Sie das X-Ray SDK für. NETClient durch Hinzufügen der AWSXRayPlugins Einstellung. Wenn mehrere Plugins auf Ihre Anwendung zutreffen, geben Sie alle Plugins in der gleichen Einstellung an (getrennt durch Kommata).

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

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

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

Dieses Beispiel definiert eine benutzerdefinierte Regel und eine Standardregel. 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 Backup-Regeln zu konfigurieren, teilen Sie dem X-Ray SDK mit. NETum Sampling-Regeln aus einer Datei mit der SamplingRuleManifest Einstellung zu laden.

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

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

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

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

Protokollierung (. NET)

Das X-Ray SDK für. NETverwendet den gleichen Protokollierungsmechanismus wie der AWS SDK for .NET. Wenn Sie Ihre Anwendung bereits so konfiguriert haben, dass die AWS SDK for .NET Ausgabe protokolliert wird, gilt dieselbe Konfiguration für die Ausgabe von 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.

...
<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 (. NETKern)

Das X-Ray SDK für. NETverwendet dieselben Protokollierungsoptionen wie der AWS SDK for .NET. Um die Protokollierung für zu konfigurieren. NETKernanwendungen: Übergeben Sie die Protokollierungsoption an die AWSXRayRecorder.RegisterLogger Methode.

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

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

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 zu konfigurieren. NET. Die SDK unterstützt die folgenden Variablen.