本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 使用適用於 Java 的 X-Ray 開發套件將註釋和中繼資料新增至區段
<a name="xray-sdk-java-segment"></a>

**注意**  
X-Ray 開發套件/協助程式維護通知 – 在 2026 年 2 月 25 日， AWS X-Ray SDKs/協助程式將進入維護模式，其中 AWS 將限制 X-Ray 開發套件和協助程式版本，以僅解決安全問題。如需支援時間表的詳細資訊，請參閱 [X-Ray SDK 和協助程式支援時間表](xray-sdk-daemon-timeline.md)。建議您遷移至 OpenTelemetry。如需遷移至 OpenTelemetry 的詳細資訊，請參閱[從 X-Ray 檢測遷移至 OpenTelemetry 檢測](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html)。

您可以使用註釋和中繼資料記錄有關請求、環境或應用程式的其他資訊。您可以將註釋和中繼資料新增至 X-Ray 開發套件建立的區段，或新增至您建立的自訂子區段。

**註釋**是具有字串、數字或布林值的鍵值對。註釋會編製索引，以便與[篩選條件表達式](xray-console-filters.md)搭配使用。使用標記記錄您想要用來在主控台將追蹤分組的資料，或是在呼叫 [https://docs.aws.amazon.com/xray/latest/api/API_GetTraceSummaries.html](https://docs.aws.amazon.com/xray/latest/api/API_GetTraceSummaries.html) API 時使用標記。

**中繼資料**是索引鍵/值對，可以具有任何類型的值，包括物件和清單，但不會編製索引以與篩選條件表達式搭配使用。使用中繼資料記錄您希望儲存在追蹤中的其他資料，但不需要搭配搜尋使用。

除了註釋和中繼資料，您也可以在區段上[記錄使用者 ID 字串](#xray-sdk-java-segment-userid)。區段會將使用者 ID 記錄在單獨的欄位中，並建立索引以用於搜尋。

**Topics**
+ [使用適用於 Java 的 X-Ray 開發套件記錄註釋](#xray-sdk-java-segment-annotations)
+ [使用適用於 Java 的 X-Ray 開發套件記錄中繼資料](#xray-sdk-java-segment-metadata)
+ [使用適用於 Java IDs](#xray-sdk-java-segment-userid)

## 使用適用於 Java 的 X-Ray 開發套件記錄註釋
<a name="xray-sdk-java-segment-annotations"></a>

針對您想要建立索引以用於搜尋的區段或子區段，請使用標註來記錄這些區段上的資訊。

**註釋要求**
+ **金鑰** – X-Ray 註釋的金鑰最多可有 500 個英數字元。您不能使用點或句點以外的空格或符號 ( 。 )
+ **值** – X-Ray 註釋的值最多可有 1，000 個 Unicode 字元。
+ **註釋**數量 – 每個追蹤最多可以使用 50 個註釋。

**記錄標註**

1. 從 `AWSXRay` 取得目前區段或子區段的參考。

   ```
   import [com.amazonaws.xray.AWSXRay](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/AWSXRay.html);
   import [com.amazonaws.xray.entities.Segment](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/entities/Segment.html);
   ...
   Segment document = AWSXRay.getCurrentSegment();
   ```

   或

   ```
   import [com.amazonaws.xray.AWSXRay](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/AWSXRay.html);
   import [com.amazonaws.xray.entities.Subsegment](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/entities/Subsegment.html);
   ...
   Subsegment document = AWSXRay.getCurrentSubsegment();
   ```

1. 使用字串索引鍵、布林值、數字或字串值，呼叫 `putAnnotation`。

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

   下列範例顯示如何使用包含點的`putAnnotation`字串索引鍵和布林值、數字或字串值來呼叫 。

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

軟體開發套件會將標註以鍵/值對記錄在區段文件中的 `annotations` 物件內。若使用相同鍵呼叫 `putAnnotation` 兩次，則會覆寫之前在相同區段或子區段上記錄的值。

若要尋找具有特定值註釋的追蹤，請在[篩選條件表達](xray-console-filters.md)式中使用 `annotation[key]`關鍵字。

**Example [https://github.com/awslabs/eb-java-scorekeep/tree/xray/src/main/java/scorekeep/GameModel.java](https://github.com/awslabs/eb-java-scorekeep/tree/xray/src/main/java/scorekeep/GameModel.java) – 註釋和中繼資料**  

```
import [com.amazonaws.xray.AWSXRay](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/AWSXRay.html);
import [com.amazonaws.xray.entities.Segment](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/entities/Segment.html);
import [com.amazonaws.xray.entities.Subsegment](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/entities/Subsegment.html);
...
  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();
    }
  }
```

## 使用適用於 Java 的 X-Ray 開發套件記錄中繼資料
<a name="xray-sdk-java-segment-metadata"></a>

針對您不想要建立索引以用於搜尋的區段，請使用中繼資料來記錄這些區段或子區段上的資訊。中繼資料值可以是字串、數字、布林值，或可序列化為 JSON 物件或陣列的任何物件。

**記錄中繼資料**

1. 從 `AWSXRay` 取得目前區段或子區段的參考。

   ```
   import [com.amazonaws.xray.AWSXRay](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/AWSXRay.html);
   import [com.amazonaws.xray.entities.Segment](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/entities/Segment.html);
   ...
   Segment document = AWSXRay.getCurrentSegment();
   ```

   或

   ```
   import [com.amazonaws.xray.AWSXRay](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/AWSXRay.html);
   import [com.amazonaws.xray.entities.Subsegment](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/entities/Subsegment.html);
   ...
   Subsegment document = AWSXRay.getCurrentSubsegment();
   ```

1. 使用字串命名空間、字串索引鍵、布林值、數字、字串或物件值，呼叫 `putMetadata`。

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

   或

   只使用鍵和值呼叫 `putMetadata`。

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

若您沒有指定命名空間，軟體開發套件會使用 `default`。若使用相同鍵呼叫 `putMetadata` 兩次，則會覆寫之前在相同區段或子區段上記錄的值。

**Example [https://github.com/awslabs/eb-java-scorekeep/tree/xray/src/main/java/scorekeep/GameModel.java](https://github.com/awslabs/eb-java-scorekeep/tree/xray/src/main/java/scorekeep/GameModel.java) – 註釋和中繼資料**  

```
import [com.amazonaws.xray.AWSXRay](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/AWSXRay.html);
import [com.amazonaws.xray.entities.Segment](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/entities/Segment.html);
import [com.amazonaws.xray.entities.Subsegment](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/entities/Subsegment.html);
...
  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();
    }
  }
```

## 使用適用於 Java IDs
<a name="xray-sdk-java-segment-userid"></a>

記錄請求區段上的使用者 ID 以識別傳送請求的使用者。

**記錄使用者 ID**

1. 從 `AWSXRay` 取得目前區段的參考。

   ```
   import [com.amazonaws.xray.AWSXRay](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/AWSXRay.html);
   import [com.amazonaws.xray.entities.Segment](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/entities/Segment.html);
   ...
   Segment document = AWSXRay.getCurrentSegment();
   ```

1. 使用傳送請求之使用者的字串 ID 呼叫 `setUser`。

   ```
   document.setUser("U12345");
   ```

您可以在控制器中呼叫 `setUser`，以在應用程式開始處理請求時馬上記錄使用者 ID。如果您只要使用區段來設定使用者 ID，可以將呼叫鏈結為單行。

**Example [src/main/java/scorekeep/MoveController.java](https://github.com/awslabs/eb-java-scorekeep/tree/xray/src/main/java/scorekeep/MoveController.java) – 使用者 ID**  

```
import [com.amazonaws.xray.AWSXRay](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/AWSXRay.html);
...
  @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 的追蹤，請在[篩選條件表達](xray-console-filters.md)式中使用 `user`關鍵字。