Configurar o X-Ray SDK para .NET

Você pode configurar o X-Ray SDK para .NET com plug-ins para incluir informações sobre o serviço em que a aplicação é executada, modificar o comportamento de amostragem padrão ou adicionar regras de amostragem que se aplicam a solicitações para caminhos específicos.

Para aplicativos web .NET, adicione chaves à seção appSettings do seu arquivo Web.config.

exemplo Web.config

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

Para o .NET Core, crie um arquivo chamado appsettings.json com chave de nível superior chamada XRay.

exemplo .NET appsettings.json

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

Em seguida, no código da aplicação, crie um objeto de configuração e use-o para inicializar o gravador do X-Ray. Faça isso antes de inicializar o gravador.

exemplo .NET Core Program.cs: configuração do gravador

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

Se você estiver instrumentando um aplicativo web .NET Core, você também pode passar o objeto de configuração para o método UseXRay ao configurar o manipulador de mensagens. Para funções do Lambda, use o método InitializeInstance como mostrado acima.

Para obter mais informações sobre a API de configuração do .NET Core, consulte Configure an ASP.NET Core App no site docs.microsoft.com.

Plug-ins

Use plugins para adicionar dados sobre o serviço que hospeda seu aplicativo.

Plug-ins

• Amazon EC2 — EC2Plugin adiciona o ID da instância, a zona de disponibilidade e o grupo de CloudWatch registros.

• Elastic Beanstalk: o ElasticBeanstalkPlugin adiciona o nome do ambiente, o rótulo da versão e o ID de implantação.

• Amazon ECS: o ECSPlugin adiciona o ID do contêiner.

Para usar um plugin, configure o cliente do X-Ray SDK para .NET adicionando a configuração AWSXRayPlugins. Se vários plugins se aplicarem ao seu aplicativo, especifique todos eles na mesma configuração, separados por vírgulas.

exemplo Web.config – plugins

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

exemplo .NET Core appsettings.json: plugins

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

Regras de amostragem

O SDK usa as regras de amostragem que você define no console do X-Ray para determinar quais solicitações serão registradas. A regra padrão rastreia a primeira solicitação a cada segundo e 5% de todas as solicitações adicionais em todos os serviços que enviam rastreamentos ao X-Ray. Crie regras adicionais no console do X-Ray para personalizar a quantidade de dados registrados para cada uma das aplicações.

O SDK aplica regras personalizadas na ordem em que elas estão definidas. Se uma solicitação corresponder a várias regras personalizadas, o SDK aplicará somente a primeira regra.

nota

Se o SDK não conseguir acessar o X-Ray para obter regras de amostragem, ele reverte para uma regra local padrão da primeira solicitação recebida no início de cada segundo e cinco por cento de todas as solicitações adicionais por host. Isso pode ocorrer se o host não tiver permissão para chamar APIs de amostragem ou não conseguir se conectar ao daemon do X-Ray, que atua como um proxy de TCP para chamadas de API feitas pelo SDK.

Você também pode configurar o SDK para carregar regras de amostragem de um documento JSON. O SDK pode usar regras locais como backup para casos em que a amostragem do X-Ray não está disponível ou usar exclusivamente regras locais.

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

Este exemplo define uma regra personalizada e uma regra padrão. A regra personalizada aplica uma taxa de amostragem de 5% sem um número mínimo de solicitações para rastrear os caminhos em /api/move/. A regra padrão rastreia a primeira solicitação a cada segundo e 10% das solicitações adicionais.

A desvantagem de definir regras localmente é que o destino fixo é aplicado por instância do gravador de forma independente, em vez de ser gerenciado pelo serviço X-Ray. À medida que você implanta mais hosts, a taxa fixa é multiplicada, dificultando o controle da quantidade de dados registrados.

Ativado AWS Lambda, você não pode modificar a taxa de amostragem. Se sua função for chamada por um serviço instrumentado, as chamadas que geraram solicitações que foram amostradas por esse serviço serão registradas pelo Lambda. Se o rastreamento ativo estiver habilitado e nenhum cabeçalho de rastreamento estiver presente, o Lambda tomará a decisão de amostragem.

Para configurar regras de backup, faça com que o X-Ray SDK para .NET carregue as regras de amostragem de um arquivo com a configuração SamplingRuleManifest.

exemplo .NET Web.config – regras de amostragem

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

exemplo .NET Core appsettings.json: regras de amostragem

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

Para usar apenas regras locais, crie o gravador com uma LocalizedSamplingStrategy. Se você tiver regras de backup configuradas, remova essa configuração.

exemplo .NET global.asax: regras de amostragem locais

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

exemplo .NET Core Program.cs: regras de amostragem locais

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

Registro (.NET)

O X-Ray SDK para .NET usa o mesmo mecanismo de registro do AWS SDK for .NET. Se você já configurou seu aplicativo para registrar a AWS SDK for .NET saída, a mesma configuração se aplica à saída do X-Ray SDK for .NET.

Para configurar o registro, adicione uma seção de configuração chamada aws no arquivo App.config ou no arquivo Web.config.

exemplo Web.config – registro

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

Para obter mais informações, consulte Configuração do seu AWS SDK for .NET aplicativo no AWS SDK for .NET Guia do desenvolvedor.

Registro (.NET Core)

O X-Ray SDK para .NET usa as mesmas opções de registro em log do AWS SDK for .NET. Para configurar o registro em log de aplicações .NET Core, passe a opção de registro em log para o método AWSXRayRecorder.RegisterLogger.

Por exemplo, para usar o log4net, crie um arquivo de configuração que define o registrador, o formato de saída e o local do arquivo.

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

Em seguida, crie o registrador e aplique a configuração no código do seu programa.

exemplo .NET Core Program.cs: registro em log

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 obter mais informações sobre como configurar o log4net, consulte Configuration em logging.apache.org.

Variáveis de ambiente

Você pode usar variáveis de ambiente para configurar o X-Ray SDK para .NET. O SDK é compatível com as variáveis a seguir.

• AWS_XRAY_TRACING_NAME: defina um nome de serviço para o SDK usar para segmentos. Sobrepõe o nome do serviço que você definiu na estratégia de nomeação de segmentos do filtro do servlet.

• AWS_XRAY_DAEMON_ADDRESS: defina o host e a porta do receptor do daemon do X-Ray. Por padrão, o SDK usa 127.0.0.1:2000 para dados de rastreamento (UDP) e para amostragem (TCP). Use essa variável se você tiver configurado o daemon para escutar em uma porta diferente ou se ele estiver sendo executado em um host diferente.

  Formato

  • Mesma porta: address:port

  • Portas diferentes: tcp:address:port udp:address:port

• AWS_XRAY_CONTEXT_MISSING: defina como RUNTIME_ERROR para lançar exceções, caso o código instrumentado tente registrar dados quando nenhum segmento estiver aberto.

  Valores válidos

  • RUNTIME_ERROR: lance uma exceção de tempo de execução.

  • LOG_ERROR: registre um erro e continue (padrão).

  • IGNORE_ERROR: ignore o erro e continue.

  Erros relativos a segmentos ou subsegmentos ausentes poderão ocorrer quando você tentar usar um cliente instrumentado no código de inicialização que é executado quando nenhuma solicitação estiver aberta ou em um código que gere um novo thread.