翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。

# NET 用 X-Ray SDK の設定
<a name="xray-sdk-dotnet-configuration"></a>

**注記**  
X-Ray SDK/デーモンメンテナンス通知 – 2026 年 2 月 25 日に、 AWS X-Ray SDKs/Daemon はメンテナンスモードに移行します。 AWS は、X-Ray SDK とデーモンのリリースをセキュリティ上の問題にのみ対処するように制限します。サポートタイムラインの詳細については、「[X-Ray SDK とデーモンのサポートタイムライン](xray-sdk-daemon-timeline.md)」を参照してください。OpenTelemetry に移行することをお勧めします。OpenTelemetry への移行の詳細については、「[X-Ray による計装から OpenTelemetry による計装への移行](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html)」を参照してください。

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

.NET ウェブアプリケーションの場合は、`appSettings` ファイルの `Web.config` セクションにキーを追加します。

**Example Web.config**  

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

.NET Core の場合は、`appsettings.json` という最上位のキーを持つ `XRay` という名前のファイルを作成します。

**Example .NET appsettings.json**  

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

次に、アプリケーションコードで、設定オブジェクトを構築し、それを使用して X-Ray レコーダーを初期化します。この操作は、[レコーダーを初期化](xray-sdk-dotnet-messagehandler.md#xray-sdk-dotnet-messagehandler-startupcs)する前に実行します。

**Example .NET Core Program.cs – Recorder 設定**  

```
using [Amazon.XRay.Recorder.Core](https://docs.aws.amazon.com/xray-sdk-for-dotnet/latest/reference/html/N_Amazon_XRay_Recorder_Core.htm);
...
AWSXRayRecorder.InitializeInstance(configuration);
```

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

.NET Core 設定 API の詳細については、docs.microsoft.com の[「ASP.NET Core アプリを構成する」](https://docs.microsoft.com/en-us/aspnet/core/fundamentals/configuration/?tabs=basicconfiguration)を参照してください。

**Topics**
+ [プラグイン](#xray-sdk-dotnet-configuration-plugins)
+ [サンプリングルール](#xray-sdk-dotnet-configuration-sampling)
+ [ログ記録 (.NET)](#xray-sdk-dotnet-configuration-logging)
+ [ログ記録 (.NET Core)](#xray-sdk-dotnet-configuration-corelogging)
+ [環境変数](#xray-sdk-dotnet-configuration-envvars)

## プラグイン
<a name="xray-sdk-dotnet-configuration-plugins"></a>

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

**プラグイン**
+ Amazon EC2 —`EC2Plugin`は、インスタンス ID、アベイラビリティーゾーン、および CloudWatch Logs グループを追加します。
+ ElasticBeanstalk– `ElasticBeanstalkPlugin`は、環境名、バージョンラベル、およびデプロイ ID を追加します。
+ Amazon ECS —`ECSPlugin`は、コンテナ ID を追加します。

プラグインを使用するには、`AWSXRayPlugins` 設定を追加して X-Ray SDK for .NET クライアントを設定します。複数のプラグインがアプリケーションに適用される場合は、そのすべてをカンマで区切って同じ設定で指定します。

**Example Web.config - プラグイン**  

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

**Example .NET Core appsettings.json – プラグイン**  

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

## サンプリングルール
<a name="xray-sdk-dotnet-configuration-sampling"></a>

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

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

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

JSON ドキュメントからサンプリングルールをロードするように SDK を設定することもできます。SDK は、X-Ray サンプリングが利用できない場合のバックアップとしてローカルルールを使用することも、ローカルルールを排他的に使用することもできます。

**Example 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 にファイルからサンプリングルールをロードするように指示します。

**Example .NET Web.config - サンプリングルール**  

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

**Example .NET Core appsettings.json – サンプリングルール**  

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

ローカルルールのみを使用するには、`LocalizedSamplingStrategy` でレコーダーをビルドします。バックアップルールが設定されている場合、その設定を削除します。

**Example .NET global.asax – ローカルサンプリングルール**  

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

**Example .NET Core Program.cs – Local サンプリングルール**  

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

## ログ記録 (.NET)
<a name="xray-sdk-dotnet-configuration-logging"></a>

X-Ray SDK for .NET では、[AWS SDK for .NET](https://docs.aws.amazon.com/sdk-for-net/v3/developer-guide/net-dg-config-other.html#config-setting-awslogging)。 AWS SDK for .NET 出力をログに記録するようにアプリケーションを設定済みの場合、X-Ray SDK for .NET からの出力にも同じ設定が適用されます。

ログ記録を設定するには、`aws` ファイルまたは `App.config` ファイルに、`Web.config` という名前の設定セクションを追加します。

**Example Web.config - ログ記録**  

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

詳細については、『[AWS SDK for .NET 開発者ガイド](https://docs.aws.amazon.com/sdk-for-net/latest/developer-guide/net-dg-config.html)』の「*AWS SDK for .NET アプリケーションの設定*」を参照してください。

## ログ記録 (.NET Core)
<a name="xray-sdk-dotnet-configuration-corelogging"></a>

X-Ray SDK for .NET では、[AWS SDK for .NET](https://docs.aws.amazon.com/sdk-for-net/v3/developer-guide/net-dg-config-other.html#config-setting-awslogging)。.NET Core アプリケーションのロギングを構成するには、logging オプションを`AWSXRayRecorder.RegisterLogger`方法。

たとえば、log4net を使用するには、ロガー、出力形式、およびファイルの場所を定義する設定ファイルを作成します。

**Example .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>
```

次に、ロガーを作成し、プログラムコードで設定を適用します。

**Example .NET Core Program.cs – ロギング**  

```
using log4net;
using [Amazon.XRay.Recorder.Core](https://docs.aws.amazon.com/xray-sdk-for-dotnet/latest/reference/html/N_Amazon_XRay_Recorder_Core.htm);

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 で[設定](https://logging.apache.org/log4net/release/manual/configuration.html)を参照してください。

## 環境変数
<a name="xray-sdk-dotnet-configuration-envvars"></a>

環境変数を使用して、X-Ray SDK を .NET 用に設定できます。SDK は次の変数をサポートしています。
+ `AWS_XRAY_TRACING_NAME` – SDK がセグメントに使用するサービス名を設定します。サーブレットフィルタの[セグメント命名ルール](xray-sdk-dotnet-messagehandler.md#xray-sdk-dotnet-messagehandler-naming)で設定したサービス名を上書きします。
+ `AWS_XRAY_DAEMON_ADDRESS` – X-Ray デーモン リスナーのホストとポートを設定します。デフォルトでは、SDK はトレースデータ (UDP) とサンプリング (TCP) の両方に`127.0.0.1:2000`を使用します。この変数は、デーモンを次のように構成している場合に使用します。[別のポートでリッスンする](xray-daemon-configuration.md)または、別のホストで実行されている場合。

**形式**
  + **同じポート** – `{{address}}:{{port}}`
  + **異なるポート** – `tcp:{{address}}:{{port}} udp:{{address}}:{{port}}`
+ `AWS_XRAY_CONTEXT_MISSING` – 計測されたコードが、セグメントが開いていないときにデータを記録しようとした場合に例外をスローするには、`RUNTIME_ERROR` に設定します。

**有効な値**
  + `RUNTIME_ERROR`— ランタイム例外をスローします。
  + `LOG_ERROR` – エラーをログ記録して続行します (デフォルト)。
  + `IGNORE_ERROR` – エラーを無視して続行します。

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