Configuración del SDK de X-Ray para .NET

Puede configurar el SDK de X-Ray para .NET mediante el uso de complementos a fin de incluir información sobre el servicio que sus aplicaciones ejecutan, modificar la conducta predeterminada de muestreo o agregar reglas de muestreo que se aplican a las solicitudes dirigidas a rutas específicas.

Para las aplicaciones web .NET, añada claves a la sección appSettings del archivo Web.config.

ejemplo Web.config

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

Para .NET Core, cree un archivo denominado appsettings.json con una clave de nivel superior llamada XRay.

ejemplo .NET appsettings.json

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

A continuación, en el código de la aplicación, cree un objeto de configuración y utilícelo para inicializar la grabadora de X-Ray. Hágalo antes de inicializar la grabadora.

ejemplo .NET Core Program.cs: configuración de grabadora

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

Si está instrumentando una aplicación web de .NET Core, también puede pasar el objeto de configuración al método UseXRay al configurar el controlador de mensajes. Para las funciones de Lambda utilice el método InitializeInstance como se muestra más arriba.

Para obtener más información acerca del API de configuración de .NET Core, consulte Configurar una aplicación ASP.NET Core en docs.microsoft.com.

Complementos

Utilice complementos para agregar datos sobre el servicio que aloja su aplicación.

Complementos

• Amazon EC2: EC2Plugin agrega el ID de la instancia, la zona de disponibilidad y el grupo de CloudWatch registros.

• Elastic Beanstalk: ElasticBeanstalkPlugin añade el nombre de entorno, la etiqueta de versión y el ID de implementación.

• Amazon ECS: ECSPlugin agrega el ID de contenedor.

Para utilizar un complemento, configure el cliente del SDK de X-Ray para .NET añadiendo el ajuste AWSXRayPlugins. Si hay varios complementos para su aplicación, especifíquelos todos en la misma configuración, separados por comas.

ejemplo Web.config - complementos

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

ejemplo .NET Core appsettings.json: complementos

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

Reglas de muestreo

El SDK utiliza las reglas de muestreo que define el usuario en la consola de X-Ray para determinar qué solicitudes registrar. La regla predeterminada rastrea la primera solicitud cada segundo y el 5 % de las solicitudes adicionales de todos los servicios que envían rastros a X-Ray. Cree reglas adicionales en la consola de X-Ray para personalizar la cantidad de datos registrados para cada una de sus aplicaciones.

El SDK aplica las reglas personalizadas en el orden en que se definen. Si una solicitud coincide con varias reglas personalizadas, el SDK solo aplica la primera regla.

nota

Si el SDK no puede comunicarse con X-Ray para obtener las reglas de muestreo, vuelve a la regla local predeterminada de la primera solicitud recibida al principio de cada segundo y del cinco por ciento de las solicitudes adicionales por host. Eso puede ocurrir si el host no tiene permiso para llamar a las API de muestreo o no puede conectarse al daemon de X-Ray, que actúa como proxy TCP para las llamadas a las API realizadas por el SDK.

También puede configurar el SDK para que cargue las reglas de muestreo desde un documento JSON. El SDK puede usar las reglas locales como respaldo para los casos en que el muestreo de X-Ray no esté disponible, o puede usar las reglas locales exclusivamente.

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

En este ejemplo se define una regla personalizada y una regla predeterminada. La regla personalizada aplica un porcentaje de muestreo del 5 % sin un número mínimo de solicitudes de rastreo para las rutas incluidas bajo /api/move/. La regla predeterminada rastrea la primera solicitud cada segundo y el 10 % de las solicitudes adicionales.

La desventaja de definir las reglas localmente es que el objetivo establecido lo aplica cada instancia de la grabadora de forma independiente, en lugar de ser administrado por el servicio de X-Ray. A medida que se implementan más hosts, el porcentaje establecido se multiplica, lo que dificulta el control de la cantidad de datos registrados.

Sí AWS Lambda, no puedes modificar la frecuencia de muestreo. Si un servicio instrumentado llama a su función, Lambda registrará las llamadas que generaron solicitudes muestreadas por ese servicio. Si el rastreo activo está activado y no hay ningún encabezado de rastreo, Lambda toma la decisión de muestreo.

Para configurar reglas de respaldo, indique al SDK de X-Ray para .NET que cargue reglas de muestreo desde un archivo con la configuración SamplingRuleManifest.

ejemplo .NET Web.config: reglas de muestreo

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

ejemplo .NET Core appsettings.json: reglas de muestreo

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

Para utilizar solo reglas locales, cree la grabadora con una LocalizedSamplingStrategy. Si tiene reglas de copia de seguridad configuradas, elimine dicha configuración.

ejemplo .NET global.asax: reglas de muestreo locales

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

ejemplo .NET Core Program.cs: reglas de muestreo locales

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

Registro (.NET)

El SDK de X-Ray para .NET usa el mismo mecanismo de registro que AWS SDK for .NET. Si ya configuró la aplicación para registrar la AWS SDK for .NET salida, la misma configuración se aplica a la salida del X-Ray SDK for .NET.

Para configurar el registro, añada una sección de configuración denominada aws al archivo App.config o Web.config.

ejemplo Web.config: registro

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

Para obtener más información, consulte Configuración del AWS SDK for .NET para su aplicación en la Guía para desarrolladores del AWS SDK for .NET .

Registro (.NET Core)

El SDK de X-Ray para .NET usa las mismas opciones de registro que AWS SDK for .NET. Para configurar el registro para las aplicaciones .NET Core, transfiera la opción de registro al método AWSXRayRecorder.RegisterLogger.

Por ejemplo, para utilizar log4net, cree un archivo de configuración que defina el registrador, el formato de salida y la ubicación del archivo.

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

A continuación, cree el registrador y aplique la configuración en el código del programa.

ejemplo .NET Core Program.cs: registro

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

Para obtener más información sobre cómo configurar log4net, consulte Configuration en logging.apache.org.

Variables de entorno

Puede usar variables de entorno para configurar el SDK de X-Ray para .NET. El SDK admite las siguientes variables.

• AWS_XRAY_TRACING_NAME: establezca el nombre de servicio que el SDK utiliza para los segmentos. Anula el nombre de servicio que se ha establecido en la estrategia de nomenclatura de segmento del filtro de servlet.

• AWS_XRAY_DAEMON_ADDRESS: establezca el host y el puerto del oyente del daemon de X-Ray. De forma predeterminada, el SDK utiliza 127.0.0.1:2000 tanto para los datos de rastro (UDP) como para el muestreo (TCP). Use esta variable si ha configurado el daemon para que escuche en un puerto diferente o si se ejecuta en un host diferente.

  Formato

  • El mismo puerto: address:port

  • Puertos diferentes: tcp:address:port udp:address:port

• AWS_XRAY_CONTEXT_MISSING: establezca esta opción en RUNTIME_ERROR para generar excepciones cuando el código instrumentado intente registrar datos sin que haya ningún segmento abierto.

  Valores válidos

  • RUNTIME_ERROR: lance una excepción de tiempo de ejecución.

  • LOG_ERROR: registre un error y continúe (predeterminado).

  • IGNORE_ERROR: ignore el error y continúe.

  Se pueden producir errores relativos a segmentos o subsegmentos inexistentes al intentar usar un cliente instrumentado en el código de inicio que se ejecuta cuando no hay ninguna solicitud abierta o en el código que inicia un nuevo subproceso.