X-Ray SDK for Java の設定 - AWS X-Ray

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

X-Ray SDK for Java の設定

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

サービスプラグイン

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

Plugins

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

  • Elastic Beanstalk – ElasticBeanstalkPlugin は、環境名、バージョンラベル、およびデプロイ ID を追加します。

  • Amazon ECS – ECSPlugin は、コンテナ ID を追加します。

  • Amazon EKS – EKSPlugin は、コンテナ ID、クラスター名、ポッド ID、および CloudWatch Logs グループを追加します。


        リソースデータを Amazon EC2 および Elastic Beanstalk プラグイン。

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

例 src/main/java/scorekeep/WebConfig.java - レコーダー

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 リソースのタイプを示します。リソースタイプは、サービスマップでアプリケーション名の下に表示されます。たとえば、AWS::ElasticBeanstalk::Environment と指定します。

サービスノードとリソースタイプ。

複数のプラグインを使用する場合、SDK では次の解決の順序に従い、オリジンを特定します。ElasticBeanstalk > EKS > ECS > EC2。

サンプリングルール

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

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

注記

SDK は、X-Ray からサンプリングルールを取得できない場合、デフォルトのローカルルール (1 秒ごとに最初のリクエストと、追加リクエストの 5%) をホストごとに適用します。これが発生するのは、サンプリング API を呼び出す権限がホストにない場合、またはホストが X-Ray デーモンに接続できない場合です。このデーモンは、SDK が行う API コールに対して TCP プロキシとして機能します。

サンプリングルールを 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 はサンプリングの決定を行います。

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

例 src/main/java/myapp/WebConfig.java – レコーダーの設定

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 を拡張するリスナーを追加し、デプロイ記述子にリスナーを登録します。

例 src/com/myapp/web/Startup.java

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) { } }

例 WEB-INF/web.xml

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

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

builder.withSamplingStrategy(new LocalizedSamplingStrategy(ruleFile));

Logging

デフォルトでは、SDK は SEVERE レベルと ERROR レベルのメッセージをアプリケーションログに出力します。SDK でデバッグレベルのロギングを有効にすると、より詳細なログがアプリケーションログファイルに出力されます。

例 application.properties

logging.level.com.amazonaws.xray プロパティを使用してログレベルを設定します。

logging.level.com.amazonaws.xray = DEBUG

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

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

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

例 完全修飾トレース ID

完全修飾 ID は TraceID@EntityID として表されます

1-5df42873-011e96598b447dfca814c156@541b3365be3dafc3

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

  • Logback バックエンドを使用する SLF4J フロントエンド API

  • SLF4J フロントエンド API Log4J2 バックエンド

  • Log4J2 フロントエンドAPIと Log4J2 バックエンド

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

SLF4J Frontend
  1. 以下の Maven 依存関係をプロジェクトに追加します。

    <dependency> <groupId>com.amazonaws</groupId> <artifactId>aws-xray-recorder-sdk-slf4j</artifactId> <version>2.4.0</version> </dependency>
  2. [ withSegmentListener メソッドは、 AWSXRayRecorder. これにより、 SegmentListener 新しいトレースを自動的に注入するクラス IDs SLF4J MDCへ

    SegmentListener は、ログステートメントのプレフィクスを設定するためのパラメータとしてオプションの文字列を取ります。プレフィクスは、次の方法で設定できます。

    • なし – デフォルトの AWS-XRAY-TRACE-ID プレフィックスを使用します。

    • – 空の文字列を使用します (例: "")。

    • カスタム – 文字列で定義されているカスタムプレフィックスを使用します。

    AWSXRayRecorderBuilder statement

    AWSXRayRecorderBuilder builder = AWSXRayRecorderBuilder .standard().withSegmentListener(new SLF4JSegmentListener("CUSTOM-PREFIX"));
Log4J2 front end
  1. 以下の Maven 依存関係をプロジェクトに追加します。

    <dependency> <groupId>com.amazonaws</groupId> <artifactId>aws-xray-recorder-sdk-log4j</artifactId> <version>2.4.0</version> </dependency>
  2. [ withSegmentListener メソッドは、 AWSXRayRecorder. これにより、 SegmentListener 自動的に新しい完全修飾トレースを注入するクラス IDs SLF4J MDCへ

    SegmentListener は、ログステートメントのプレフィクスを設定するためのパラメータとしてオプションの文字列を取ります。プレフィクスは、次の方法で設定できます。

    • なし – デフォルトの AWS-XRAY-TRACE-ID プレフィックスを使用します。

    • – 空の文字列 (例: "") を使用して、プレフィックスを削除します。

    • カスタム – 文字列で定義されているカスタムプレフィックスを使用します。

    AWSXRayRecorderBuilder statement

    AWSXRayRecorderBuilder builder = AWSXRayRecorderBuilder .standard().withSegmentListener(new Log4JSegmentListener("CUSTOM-PREFIX"));
Logback backend

トレース ID をログイベントに挿入するには、各ログ記録ステートメントを書式設定するロガーの PatternLayout を変更する必要があります。

  1. patternLayout が設定されている場所を見つけます。これは、プログラムで行うことも、XML 設定ファイルを使用して行うこともできます。詳細については、「Logback の設定」を参照してください。

  2. 挿入 %X{AWS-XRAY-TRACE-ID} 場所を patternLayout トレース ID を将来のログ記録ステートメントに挿入します。%X{} は、MDC から提供されたキーで値を取得していることを示します。についてもっと知るには PatternLayouts [Logback]で、次を参照してください。 PatternLayout.

Log4J2 backend
  1. patternLayout が設定されている場所を見つけます。これは、プログラムで行うことも、XML、JSON、YAML、またはプロパティ形式で記述された設定ファイルを使用して行うこともできます。

    構成の詳細について Log4J2 設定ファイルから、を参照してください。 構成.

    構成の詳細について Log4J2 プログラマティック、次を参照: プログラマティック設定.

  2. 挿入 %X{AWS-XRAY-TRACE-ID} 場所を PatternLayout トレース ID を将来のログ記録ステートメントに挿入します。%X{} は、MDC から提供されたキーで値を取得していることを示します。についてもっと知るには PatternLayouts () Log4J2、参照 パターンレイアウト.

トレース ID の挿入の例

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

例 ID を挿入した PatternLayout

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

AWS X-Ray によって、ログステートメントにキーとトレース ID が自動的に出力されて、解析が容易になります。以下に示しているのは、変更した PatternLayout を使用したログステートメントです。

例 ID を挿入したログステートメント

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 Recorder SDK for Java API のドキュメントを参照してください。

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

例 MySegmentListener.java(java)

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 statement

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

環境変数

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

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

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

    形式

    • 同じポートaddress:port

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

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

    有効な値

    • RUNTIME_ERROR – ランタイム例外をスローします(デフォルト)。

    • LOG_ERROR – エラーを記録して続行します。

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

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

システムプロパティ

システムプロパティは、「環境変数」に代わる JVM 固有の代替的な方法として使用できます。SDK では、以下のプロパティをサポートしています。

  • com.amazonaws.xray.strategy.tracingNameAWS_XRAY_TRACING_NAMEと同様です。

  • com.amazonaws.xray.emitters.daemonAddressAWS_XRAY_DAEMON_ADDRESSと同様です。

  • com.amazonaws.xray.strategy.contextMissingStrategyAWS_XRAY_CONTEXT_MISSINGと同様です。

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