設定的 X-Ray SDK。 NET - AWS X-Ray
外掛程式抽樣規則日誌記錄 (. NET)日誌記錄 (. NET核心)環境變數

本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

設定的 X-Ray SDK。 NET

您可以SDK為其配置 X-Ray。 NET使用外掛程式來包含應用程式執行所在服務的相關資訊、修改預設取樣行為，或新增適用於特定路徑要求的取樣規則。

對於. NETWeb 應用程序，將密鑰添加到Web.config文件的appSettings部分。

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

對於. NET核心，創建一個名為appsettings.json頂級密鑰的文件XRay。

範例 。 NET應用程序設置
{
  "XRay": {
    "AWSXRayPlugins": "EC2Plugin",
    "SamplingRuleManifest": "sampling-rules.json"
  }
}

然後，在您的應用程式程式碼中，建立設定物件，並使用它來初始化 X-Ray 記錄器。請在初始化記錄器前執行此作業。

範例 。 NET核心 Program.cs-記錄器配置
using Amazon.XRay.Recorder.Core;
...
AWSXRayRecorder.InitializeInstance(configuration);

如果您正在檢測. NET核心 Web 應用程序，您也可以在配置消息處理程序時將配置對象傳遞給該UseXRay方法。對於 Lambda 函數，請使用如上所示的InitializeInstance方法。

如需有關. NET核心配置API，請參閱配置ASP. NET文檔微軟的核心應用程序。

外掛程式

使用外掛程式來新增託管您應用程式的服務相關資料。

外掛程式

  • Amazon EC2 — EC2Plugin 新增執行個體 ID、可用區域和 CloudWatch 日誌群組。

  • Elastic Beanstalk — ElasticBeanstalkPlugin 新增環境名稱、版本標籤和部署 ID。

  • Amazon ECS-ECSPlugin 添加容器 ID。

若要使用外掛程式，請設定SDK的 X-Ray。 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套用第一個規則。

注意

如果無法達到 X-Ray SDK 以取得取樣規則，則會回復為每秒第一個要求的預設本機規則，而每個主機的任何其他要求的百分之五。如果主機沒有呼叫取樣的權限APIs，或者無法連線至 X-Ray 精靈 (做為SDK. TCP API

您也可以配置SDK為從JSON文件載入取樣規則。對於無法使用 X-Ray 取樣的情況，SDK可以使用本機規則做為備份，或僅使用本機規則。

範例 採樣規則
{
  "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 會做出取樣決策。

要配置備份規則，SDK請告訴 X-Ray。 NET從具有設定的檔案載入取樣規SamplingRuleManifest則。

範例 。 NETWeb. 配置-採樣規則
<configuration>
  <appSettings>
    <add key="SamplingRuleManifest" value="sampling-rules.json"/>
  </appSettings>
</configuration>
範例 。 NET核心應用程序設置 .json-採樣規則
{
  "XRay": {
    "SamplingRuleManifest": "sampling-rules.json"
  }
}

若僅要使用本機規則，請使用 LocalizedSamplingStrategy 建置記錄器。若您已設定備份規則，請移除該組態。

範例 。 NET全球抽樣規則
var recorder = new AWSXRayRecorderBuilder().WithSamplingStrategy(new LocalizedSamplingStrategy("samplingrules.json")).Build();
AWSXRayRecorder.InitializeInstance(recorder: recorder);
範例 。 NET核心 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核心日誌
<?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核心 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 的設定。

環境變數

您可以使用環境變數來規劃 X-Ray SDK。 NET。支SDK援下列變數。

  • 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— 記錄錯誤並繼續 (預設值)。

    • IGNORE_ERROR— 忽略錯誤並繼續。

    當您嘗試在沒有要求開啟時執行的啟動程式碼中使用已檢測的用戶端，或在產生新執行緒的程式碼中使用已檢測的用戶端時，可能會發生與遺失區段或子區段相關的錯誤。