As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.

# Configurar o X-Ray SDK para .NET
<a name="xray-sdk-dotnet-configuration"></a>

**nota**  
Aviso de SDK/Daemon manutenção do X-Ray — Em 25 de fevereiro de 2026, o AWS X-Ray SDKs/Daemon entrará no modo de manutenção, onde AWS limitará as versões do X-Ray SDK e do Daemon para tratar apenas de problemas de segurança. Para obter mais informações sobre a linha do tempo do suporte, consulte [Cronograma de suporte do X-Ray SDK e do Daemon Support](xray-sdk-daemon-timeline.md). Recomendamos migrar para o. OpenTelemetry Para obter mais informações sobre a migração para OpenTelemetry, consulte [Migrando da instrumentação X-Ray para a instrumentação](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html). OpenTelemetry 

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

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

**Example 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`.

**Example .NET appsettings.json**  

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

Em seguida, no código do aplicativo, crie um objeto de configuração e use-o para inicializar o gravador do X-Ray. Faça isso antes de [inicializar o gravador](xray-sdk-dotnet-messagehandler.md#xray-sdk-dotnet-messagehandler-startupcs).

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

```
using [Amazon.XRay.Recorder.Core](https://docs.aws.amazon.com/xray-sdk-for-dotnet/latest/reference/html/N_Amazon_XRay_Recorder_Core.htm);
...
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](xray-sdk-dotnet-messagehandler.md#xray-sdk-dotnet-messagehandler-startupcs). 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](https://docs.microsoft.com/en-us/aspnet/core/fundamentals/configuration/?tabs=basicconfiguration) no site docs.microsoft.com.

**Topics**
+ [Plugins](#xray-sdk-dotnet-configuration-plugins)
+ [Regras de amostragem](#xray-sdk-dotnet-configuration-sampling)
+ [Registro (.NET)](#xray-sdk-dotnet-configuration-logging)
+ [Registro (.NET Core)](#xray-sdk-dotnet-configuration-corelogging)
+ [Variáveis de ambiente](#xray-sdk-dotnet-configuration-envvars)

## Plugins
<a name="xray-sdk-dotnet-configuration-plugins"></a>

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

**Plugins**
+ 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.

**Example Web.config – plugins**  

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

**Example .NET Core appsettings.json: plugins**  

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

## Regras de amostragem
<a name="xray-sdk-dotnet-configuration-sampling"></a>

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](xray-console-sampling.md) para personalizar a quantidade de dados registrados para cada uma dos aplicativos.

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 reverterá para uma regra local padrão da primeira solicitação a cada segundo e 5% de todas as solicitações adicionais por host. Isso pode ocorrer se o host não tiver permissão para chamar a amostragem APIs ou não conseguir se conectar ao daemon X-Ray, que atua como um proxy 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.

**Example 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`.

**Example .NET Web.config – regras de amostragem**  

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

**Example .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.

**Example .NET global.asax: regras de amostragem locais**  

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

**Example .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)
<a name="xray-sdk-dotnet-configuration-logging"></a>

O X-Ray SDK para .NET usa o mesmo mecanismo de registro do [AWS SDK para .NET](https://docs.aws.amazon.com/sdk-for-net/v3/developer-guide/net-dg-config-other.html#config-setting-awslogging). Se você já configurou seu aplicativo para registrar a AWS SDK para .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`.

**Example 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 para .NET aplicativo](https://docs.aws.amazon.com/sdk-for-net/latest/developer-guide/net-dg-config.html) no *AWS SDK para .NET Guia do desenvolvedor*.

## Registro (.NET Core)
<a name="xray-sdk-dotnet-configuration-corelogging"></a>

O X-Ray SDK para .NET usa as mesmas opções de registro em log do [AWS SDK para .NET](https://docs.aws.amazon.com/sdk-for-net/v3/developer-guide/net-dg-config-other.html#config-setting-awslogging). Para configurar o registro em log de aplicativos .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.

**Example .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.

**Example .NET Core Program.cs: registro em log**  

```
using log4net;
using [Amazon.XRay.Recorder.Core](https://docs.aws.amazon.com/xray-sdk-for-dotnet/latest/reference/html/N_Amazon_XRay_Recorder_Core.htm);

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](https://logging.apache.org/log4net/release/manual/configuration.html) em logging.apache.org.

## Variáveis de ambiente
<a name="xray-sdk-dotnet-configuration-envvars"></a>

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](xray-sdk-dotnet-messagehandler.md#xray-sdk-dotnet-messagehandler-naming) 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](xray-daemon-configuration.md) 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.