本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

# 配置适用于 .NET 的 X-Ray 开发工具包
配置

**注意**  
X-Ray SDK/Daemon 维护通知 — 2026 年 2 月 25 日， Amazon X-Ray SDKs/Daemon 将进入维护模式，在该模式下，X-Ray SDK 和 Daemon 的发布 Amazon 将仅限于解决安全问题。有关支持时间表的更多信息，请参阅 [X-Ray SDK 和 Daemon Support 时间表](xray-sdk-daemon-timeline.md)。我们建议迁移到 OpenTelemetry。有关迁移到的更多信息 OpenTelemetry，请参阅[从 X-Ray 仪器迁移到 OpenTelemetry 仪器](https://docs.amazonaws.cn/xray/latest/devguide/xray-sdk-migration.html)。

您可以配置带有插件的适用于 .NET 的 X-Ray 开发工具包 以包括应用程序在其上运行的服务的相关信息，修改默认采样行为，或者添加应用于特定路径请求的采样规则。

对于 .NET Web 应用程序，请将密钥添加到 `appSettings` 文件的 `Web.config` 部分。

**Example Web.config**  

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

对于 .NET Core，请使用名为 `appsettings.json` 的顶层密钥创建名为 `XRay` 的文件。

**Example .NET appsettings.json**  

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

然后，在应用程序代码中，生成配置对象并将其用于初始化 X-Ray 记录器。在[初始化记录器](xray-sdk-dotnet-messagehandler.md#xray-sdk-dotnet-messagehandler-startupcs)之前执行此操作。

**Example .NET Core Program.cs 记录器配置**  

```
using [Amazon.XRay.Recorder.Core](https://docs.amazonaws.cn/xray-sdk-for-dotnet/latest/reference/html/N_Amazon_XRay_Recorder_Core.htm);
...
AWSXRayRecorder.InitializeInstance(configuration);
```

如果您正在检测 .NET Core Web 应用程序，则在[配置消息处理程序](xray-sdk-dotnet-messagehandler.md#xray-sdk-dotnet-messagehandler-startupcs)时，还可以将配置对象传递到 `UseXRay` 方法。对于 Lambda 函数，使用上面所示的 `InitializeInstance` 方法。

有关 .NET Core 配置 API 的更多信息，请参阅 docs.microsoft.com 上的[配置 ASP.NET Core 应用程序](https://docs.microsoft.com/en-us/aspnet/core/fundamentals/configuration/?tabs=basicconfiguration)。

**Topics**
+ [

## 插件
](#xray-sdk-dotnet-configuration-plugins)
+ [

## 采样规则
](#xray-sdk-dotnet-configuration-sampling)
+ [

## 日志记录 (.NET)
](#xray-sdk-dotnet-configuration-logging)
+ [

## 日志记录 (.NET Core)
](#xray-sdk-dotnet-configuration-corelogging)
+ [

## 环境变量
](#xray-sdk-dotnet-configuration-envvars)

## 插件


使用插件可添加有关托管您应用程序的服务的数据。

**插件**
+ Amazon EC2 — `EC2Plugin` 添加实例 ID、可用区和 CloudWatch 日志组。
+ Elastic Beanstalk - `ElasticBeanstalkPlugin` 添加环境名称、版本标签和部署 ID。
+ Amazon ECS — `ECSPlugin` 添加容器 ID。

要使用插件，请通过添加 `AWSXRayPlugins` 设置配置适用于 .NET 的 X-Ray 开发工具包客户端。如果多个插件应用到您的应用程序，请在同一个设置中指定所有这些设置，以逗号分隔。

**Example Web.config - 插件**  

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

**Example .NET Core appsettings.json 插件**  

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

## 采样规则


该 SDK 使用您在 X-Ray 控制台中定义的采样规则来确定要记录的请求。默认规则跟踪每秒的第一个请求，以及所有将跟踪发送到 X-Ray 的服务的任何其他请求的百分之五。[在 X-Ray 控制台中创建其他规则](xray-console-sampling.md)以自定义为每个应用程序记录的数据量。

该 SDK 按照定义的顺序应用自定义规则。如果请求与多个自定义规则匹配，则 SDK 仅应用第一条规则。

**注意**  
如果 SDK 无法访问 X-Ray 来获取采样规则，它将恢复为默认的本地规则，即每秒第一个请求以及每个主机所有其他请求的百分之五。如果主机无权调用采样，或者无法连接到 X-Ray 守护程序 APIs，后者充当 SDK 发出的 API 调用的 TCP 代理，则可能会发生这种情况。

您还可以将 SDK 配置为从 JSON 文档加载采样规则。在 X-Ray 采样不可用的情况下，SDK 可以使用本地规则作为备份，也可以只使用本地规则。

**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
  }
}
```

此示例定义了一个自定义规则和一个默认规则。自定义规则采用百分之五的采样率，对于 `/api/move/` 之下的路径要跟踪的请求数量不设下限。默认规则中每秒的第一个请求以及其他请求的百分之十。

在本地定义规则的缺点是，固定目标由记录器的每个实例独立应用而不是由 X-Ray 服务管理。随着您部署更多主机，固定速率会成倍增加，这使得控制记录的数据量变得更加困难。

启 Amazon Lambda用，您无法修改采样率。如果您的函数由检测服务调用，Lambda 将记录生成由该服务采样的请求的调用。如果启用了主动跟踪且不存在任何跟踪标头，则 Lambda 会做出采样决定。

要配置备份规则，请指示从具有适用于 .NET 的 X-Ray 开发工具包 `SamplingRuleManifest` 设置的文件加载采样规则。

**Example .NET Web.config - 采样规则**  

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

**Example .NET Core appsettings.json 采样规则**  

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

要仅使用本地规则，请使用 `LocalizedSamplingStrategy` 构建记录器。如果您配置了备份规则，请删除该配置。

**Example .NET global.asax - 本地采样规则**  

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

**Example .NET Core Program.cs - 本地采样规则**  

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

## 日志记录 (.NET)


适用于 .NET 的 X-Ray 开发工具包使用与 [适用于 .NET 的 Amazon SDK](https://docs.amazonaws.cn/sdk-for-net/v3/developer-guide/net-dg-config-other.html#config-setting-awslogging) 相同的日志记录机制。如果您已经将应用程序配置为记录 适用于 .NET 的 Amazon SDK 输出，则同样的配置也适用于适用于.NET 的 X-Ray SDK 的输出。

要配置日志记录，请将名为 `aws` 的配置部分添加到您的 `App.config` 文件或 `Web.config` 文件。

**Example Web.config - 日志记录**  

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

有关更多信息，请参阅 [适用于 .NET 的 Amazon SDK 开发人员指南](https://docs.amazonaws.cn/sdk-for-net/latest/developer-guide/net-dg-config.html) 中的*配置您的适用于 .NET 的 Amazon SDK 应用程序*。

## 日志记录 (.NET Core)


适用于 .NET 的 X-Ray 开发工具包使用与 [适用于 .NET 的 Amazon SDK](https://docs.amazonaws.cn/sdk-for-net/v3/developer-guide/net-dg-config-other.html#config-setting-awslogging) 相同的日志记录选项。要为 .NET Core 应用程序配置日志记录，请将日志选项传递给 `AWSXRayRecorder.RegisterLogger` 方法。

例如，要使用 log4net，请创建定义记录器的配置文件、输出格式和文件位置。

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

然后，创建记录器并在程序代码中应用配置。

**Example .NET Core Program.cs - 日志记录**  

```
using log4net;
using [Amazon.XRay.Recorder.Core](https://docs.amazonaws.cn/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)
  {
  ...
  }
}
```

有关配置 log4net 的更多信息，请参阅 logging.apache.org 上的[配置](https://logging.apache.org/log4net/release/manual/configuration.html)。

## 环境变量


您可以使用环境变量配置适用于.NET 的 X-Ray 开发工具包。SDK 支持以下变量。
+ `AWS_XRAY_TRACING_NAME` - 设置开发工具包用于进行分段的服务名称。覆盖您根据 servlet 筛选器的[分段命名策略](xray-sdk-dotnet-messagehandler.md#xray-sdk-dotnet-messagehandler-naming)设置的服务名称。
+ `AWS_XRAY_DAEMON_ADDRESS` - 设置 X-Ray 进程守护程序侦听器的主机和端口。默认情况下，SDK 使用用于跟踪数据（UDP）和采样（TCP）的 `127.0.0.1:2000`。如果您已将进程守护程序配置为[侦听不同端口](xray-daemon-configuration.md)或者进程守护程序在另一台主机上运行，则使用此变量。

**Format**
  + **同一个端口** — `address:port`
  + **不同的端口** — `tcp:address:port udp:address:port`
+ `AWS_XRAY_CONTEXT_MISSING` - 设置为 `RUNTIME_ERROR` 在您的已检测代码尝试在分段未打开的情况下记录数据时引发异常。

**有效值**
  + `RUNTIME_ERROR`— 引发运行时异常。
  + `LOG_ERROR`— 记录错误并继续（默认）。
  + `IGNORE_ERROR`— 忽略错误并继续。

  对于在未打开任何请求时运行的启动代码或者会生成新线程的代码，如果您尝试在其中使用检测过的客户端，则可能发生与缺失分段或子分段相关的错误。