为 .NET X-Ray SDK for .NET

您可以使用插件配置 X-Ray SDK for .NET，使其包含有关应用程序运行的服务的信息、修改默认采样行为或添加适用于特定路径请求的采样规则。

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

例 Web.config


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

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

例 .NET appsettings.json


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

然后，在应用程序代码中生成一个配置对象并使用它来初始化 X-Ray 记录器。在初始化记录器之前执行此操作。

例 .NET Core Program.cs — 录制器配置


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

如果您正在检测 .NET Core Web 应用程序，也可以在配置消息处理程序时将配置对象传递给该UseXRay方法。对于 Lambda 函数，请使用上面所示InitializeInstance的方法。

有关.NET Core 配置 API 的更多信息，请参阅在 docs.microsoft.com 上配置 ASP.NET 核心应用程序。

小节目录

插件
采样规则
日志记录 (.NET)
日志记录 (.NET Core)
环境变量

插件

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

插件

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

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

例 Web.config-插件


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

例 .NET 酷睿 appsettings.json


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

采样规则

SDK 使用您在 X-Ray 控制台中定义的采样规则来确定要记录哪些请求。默认规则每秒跟踪第一个请求，以及向 X-Ray 发送跟踪的所有服务中所有额外请求的 5%。在 X-Ray 控制台中创建其他规则，以自定义每个应用程序记录的数据量。

开发工具包将按定义顺序应用自定义规则。如果一个请求匹配多个自定义规则，则 SDK 仅应用第一条规则。

注意

如果 SDK 无法访问 X-Ray 获取采样规则，它将恢复为每秒第一个请求的默认本地规则，以及每台主机所有额外请求的 5%。如果主机没有调用采样 API 的权限，或者无法连接到 X-Ray 守护程序，后者充当 SDK 发出 API 调用的 TCP 代理，则可能会发生这种情况。

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

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

此示例定义了一条自定义规则和一条默认规则。自定义规则采用 5% 的采样率，对于下方的路径，要追踪的请求数没有最低限制/api/move/。默认规则每秒跟踪第一个请求和 10% 的其他请求。

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

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

要配置备份规则，请告诉 X-Ray SDK for .NET 从具有该SamplingRuleManifest设置的文件中加载采样规则。

例 .NET Web.config-采样


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

例 .NET Core appsettings.json —


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

要仅使用本地规则，请使用生成录制器LocalizedSamplingStrategy。如果您配置了备份规则，请删除该配置。

例 .NET global.asax — 本地抽样规则


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

例 .NET Core Program.cs — 本地采样规则


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

日志记录 (.NET)

SDK for .NET X-Ray 开发工具包使用与相同的日志记录机制Amazon SDK for .NET。如果您已将应用程序配置为记录Amazon SDK for .NET输出，则相同的配置SDK for .NET X-Ray 开发工具包的输出。

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

例 Web.config-日志


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

有关更多信息，请参阅 Amazon SDK for .NET 开发人员指南中的配置您的 Amazon SDK for .NET 应用程序。

日志记录 (.NET Core)

SDK for .NET X-Ray 开发工具包使用与相同的日志记录选项Amazon SDK for .NET。要为 .NET Core 应用程序配置日志记录，请将日志记录选项传递给AWSXRayRecorder.RegisterLogger方法。

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

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

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

例 .NET Core Program.cs — 日志


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

有关配置 log4net 的更多信息，请参阅 logging.apache.org 上的配置。

环境变量

您可以使用环境变量来配置SDK for .NET X-Ray 开发工具包。开发工具包支持以下变量。

AWS_XRAY_TRACING_NAME— 设置 SDK 用于分段的服务名称。覆盖您根据 servlet 筛选器的分段命名策略设置的服务名称。
AWS_XRAY_DAEMON_ADDRESS— 设置 X-Ray 守护程序侦听器的主机和端口。默认情况下，SDK 同时使用127.0.0.1:2000跟踪数据 (UDP) 和采样 (TCP)。如果您已将守护程序配置为监听不同的端口，或者它在不同的主机上运行，请使用此变量。
格式
- 同一个端口 —address:port
- 不同的端口 —tcp:address:port udp:address:port
AWS_XRAY_CONTEXT_MISSING— 设置为RUNTIME_ERROR，当您的仪表代码在未打开分段时尝试记录数据时抛出异常。
有效值
- RUNTIME_ERROR— 引发运行时异常。
- LOG_ERROR— 记录错误并继续（默认）。
当您尝试在未打开请求时运行的启动代码或生成新线程的代码中使用已检测的客户端时，可能会发生与缺失分段或子分段相关的错误。

Javascript 在您的浏览器中被禁用或不可用。

要使用 Amazon Web Services 文档，必须启用 Javascript。请参阅浏览器的帮助页面以了解相关说明。

SDK for .NET X-Ray

传入请求