X-Ray SDK for Java を使用してセグメントに注釈とメタデータを追加する

リクエスト、環境、または注釈やメタデータを使用するアプリケーションに関する追加情報を記録できます。X-Ray がSDK作成するセグメント、または作成するカスタムサブセグメントに注釈とメタデータを追加できます。

注釈は文字列、数値、またはブール値を使用したキーと値のペアです。注釈は、フィルタ式用にインデックス付けされます。注釈を使用して、コンソールでトレースをグループ化するために使用するデータ、または GetTraceSummaries を呼び出すときに記録しますAPI。

メタデータは、オブジェクトとリストを含む、任意のタイプの値を持つことができるキーバリューのペアですが、フィルタ式に使用するためにインデックスは作成されません。メタデータを使用してトレースに保存する追加のデータを記録しますが、検索で使用する必要はありません。

注釈とメタデータに加えて、セグメントにユーザー ID 文字列を記録することもできます。ユーザーはセグメントの別のフィールドにIDs記録され、検索で使用するインデックスが付けられます。

X-Ray SDK for Java を使用した注釈の記録

注釈を使用して、検索用にインデックスを作成するセグメントまたはサブセグメントに情報を記録します。

注釈の要件

• キー – X-Ray 注釈のキーには、最大 500 文字の英数字を使用できます。ドットまたはピリオド ( ) 以外のスペースまたは記号は使用できません。 ）

• 値 – X-Ray 注釈の値は、最大 1,000 文字の Unicode 文字を持つことができます。

• 注釈の数 — トレースごとに最大 50 個の注釈を使用できます。

注釈を記録するには

1. AWSXRay から現在のセグメントまたはサブセグメントの参照を取得します。

   import com.amazonaws.xray.AWSXRay;
   import com.amazonaws.xray.entities.Segment;
   ...
   Segment document = AWSXRay.getCurrentSegment();

   または

   import com.amazonaws.xray.AWSXRay;
   import com.amazonaws.xray.entities.Subsegment;
   ...
   Subsegment document = AWSXRay.getCurrentSubsegment();

2. 文字列キー、および、ブール値、数値、文字列値を使用して putAnnotation を呼び出します。

   document.putAnnotation("mykey", "my value");

   次の例は、ドット、ブール値、数値、または文字列値を含む文字列キーputAnnotationを使用して を呼び出す方法を示しています。

   document.putAnnotation("testkey.test", "my value");

は、セグメントドキュメント内のannotationsオブジェクトのキーと値のペアとして注釈SDKを記録します。同じキーで putAnnotation を 2 回呼び出すと、同じセグメントまたはサブセグメントに以前記録された値が上書きされます。

特定の値を持つ注釈のあるトレースを見つけるには、annotation[key]フィルタ式の キーワードを使用します。

例 src/main/java/scorekeep/GameModel.java – 注釈とメタデータ

import com.amazonaws.xray.AWSXRay;
import com.amazonaws.xray.entities.Segment;
import com.amazonaws.xray.entities.Subsegment;
...
  public void saveGame(Game game) throws SessionNotFoundException {
    // wrap in subsegment
    Subsegment subsegment = AWSXRay.beginSubsegment("## GameModel.saveGame");
    try {
      // check session
      String sessionId = game.getSession();
      if (sessionModel.loadSession(sessionId) == null ) {
        throw new SessionNotFoundException(sessionId);
      }
      Segment segment = AWSXRay.getCurrentSegment();
      subsegment.putMetadata("resources", "game", game);
      segment.putAnnotation("gameid", game.getId());
      mapper.save(game);
    } catch (Exception e) {
      subsegment.addException(e);
      throw e;
    } finally {
      AWSXRay.endSubsegment();
    }
  }

X-Ray SDK for Java を使用したメタデータの記録

メタデータを使用して、検索用にインデックスを作成する必要のないセグメントまたはサブセグメントに情報を記録します。メタデータ値は、文字列、数値、ブール値、またはオブジェクトまたは配列にシリアル化できる任意のJSONオブジェクトです。

メタデータを記録するには

1. AWSXRay から現在のセグメントまたはサブセグメントの参照を取得します。

   import com.amazonaws.xray.AWSXRay;
   import com.amazonaws.xray.entities.Segment;
   ...
   Segment document = AWSXRay.getCurrentSegment();

   または

   import com.amazonaws.xray.AWSXRay;
   import com.amazonaws.xray.entities.Subsegment;
   ...
   Subsegment document = AWSXRay.getCurrentSubsegment();

2. 文字列名前空間、文字列キー、ブール値、数値、文字列値、オブジェクト値を使用して putMetadata を呼び出します。

   document.putMetadata("my namespace", "my key", "my value");

   または

   キーと値だけを使用して putMetadata を呼び出します。

   document.putMetadata("my key", "my value");

名前空間を指定しない場合、 は SDKを使用しますdefault。同じキーで putMetadata を 2 回呼び出すと、同じセグメントまたはサブセグメントに以前記録された値が上書きされます。

例 src/main/java/scorekeep/GameModel.java – 注釈とメタデータ

import com.amazonaws.xray.AWSXRay;
import com.amazonaws.xray.entities.Segment;
import com.amazonaws.xray.entities.Subsegment;
...
  public void saveGame(Game game) throws SessionNotFoundException {
    // wrap in subsegment
    Subsegment subsegment = AWSXRay.beginSubsegment("## GameModel.saveGame");
    try {
      // check session
      String sessionId = game.getSession();
      if (sessionModel.loadSession(sessionId) == null ) {
        throw new SessionNotFoundException(sessionId);
      }
      Segment segment = AWSXRay.getCurrentSegment();
      subsegment.putMetadata("resources", "game", game);
      segment.putAnnotation("gameid", game.getId());
      mapper.save(game);
    } catch (Exception e) {
      subsegment.addException(e);
      throw e;
    } finally {
      AWSXRay.endSubsegment();
    }
  }

X-Ray SDK for Java IDsを使用したユーザーの記録

リクエストセグメントIDsにユーザーを記録して、リクエストを送信したユーザーを特定します。

ユーザーを記録するには IDs

1. AWSXRay から現在のセグメントへの参照を取得します。

   import com.amazonaws.xray.AWSXRay;
   import com.amazonaws.xray.entities.Segment;
   ...
   Segment document = AWSXRay.getCurrentSegment();

2. リクエストを送信したユーザーの文字列 ID を使用して setUser を呼び出します。

   document.setUser("U12345");

コントローラーで setUser を呼び出し、アプリケーションがリクエストの処理を開始するとすぐに、ユーザー ID を記録できます。ユーザー ID を設定するためだけにセグメントを使用する場合、呼び出しを 1 行で連鎖させることができます。

例 src/main/java/scorekeep/MoveController.java – ユーザー ID

import com.amazonaws.xray.AWSXRay;
...
  @RequestMapping(value="/{userId}", method=RequestMethod.POST)
  public Move newMove(@PathVariable String sessionId, @PathVariable String gameId, @PathVariable String userId, @RequestBody String move) throws SessionNotFoundException, GameNotFoundException, StateNotFoundException, RulesException {
    AWSXRay.getCurrentSegment().setUser(userId);
    return moveFactory.newMove(sessionId, gameId, userId, move);
  }

ユーザー ID のトレースを見つけるには、userフィルタ式で、 キーワードを使用します。