Configuration du kit SDK X-Ray pour .NET

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

Pour les applications web .NET, ajoutez des clés à la section appSettings du fichier Web.config.

Exemple Web.config

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

Pour .NET Core, créez un fichier nommé appsettings.json avec une clé de niveau supérieur nommée XRay.

Exemple .NET appsettings.json

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

Exemple .NET Core Program.cs — Configuration de l'enregistreur

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

Si vous instrumentez une application web .NET Core, vous pouvez également transmettre l'objet de configuration à la méthode UseXRay lorsque vous configurez le gestionnaire de messages. Pour les fonctions Lambda, utilisez laInitializeInstance méthode indiquée ci-dessus.

Pour plus d'informations sur l'API de configuration .NET Core, veuillez consulter la rubrique Configuration d'une application ASP.NET Core sur docs.microsoft.com.

Plugins

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

Plugins

• Amazon EC2 :EC2Plugin ajoute l'ID d'instance, la zone de disponibilité et le groupe de CloudWatch journaux.

• Elastic Beanstalk :ElasticBeanstalkPlugin ajoute le nom de l'environnement, l'étiquette de version et l'ID de déploiement.

• Amazon ECS :ECSPlugin ajoute l'ID du conteneur.

Pour utiliser un plugin, configurez le kit SDK X-Ray SDK for .NET en ajoutant leAWSXRayPlugins 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.

Exemple Web.config - plug-ins

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

Exemple .NET Core appsettings.json — Plug-ins

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

Règles d'échantillonnage

Le SDK utilise 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 effectue le suivi de la première demande chaque seconde et de 5 % de toutes les demandes supplémentaires, tous services confondus, qui envoient des traces à X-Ray. Créez des règles supplémentaires dans la console X-Ray afin de personnaliser la quantité de données enregistrées pour chacune de vos applications.

Le kit SDK applique des règles personnalisées dans l'ordre dans lequel elles sont définies. Si une demande correspond à plusieurs règles personnalisées, le SDK applique uniquement la première règle.

Note

Si le SDK ne parvient pas à joindre X-Ray pour obtenir les règles d'échantillonnage, il revient à une règle locale par défaut selon laquelle la première demande est effectuée chaque seconde et 5 % des demandes supplémentaires par hôte. Cela peut se produire si l'hôte n'est pas autorisé à appeler des API d'échantillonnage ou s'il ne peut pas se connecter au démon X-Ray, qui agit en tant que proxy TCP pour les appels d'API effectués par le SDK.

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

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

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 rechercher les chemins/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 davantage d'hôtes, le débit 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 la fréquence d'échantillonnage. Si votre fonction est appelée par un service instrumenté, les appels ayant généré des requêtes é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, demandez au SDK X-Ray pour .NET de charger les règles d'échantillonnage à partir d'un fichier contenant leSamplingRuleManifest paramètre.

Exemple .NET Web.config - Règles d'échantillonnage

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

Exemple .NET Core appsettings.json — Règles d'échantillonnage

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

Exemple .NET global.asax — Règles d'échantillonnage locales

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

Exemple .NET Core Program.cs — Règles d'échantillonnage locales

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

Journalisation (.NET)

Le kit SDK X-Ray pour .NET utilise le même mécanisme de journalisation que le kit SDK X-Ray pour .NET AWS SDK for .NET. Si vous avez déjà configuré votre application pour enregistrer laAWS SDK for .NET sortie, la même configuration s'applique à la sortie du kit SDK X-Ray pour .NET.

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

Exemple Web.config - journalisation

...
<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 (.NET Core)

Le kit SDK X-Ray pour .NET utilise les mêmes options de journalisation que le kit SDK X-Ray pour .NET AWS SDK for .NET. Pour configurer la journalisation pour les applications .NET Core, transmettez l'option de journalisation à laAWSXRayRecorder.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.

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

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

Exemple .NET Core Program.cs — Journalisation

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 la section Configuration sur logging.apache.org.

Variables d'environnement

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

• AWS_XRAY_TRACING_NAME— Définissez un nom de service que le SDK utilise pour les segments. Remplace le nom de service que vous définissez sur la stratégie d'attribution de noms de segment du filtre servlet.

• AWS_XRAY_DAEMON_ADDRESS— Définissez l'hôte et le port de l'écouteur du démon X-Ray. Par défaut, le SDK utilise à la fois127.0.0.1:2000 les données de trace (UDP) et l'échantillonnage (TCP). Utilisez cette variable si vous avez configuré le démon pour qu'il écoute sur un autre port ou s'il s'exécute sur un autre hôte.

  Format

  • Même port —address:port

  • Différents ports —tcp:address:port udp:address:port

• AWS_XRAY_CONTEXT_MISSING— DéfiniRUNTIME_ERROR pour générer des exceptions lorsque votre code instrumenté tente d'enregistrer des données alors qu'aucun segment n'est ouvert.

  Valeurs valides

  • RUNTIME_ERROR— Lance une exception d'exécution

  • LOG_ERROR— Consigne une erreur et continue (par défaut).

  • IGNORE_ERROR— Ignorez l'erreur et continuez.

  Des erreurs liées à des segments ou sous-segments manquants peuvent survenir lorsque vous essayez d'utiliser un client instrumenté dans du code de démarrage qui s'exécute lorsqu'aucune demande n'est ouverte, ou dans du code qui génère un nouveau fil de discussion.