配置 X-Ray SDK for .NET - AWS X-Ray
插件采样规则日志记录 (.NET)日志记录 (.NET Core)环境变量
AWS 文档中描述的 AWS 服务或功能可能因区域而异。要查看适用于中国区域的差异，请参阅中国的 AWS 服务入门。

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

配置 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 Core 应用程序。

插件

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

插件

  • Amazon EC2 – EC2Plugin 会添加实例 ID、可用区和 CloudWatch Logs 组。

  • Elastic Beanstalk – ElasticBeanstalkPlugin 添加环境名称、版本标签和部署 ID。

  • Amazon ECS – ECSPlugin 添加容器 ID。

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

例 Web.config - 插件

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

例 .NET Core appsettings.json – 插件

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

采样规则

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

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

注意

如果开发工具包无法访问 X-Ray 来获取示例规则，则它将恢复为使用每台主机的默认本地规则每秒的第一个请求，以及任何额外请求中的 5%。如果主机无权调用采样 API，或者无法连接到 X-Ray 守护程序（充当开发工具包所发出 API 调用的 TCP 代理），则可能出现此情况。

您还可将开发工具包配置为加载 JSON 文档中的采样规则。开发工具包可以在 X-Ray 采样不可用的情况下使用本地规则作为备份，或仅使用本地规则。

例 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/ 下的路径的请求未设置最低追踪请求数量。默认规则将跟踪每秒的第一个请求，以及任何额外请求中的 10%。

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

在 AWS 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);

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

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

日志记录 (.NET)

X-Ray SDK for .NET使用与适用于 .NET 的 AWS 开发工具包相同的日志记录机制。如果您已经将应用程序配置为记录适用于 .NET 的 AWS 开发工具包输出，则相同的配置也适用于来自X-Ray SDK for .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>

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

日志记录 (.NET Core)

对于 .NET Core 应用程序，X-Ray 开发工具包支持适用于 .NET 的 AWS 开发工具包 LoggingOptions 枚举中的日志记录选项。要配置日志记录，请将这些选项之一传递到 RegisterLogger 方法。 

AWSXRayRecorder.RegisterLogger(LoggingOptions.Console);

例如，要使用 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 上的配置。

环境变量

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

  • AWS_XRAY_TRACING_NAME – 设置开发工具包用于进行分段的服务名称。覆盖您根据 servlet 筛选器的分段命名策略设置的服务名称。

  • AWS_XRAY_DAEMON_ADDRESS – 设置 X-Ray 守护程序侦听器的主机和端口。默认情况下，开发工具包对跟踪数据 (UDP) 和采样 (TCP) 使用 127.0.0.1:2000。如果您已将守护程序配置为在不同的端口上侦听，或者它运行在其他主机上，请使用该变量。

    格式

    • 相同端口 – address:port

    • 不同端口 – tcp:address:port udp:address:port

  • AWS_XRAY_CONTEXT_MISSING – 设置为 LOG_ERROR 可避免在您的已检测代码尝试在分段未打开的情况下记录数据时引发异常。

    有效值

    • RUNTIME_ERROR – 引发运行时异常（默认）。

    • LOG_ERROR – 记录错误并继续。

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