「翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。」
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 グループを追加します。
プラグインを使用するには、withPlugin で AWSXRayRecorderBuilder を呼び出します。
例 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>ローカルルールのみを使用するには、CentralizedSamplingStrategy を LocalizedSamplingStrategy に置き換えます。
builder.withSamplingStrategy(newLocalizedSamplingStrategy(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 がキー AWS-XRAY-TRACE-ID と共に MDC に挿入されます。そのセグメントが終了すると、キーは MDC から削除されます。これにより、トレース ID が使用中のログ記録ライブラリに公開されます。サブセグメントが終了すると、その親
ID が MDC に挿入されます。
例 完全修飾トレース ID
完全修飾 ID は TraceID@EntityID として表されます
1-5df42873-011e96598b447dfca814c156@541b3365be3dafc3この機能は、AWS X-Ray SDK for Java によって計測された Java アプリケーションで動作し、以下のログ設定をサポートしています。
-
Logback バックエンドを使用する SLF4J フロントエンド API
-
Log4J2 バックエンドを使用する SLF4J フロントエンド API
-
Log4J2 バックエンドを使用する Log4J2 フロントエンド API
各フロントエンドと各バックエンドのニーズについては、以下のタブを参照してください。
トレース ID の挿入の例
以下に示しているのは、トレース ID を含むように変更された PatternLayout 文字列です。トレース ID は、スレッド名 (%t) の後、ログレベル (%-5p) の前に出力されます。
例 PatternLayoutID を挿入した
%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
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:portudp:address:port
-
-
AWS_XRAY_CONTEXT_MISSING– 実装されたコードが、セグメントが開いていないときにデータを記録しようとした場合に例外のスローを回避するには、LOG_ERRORに設定します。有効な値
-
RUNTIME_ERROR– ランタイム例外をスローします（デフォルト）。 -
LOG_ERROR– エラーを記録して続行します。
オープン状態のリクエストがない場合、または新しいスレッドを発生させるコードで実行されるスタートアップコードで実装されたクライアントを使用しようとした場合に発生する可能性がある、セグメントまたはサブセグメントの欠落に関連するエラー。
-
環境変数は、同等の「システムプロパティ」と、コードで設定される値を上書きします。
システムプロパティ
システムプロパティは、「環境変数」に代わる JVM 固有の代替的な方法として使用できます。SDK では、以下のプロパティをサポートしています。
-
com.amazonaws.xray.strategy.tracingName– に相当しますAWS_XRAY_TRACING_NAME。 -
com.amazonaws.xray.emitters.daemonAddress– に相当しますAWS_XRAY_DAEMON_ADDRESS。 -
com.amazonaws.xray.strategy.contextMissingStrategy– に相当しますAWS_XRAY_CONTEXT_MISSING。
環境変数と同等の環境変数のいずれも設定されている場合は、環境変数の値が使用されます。どちらのメソッドでも、コードで設定される値は上書きされます。
