NET 用 X-Ray SDK の設定

X-Ray SDK for .NET にプラグインを設定して、アプリケーションが実行されているサービスに関する情報が含めたり、デフォルトのサンプリング動作を変更したり、特定のパスに対するリクエストに適用されるサンプリングルールを追加したりできます。

.NET ウェブアプリケーションの場合は、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 – Recorder 設定

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

.NET Core ウェブアプリケーションを計測する場合は、UseXRayメッセージ ハンドラーを設定するときに、設定オブジェクトを メソッドに渡すこともできます。Lambda 関数の場合は、上記のように InitializeInstance メソッドを使用します。

.NET Core 設定 API の詳細については、docs.microsoft.com の「ASP.NET Core アプリを構成する」を参照してください。

プラグイン

プラグインを使用して、アプリケーションをホストしているサービスに関するデータを追加します。

プラグイン

• Amazon EC2 —EC2Pluginは、インスタンス ID、アベイラビリティーゾーン、および CloudWatch Logs グループを追加します。

• ElasticBeanstalk– 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"
  }
}

サンプリングルール

SDK は X-Ray コンソールで定義したサンプリングルールを使用し、記録するリクエストを決定します。デフォルトルールでは、最初のリクエストを毎秒トレースし、X-Ray にトレースを送信するすべてのサービスで追加のリクエストの 5% をトレースします。X-Ray コンソールに追加のルールを作成するをクリックして、各アプリケーションで記録されるデータ量をカスタマイズします。

SDK は、定義された順序でカスタムルールを適用します。リクエストが複数のカスタムルールと一致する場合、SDK は最初のルールのみを適用します。

注記

SDK が X-Ray に到達してサンプリングルールを取得できない場合、1 秒ごとに最初のリクエストのデフォルトのローカルルールに戻り、ホストあたりの追加リクエストの 5% に戻ります。これは、ホストがサンプリング API を呼び出す権限を持っていない場合や、SDK によって行われる API 呼び出しの TCP プロキシとして機能する X-Ray デーモンに接続できない場合に発生します。

JSON ドキュメントからサンプリングルールをロードするように SDK を設定することもできます。SDK は、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
  }
}

この例では、1 つのカスタムルールとデフォルトルールを定義します。カスタムルールでは、5 パーセントのサンプリングレートが適用され、/api/move/以下のパスに対してトレースするリクエストの最小数はありません。デフォルトのルールでは、1秒ごとの最初のリクエストおよび追加リクエストの 10 パーセントをトレースします。

ルールをローカルで定義することの欠点は、固定ターゲットが X-Ray サービスによって管理されるのではなく、レコーダーの各インスタンスによって個別に適用されることです。より多くのホストをデプロイすると、固定レートが乗算され、記録されるデータ量の制御が難しくなります。

AWS Lambdaの場合、サンプリングレートは変更できません。関数がインストルメント化されたサービスによって呼び出された場合、そのサービスによってサンプリングされたリクエストを生成した呼び出しは Lambda によって記録されます。アクティブなトレースが有効で、トレースヘッダーが存在しない場合、Lambda はサンプリングを決定します。

バックアップルールを設定するには、SamplingRuleManifest 設定を使用して X-Ray SDK for .NET にファイルからサンプリングルールをロードするように指示します。

例 .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 – Local サンプリングルール

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

ログ記録 (.NET)

X-Ray SDK for .NET では、AWS SDK for .NET。すでに AWS SDK for .NET 出力をログに記録するようにアプリケーションを設定している場合は、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>

詳細については、『AWS SDK for .NET 開発者ガイド』の「AWS SDK for .NET アプリケーションの設定」を参照してください。

ログ記録 (.NET Core)

X-Ray SDK for .NET では、AWS SDK for .NET。.NET Core アプリケーションのロギングを構成するには、logging オプションを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 で設定を参照してください。

環境変数

環境変数を使用して、X-Ray SDK を .NET 用に設定できます。SDK は次の変数をサポートしています。

• AWS_XRAY_TRACING_NAME – SDK がセグメントに使用するサービス名を設定します。サーブレットフィルタのセグメント命名ルールで設定したサービス名を上書きします。

• AWS_XRAY_DAEMON_ADDRESS – X-Ray デーモン リスナーのホストとポートを設定します。デフォルトでは、SDK はトレースデータ (UDP) とサンプリング (TCP) の両方に127.0.0.1:2000を使用します。この変数は、デーモンを次のように構成している場合に使用します。別のポートでリッスンするまたは、別のホストで実行されている場合。

  [Format] (形式)

  • 同じポート – address:port

  • 異なるポート – tcp:address:port udp:address:port

• AWS_XRAY_CONTEXT_MISSING – 計測されたコードが、セグメントが開いていないときにデータを記録しようとした場合に例外をスローするには、RUNTIME_ERROR に設定します。

  有効な値

  • RUNTIME_ERROR – ランタイム例外をスローします。

  • LOG_ERROR – エラーをログ記録して続行します (デフォルト)。

  • IGNORE_ERROR – エラーを無視して続行します。

  オープン状態のリクエストがない場合、または新しいスレッドを発生させるコードで、スタートアップコードに実装されたクライアントを使用しようとした場合に発生する可能性がある、セグメントまたはサブセグメントの欠落に関連するエラー。