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

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

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

对于 .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 的更多信息，请参阅配置 ASP.NET Core 应用程序在医生。微软网站上。

小节目录

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

Plugins

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

Plugins

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

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

例 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 守护程序，该程序充当 SDK 发出的 API 调用的 TCP 代理，则会发生这种情况。

您还可以配置开发工具包以加载 JSON 文档的采样规则。对于 X-Ray 采样不可用的情况，SDK 可以使用本地规则作为备份，或专门使用本地规则。

例采样规则 .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 会做出采样决定。

要配置备份规则，请指示适用于 .NET 的 X-Ray 开发工具包从具有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)

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

适用于 .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 的更多信息，请参阅配置关于登录 .apache.org 的信息。

环境变量

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

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

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

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

使用 .NET

传入请求