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

# X-Ray SDK for Node.js の設定
<a name="xray-sdk-nodejs-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 Node.js にプラグインを設定して、アプリケーションが実行されているサービスに関する情報が含めたり、デフォルトのサンプリング動作を変更したり、特定のパスに対するリクエストに適用されるサンプリングルールを追加したりできます。

**Topics**
+ [サービスプラグイン](#xray-sdk-nodejs-configuration-plugins)
+ [サンプリングルール](#xray-sdk-nodejs-configuration-sampling)
+ [ログ記録](#xray-sdk-nodejs-configuration-logging)
+ [X-Ray デーモンのアドレス](#xray-sdk-nodejs-configuration-daemon)
+ [環境変数](#xray-sdk-nodejs-configuration-envvars)

## サービスプラグイン
<a name="xray-sdk-nodejs-configuration-plugins"></a>

`plugins`を使用して、アプリケーションをホストしているサービスに関する情報を記録します。

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

プラグインを使用するには、`config` メソッドを使用して X-Ray SDK for Node.js クライアントを設定します。

**Example app.js - プラグイン**  

```
var AWSXRay = require('aws-xray-sdk');
AWSXRay.config([AWSXRay.plugins.EC2Plugin,AWSXRay.plugins.ElasticBeanstalkPlugin]);
```

SDK はプラグイン設定を使用して、セグメントの`origin`フィールドを設定します。これは、アプリケーションを実行する AWS リソースのタイプを示します。複数のプラグインを使用する場合、SDK は次の解決順序を使用して起点を決定します。ElasticBeanStalk > EKS > ECS > EC2。

## サンプリングルール
<a name="xray-sdk-nodejs-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 はサンプリングを決定します。

バックアップルールを設定するには、`setSamplingRules`の ファイルからサンプリングルールをロードするようX-Ray SDK for Node.js に指示します。

**Example app.js - ファイルのサンプリングルール**  

```
var AWSXRay = require('aws-xray-sdk');
AWSXRay.middleware.setSamplingRules('sampling-rules.json');
```

コードのルールを定義し、オブジェクトとして `setSamplingRules` に渡すこともできます。

**Example app.js - オブジェクトのサンプリングルール**  

```
var AWSXRay = require('aws-xray-sdk');
var rules = {
  "rules": [ { "description": "Player moves.", "service_name": "*", "http_method": "*", "url_path": "/api/move/*", "fixed_target": 0, "rate": 0.05 } ],
  "default": { "fixed_target": 1, "rate": 0.1 },
  "version": 1
  }

AWSXRay.middleware.setSamplingRules(rules);
```

ローカルルールのみを使用するには、`disableCentralizedSampling` を呼び出します。

```
AWSXRay.middleware.disableCentralizedSampling()
```

## ログ記録
<a name="xray-sdk-nodejs-configuration-logging"></a>

 SDK からログ出力するには、`AWSXRay.setLogger(logger)` を呼び出します。`logger` は、標準のログ記録メソッド (`warn`、`info`、など) を提供するオブジェクトです。

デフォルトでは、SDK はコンソールオブジェクトの標準メソッドを使用してコンソールにエラーメッセージを記録します。組み込みロガーのログレベルは、`AWS_XRAY_DEBUG_MODE`または`AWS_XRAY_LOG_LEVEL`環境変数を使って設定できます。有効なログレベル値の一覧については、「[環境変数](#xray-sdk-nodejs-configuration-envvars)」を参照してください。

ログに別の形式または宛先を指定したい場合は、次に示すように、SDK に独自のロガーインターフェイスの実装を提供できます。このインタフェースを実装するあらゆるオブジェクトを使用できます。つまり、Winston など、多くのロギングライブラリを使用して SDK に直接渡すことができるということです。

**Example app.js - ログ記録**  

```
var AWSXRay = require('aws-xray-sdk');

// Create your own logger, or instantiate one using a library.
var logger = {
  error: (message, meta) => { /* logging code */ },
  warn: (message, meta) => { /* logging code */ },
  info: (message, meta) => { /* logging code */ },
  debug: (message, meta) => { /* logging code */ }
}

AWSXRay.setLogger(logger);
AWSXRay.config([AWSXRay.plugins.EC2Plugin]);
```

他の設定方法を実行する前に、`setLogger` を呼び出して、これらの操作から出力をキャプチャすることを確認します。

## X-Ray デーモンのアドレス
<a name="xray-sdk-nodejs-configuration-daemon"></a>

X-Ray デーモンが、`127.0.0.1:2000` 以外のポートまたはホスト上でリッスンする場合は、X-Ray SDK for Node.js を使用して、トレースデータを別のアドレスに送信することができます。

```
AWSXRay.setDaemonAddress('host:port');
```

ホストは、名前または IPv4 アドレス で指定できます。

**Example app.js - デーモンのアドレス**  

```
var AWSXRay = require('aws-xray-sdk');
AWSXRay.setDaemonAddress('daemonhost:8082');
```

TCP および UDP の別のポートでリッスンするようデーモンを設定する場合、両方ともデーモンアドレスの設定で指定できます。

**Example app.js - 別々のポートのデーモンのアドレス**  

```
var AWSXRay = require('aws-xray-sdk');
AWSXRay.setDaemonAddress('tcp:daemonhost:8082 udp:daemonhost:8083');
```

または、`AWS_XRAY_DAEMON_ADDRESS` [環境変数](#xray-sdk-nodejs-configuration-envvars)を使用して、デーモンアドレスを設定することもできます。

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

環境変数を使用して、X-Ray SDK for Node.js を設定できます。SDK は次の変数をサポートしています。
+ `AWS_XRAY_CONTEXT_MISSING` – 計測されたコードが、セグメントが開いていないときにデータを記録しようとした場合に例外をスローするには、`RUNTIME_ERROR` に設定します。

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

  オープン状態のリクエストがない場合、または新しいスレッドを発生させるコードで、スタートアップコードに実装されたクライアントを使用しようとした場合に発生する可能性がある、セグメントまたはサブセグメントの欠落に関連するエラー。
+ `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_DEBUG_MODE`— `debug`レベルでコンソールにログを出力するように SDK を設定するには、`TRUE`に設定します。
+ `AWS_XRAY_LOG_LEVEL ` – デフォルトロガーのログレベルを設定します。有効な値は、`debug`、`info`、`warn`、`error`、`silent` です。この値は、AWS\$1XRAY\$1DEBUG\$1MODE が `TRUE` に設定されている場合、無視されます。
+ `AWS_XRAY_TRACING_NAME` – SDK がセグメントに使用するサービス名を設定します。[Express ミドルウェアを設定した](xray-sdk-nodejs-middleware.md)セグメント名を上書きします。