Configuration du X-Ray SDK pour. NET

Vous pouvez configurer le X-Ray SDK pour. NETavec des plugins pour inclure des informations sur le service sur lequel votre application s'exécute, modifier le comportement d'échantillonnage par défaut ou ajouter des règles d'échantillonnage qui s'appliquent aux demandes adressées à des chemins spécifiques.

Pour. NETapplications Web, ajoutez des clés à la appSettings section de votre Web.config fichier.

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

Pour. NETCore, créez un fichier nommé appsettings.json avec une clé de niveau supérieur nomméeXRay.

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

Ensuite, dans le code de votre application, créez un objet de configuration et utilisez-le pour initialiser l'enregistreur X-Ray. Faites-le avant d'initialiser l'enregistreur.

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

Si vous instrumentez un. NETApplication Web principale, vous pouvez également transmettre l'objet de configuration à la UseXRay méthode lorsque vous configurez le gestionnaire de messages. Pour les fonctions Lambda, utilisez la InitializeInstance méthode décrite ci-dessus.

Pour plus d'informations sur le. NETConfiguration de baseAPI, voir Configurer unASP. NETApplication principale sur docs.microsoft.com.

Plugins

Utilisez des plug-ins pour ajouter des données sur le service qui héberge votre application.

Pour utiliser un plugin, configurez le X-Ray SDK pour. NETclient en ajoutant le AWSXRayPlugins paramètre. Si plusieurs plug-ins s'appliquent à votre application, spécifiez-les tous dans le même paramètre, séparés par des virgules.

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

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

Règles d'échantillonnage

SDKUtilise les règles d'échantillonnage que vous définissez dans la console X-Ray pour déterminer les demandes à enregistrer. La règle par défaut suit la première demande chaque seconde, et 5 % de toutes les demandes supplémentaires provenant de tous les services envoient des traces à X-Ray. Créez des règles supplémentaires dans la console X-Ray pour personnaliser la quantité de données enregistrées pour chacune de vos applications.

Les règles personnalisées SDK s'appliquent dans l'ordre dans lequel elles sont définies. Si une demande correspond à plusieurs règles personnalisées, seule la première règle SDK s'applique.

Vous pouvez également configurer le SDK pour charger les règles d'échantillonnage à partir d'un JSON document. Ils SDK peuvent utiliser les règles locales comme solution de rechange dans les cas où l'échantillonnage X-Ray n'est pas disponible, ou utiliser exclusivement les règles locales.

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

Cet exemple définit une règle personnalisée et une règle par défaut. La règle personnalisée applique un taux d'échantillonnage de 5 % sans nombre minimum de demandes à suivre pour les chemins sous-jacents. /api/move/ La règle par défaut suit la première demande chaque seconde et 10 % des demandes supplémentaires.

L'inconvénient de définir des règles localement est que la cible fixe est appliquée par chaque instance de l'enregistreur indépendamment, au lieu d'être gérée par le service X-Ray. Au fur et à mesure que vous déployez de nouveaux hôtes, le taux fixe est multiplié, ce qui complique le contrôle de la quantité de données enregistrées.

Activé AWS Lambda, vous ne pouvez pas modifier le taux d'échantillonnage. Si votre fonction est appelée par un service instrumenté, les appels ayant généré des demandes échantillonnées par ce service seront enregistrés par Lambda. Si le suivi actif est activé et qu'aucun en-tête de suivi n'est présent, Lambda prend la décision d'échantillonnage.

Pour configurer les règles de sauvegarde, indiquez au X-Ray SDK for. NETpour charger les règles d'échantillonnage à partir d'un fichier contenant le SamplingRuleManifest paramètre.

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

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

Pour utiliser uniquement les règles locales, créez l'enregistreur avec une instruction LocalizedSamplingStrategy. Si vous avez des règles de sauvegarde configurées, supprimez cette configuration.

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

Journalisation (. NET)

The X-Ray SDK pour. NETutilise le même mécanisme de journalisation que le AWS SDK for .NET. Si vous avez déjà configuré votre application pour enregistrer les AWS SDK for .NET sorties, la même configuration s'applique aux sorties du X-Ray SDK for. NET.

Pour configurer la journalisation, ajoutez une section de configuration nommée aws à votre fichier App.config ou Web.config.

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

Pour plus d'informations, consultez Configuration de votre application AWS SDK for .NET dans le Manuel du développeur AWS SDK for .NET .

Journalisation (. NETNoyau)

The X-Ray SDK pour. NETutilise les mêmes options de journalisation que le AWS SDK for .NET. Pour configurer la journalisation pour. NETApplications principales, transmettez l'option de journalisation à la AWSXRayRecorder.RegisterLogger méthode.

Par exemple, pour utiliser log4net, créez un fichier de configuration qui définit l'enregistreur d'événements, le format de sortie et l'emplacement du fichier.

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

Ensuite, créez l'enregistreur d'événements et appliquez la configuration dans le code de programme.

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)
  {
  ...
  }
}

Pour plus d'informations sur la configuration de log4net, consultez Configuration sur logging.apache.org.

Variables d’environnement

Vous pouvez utiliser des variables d'environnement pour configurer le X-Ray SDK pour. NET. Le SDK prend en charge les variables suivantes.