将 X-Ray 配置SDK为. NET

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

对于。 NETWeb 应用程序，向Web.config文件appSettings部分添加密钥。

例 Web.config


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

对于。 NETCore，创建一个名为appsettings.json的文件，其顶级密钥名为XRay。

例。 NETappsettings.


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

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

例。 NETCore Program.cs — 录制器配置


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

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

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

插件

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

插件

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

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

例 Web.config - 插件


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

例。 NET核心应用程序设置.json — 插件


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

采样规则

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

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

注意

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

您也可以将配置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
  }
}

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

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

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

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

例。 NETWeb.config-采样规则


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

例。 NET核心应用程序设置.json — 采样规则


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

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

例。 NETglobal.asax — 本地抽样规则


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

例。 NETCore Program.cs — 本地采样规则


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

日志 (。 NET)

X-Ray SDK 适用于. NET使用与. 相同的日志记录机制AWS SDK for .NET。如果您已经将应用程序配置为记录 AWS SDK for .NET 输出，则同样的配置也适用于 X-Ray SDK 的输出。 NET。

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

例 Web.config - 日志记录


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

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

日志 (。 NET核心)

X-Ray SDK 适用于. NET使用的日志记录选项与AWS SDK for .NET。为配置日志记录。 NET核心应用程序，将日志选项传递给AWSXRayRecorder.RegisterLogger方法。

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

例。 NET核心日志4net.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>

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

例。 NETCore 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 上的配置。

环境变量

您可以使用环境变量为其配置 X-R SDK ay。 NET。SDK支持以下变量。

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

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

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

文档惯例

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

传入请求

将 X-Ray 配置SDK为. NET

例 Web.config

例 。 NETappsettings.

例 。 NETCore Program.cs — 录制器配置