X-Ray SDK for Java を使用したカスタムサブセグメントの生成

サブセグメントは、トレースの セグメント をリクエストを処理するために行われた作業の詳細で拡張します。計測済みクライアント内で呼び出しを行うたびに、X-Ray SDK によってサブセグメントに生成された情報が記録されます。追加のサブセグメントを作成して、他のサブセグメントをグループ化したり、コードセクションのパフォーマンスを測定したり、注釈とメタデータを記録したりできます。

サブセグメントを管理するには、beginSubsegment および endSubsegment メソッドを使用します。

例 GameModel.java - カスタムサブセグメント

import com.amazonaws.xray.AWSXRay;
...
  public void saveGame(Game game) throws SessionNotFoundException {
    // wrap in subsegment
    Subsegment subsegment = AWSXRay.beginSubsegment("Save Game");
    try {
      // check session
      String sessionId = game.getSession();
      if (sessionModel.loadSession(sessionId) == null ) {
        throw new SessionNotFoundException(sessionId);
      }
      mapper.save(game);
    } catch (Exception e) {
      subsegment.addException(e);
      throw e;
    } finally {
      AWSXRay.endSubsegment();
    }
  }

この例では、サブセグメント内のコードが、セッションモデルのメソッドを使用して DynamoDB からゲームのセッションをロードし、AWS SDK for Java の DynamoDB マッパーを使用してゲームを保存します。このコードをサブセグメントにラップすることで、呼び出しが Save Game サブセグメントの DynamoDB の子としてコンソールのトレースビューに表示されます。

サブセグメントのコードがチェック例外をスローした場合は、try ブロックにコードをラップして、finally ブロックで AWSXRay.endSubsegment() を呼び出し、常にサブセグメントが閉じられるようにします。サブセグメントが閉じていない場合は、親セグメントが完了できず、X-Ray に送信されません。

チェック例外をスローしないコードの場合は、コードを Lambda 関数として AWSXRay.CreateSubsegment に渡すことができます。

例 Lambda 関数のサブセグメント

import com.amazonaws.xray.AWSXRay;

AWSXRay.createSubsegment("getMovies", (subsegment) -> {
    // function code
});

セグメントまたは別のサブセグメント内にサブセグメントを作成する場合、X-Ray SDK for Java によってその ID が生成され、開始時刻と終了時刻が記録されます。

例 サブセグメントとメタデータ

"subsegments": [{
  "id": "6f1605cd8a07cb70",
  "start_time": 1.480305974194E9,
  "end_time": 1.4803059742E9,
  "name": "Custom subsegment for UserModel.saveUser function",
  "metadata": {
    "debug": {
      "test": "Metadata string from UserModel.saveUser"
    }
  },

非同期やマルチスレッドのプログラミングでは、非同期実行中に X-Ray コンテキストが変更されることがあるため、サブセグメントを endSubsegment() メソッドに手動で渡して正しく閉じるようにする必要があります。親セグメントが閉じられた後に非同期サブセグメントが閉じられた場合、このメソッドはセグメント全体を X-Ray デーモンに自動的にストリームします。

例 非同期サブセグメント

@GetMapping("/api")
public ResponseEntity<?> api() {
  CompletableFuture.runAsync(() -> {
      Subsegment subsegment = AWSXRay.beginSubsegment("Async Work");
      try {
          Thread.sleep(3000);
      } catch (InterruptedException e) {
          subsegment.addException(e);
          throw e;
      } finally {
          AWSXRay.endSubsegment(subsegment);
      }
  });
  return ResponseEntity.ok().build();
}