X-Ray SDK for Java の設定

X-Ray SDK for Java には、 グローバルレコーダーAWSXRayを提供する という名前のクラスが含まれています。これは、コードの計測に使用できる TracingHandler です。グローバルレコーダーを設定して、着信HTTPのセグメントAWSXRayServletFilterを作成する をカスタマイズできます。

サービスプラグイン

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

プラグインを使用するには、AWSXRayRecorderBuilder で withPlugin を呼び出します。

import com.amazonaws.xray.AWSXRay;
import com.amazonaws.xray.AWSXRayRecorderBuilder;
import com.amazonaws.xray.plugins.EC2Plugin;
import com.amazonaws.xray.plugins.ElasticBeanstalkPlugin;
import com.amazonaws.xray.strategy.sampling.LocalizedSamplingStrategy;

@Configuration
public class WebConfig {
...
  static {
    AWSXRayRecorderBuilder builder = AWSXRayRecorderBuilder.standard().withPlugin(new EC2Plugin()).withPlugin(new ElasticBeanstalkPlugin());

    URL ruleFile = WebConfig.class.getResource("/sampling-rules.json");
    builder.withSamplingStrategy(new LocalizedSamplingStrategy(ruleFile));

    AWSXRay.setGlobalRecorder(builder.build());
  }
}

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

サンプリングルール

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

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

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

{
  "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 はサンプリングを決定します。

Spring でバックアップルールを提供するには、設定クラスの CentralizedSamplingStrategy にグローバルレコーダーを設定します。

import com.amazonaws.xray.AWSXRay;
import com.amazonaws.xray.AWSXRayRecorderBuilder;
import com.amazonaws.xray.javax.servlet.AWSXRayServletFilter;
import com.amazonaws.xray.plugins.EC2Plugin;
import com.amazonaws.xray.strategy.sampling.LocalizedSamplingStrategy;

@Configuration
public class WebConfig {

  static {
  AWSXRayRecorderBuilder builder = AWSXRayRecorderBuilder.standard().withPlugin(new EC2Plugin());

  URL ruleFile = WebConfig.class.getResource("/sampling-rules.json");
  builder.withSamplingStrategy(new CentralizedSamplingStrategy(ruleFile));

  AWSXRay.setGlobalRecorder(builder.build());
}

Tomcat の場合、ServletContextListener を拡張するリスナーを追加し、デプロイ記述子にリスナーを登録します。

import com.amazonaws.xray.AWSXRay;
import com.amazonaws.xray.AWSXRayRecorderBuilder;
import com.amazonaws.xray.plugins.EC2Plugin;
import com.amazonaws.xray.strategy.sampling.LocalizedSamplingStrategy;

import java.net.URL;
import javax.servlet.ServletContextEvent;
import javax.servlet.ServletContextListener;

public class Startup implements ServletContextListener {

    @Override
    public void contextInitialized(ServletContextEvent event) {
        AWSXRayRecorderBuilder builder = AWSXRayRecorderBuilder.standard().withPlugin(new EC2Plugin());

        URL ruleFile = Startup.class.getResource("/sampling-rules.json");
        builder.withSamplingStrategy(new CentralizedSamplingStrategy(ruleFile));

        AWSXRay.setGlobalRecorder(builder.build());
    }

    @Override
    public void contextDestroyed(ServletContextEvent event) { }
}

...
  <listener>
    <listener-class>com.myapp.web.Startup</listener-class>
  </listener>

ローカルルールのみを使用するには、CentralizedSamplingStrategy を LocalizedSamplingStrategy に置き換えます。

builder.withSamplingStrategy(new LocalizedSamplingStrategy(ruleFile));

ログ記録

デフォルトでは、 は ERRORレベルのメッセージをアプリケーションログにSDK出力します。でデバッグレベルのログ記録を有効にしてSDK、より詳細なログをアプリケーションログファイルに出力できます。有効なログレベルは DEBUG、INFO、、WARN、および ですFATAL。 FATALは致命的なレベルでログを記録しないためERROR、ログレベルSDKはすべてのログメッセージを無音にします。

logging.level.com.amazonaws.xray = DEBUG

デバッグログを使用して問題を識別します。たとえば、「サブセグメントを手動で生成する」場合にサブセグメントが閉じない問題などです。

ログへのトレース ID の挿入

現在の完全修飾トレース ID をログステートメントに公開するには、マッピングされた診断コンテキスト () に ID を挿入しますMDC。SegmentListener インターフェイスを使用して、セグメントライフサイクルイベント中に X-Ray レコーダーからメソッドが呼び出されます。セグメントまたはサブセグメントが開始されると、修飾トレース ID はキー MDCを使用して に挿入されますAWS-XRAY-TRACE-ID。そのセグメントが終了すると、キーは から削除されますMDC。これにより、トレース ID が使用中のログ記録ライブラリに公開されます。サブセグメントが終了すると、その親 ID が に挿入されますMDC。

1-5df42873-011e96598b447dfca814c156@541b3365be3dafc3

この機能は、 AWS X-Ray SDK for Java で計測された Java アプリケーションで動作し、次のログ記録設定をサポートします。

各フロントエンドと各バックエンドのニーズについては、以下のタブを参照してください。

トレース ID の挿入の例

以下に示しているのは、トレース ID を含むように変更された PatternLayout 文字列です。トレース ID は、スレッド名 (%t) の後、ログレベル (%-5p) の前に出力されます。

%d{HH:mm:ss.SSS} [%t] %X{AWS-XRAY-TRACE-ID} %-5p %m%n

AWS X-Ray は、簡単に解析できるように、ログステートメントにキーとトレース ID を自動的に出力します。以下に示しているのは、変更した PatternLayout を使用したログステートメントです。

2019-09-10 18:58:30.844 [nio-5000-exec-4]  AWS-XRAY-TRACE-ID: 1-5d77f256-19f12e4eaa02e3f76c78f46a@1ce7df03252d99e1 WARN 1 - Your logging message here

ログメッセージ自体はパターン %m に格納され、ロガーを呼び出すときに設定されます。

セグメントリスナー

セグメントリスナーは、 によって生成されるセグメントの開始や終了などのライフサイクルイベントをインターセプトするためのインターフェイスですAWSXRayRecorder。セグメントリスナーイベント関数の実装には、 で作成されたときにすべてのサブセグメントに同じアノテーションを追加したりonBeginSubsegment、 を使用して各セグメントがデーモンに送信された後にメッセージをログに記録したりafterEndSegment、 を使用してSQLインターセプターから送信されたクエリを記録beforeEndSubsegmentしてサブセグメントがSQLクエリを表しているかどうかを確認し、その場合はメタデータを追加したりすることが考えられます。

SegmentListener 関数の完全なリストを確認するには、AWS X-Ray Java SDK用 Recorder APIのドキュメントを参照してください。

次の例は、onBeginSubsegment での作成時にすべてのサブセグメントに一貫性のある注釈を追加し、afterEndSegment を使用して各セグメントの最後にログメッセージを出力する方法を示しています。

import com.amazonaws.xray.entities.Segment;
import com.amazonaws.xray.entities.Subsegment;
import com.amazonaws.xray.listeners.SegmentListener;

public class MySegmentListener implements SegmentListener {
    .....
    
    @Override
    public void onBeginSubsegment(Subsegment subsegment) {
        subsegment.putAnnotation("annotationKey", "annotationValue");
    }
    
    @Override
    public void afterEndSegment(Segment segment) {
        // Be mindful not to mutate the segment
        logger.info("Segment with ID " + segment.getId());
    }
}

このカスタムセグメントリスナーは、AWSXRayRecorder を構築するときに参照されます。

AWSXRayRecorderBuilder builder = AWSXRayRecorderBuilder
        .standard().withSegmentListener(new MySegmentListener());

環境変数

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

環境変数は、同等の「システムプロパティ」と、コードで設定される値を上書きします。

システムプロパティ

システムプロパティは、環境変数 の JVM固有の代替として使用できます。は、次のプロパティSDKをサポートしています。

環境変数と同等の環境変数のいずれも設定されている場合は、環境変数の値が使用されます。どちらのメソッドでも、コードで設定される値は上書きされます。