使用SDK适用于 Java 的 X-Ray 向区段添加注释和元数据

可以利用注释和元数据记录与请求、环境或应用程序相关的其他信息。您可以向 X-Ray 创建的区段或您SDK创建的自定义子分段添加注释和元数据。

注释是带字符串、数字或布尔值的键值对。系统会对注释编制索引，以便与筛选表达式一起使用。使用注解来记录要用于在控制台中或在调用时对跟踪进行分组的数据GetTraceSummariesAPI。

元数据是可以具有任何类型值的键-值对，包括对象和列表，但没有编制索引，无法与筛选条件表达式一起使用。使用元数据记录要存储在跟踪中但不需要用于搜索跟踪的其他数据。

除了注释和元数据之外，您还可以在分段上记录用户 ID 字符串。用户IDs被记录在区段的单独字段中，并编制索引以供搜索使用。

使用SDK适用于 Java 的 X-Ray 录制注释

使用注释记录有关要为其编制索引以进行搜索的分段和子分段的信息。

注释要求

• 密钥-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");

它们将注释作为键值对SDK记录在区段文档的annotations对象中。使用相同键调用两次 putAnnotation 将覆盖同一分段或子分段上之前记录的值。

要查找具有带特定值的注释的跟踪，请在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();
    }
  }

使用SDK适用于 Java 的 X-Ray 录制元数据

使用元数据记录有关您无需为其编制索引以进行搜索的分段或子分段的信息。元数据值可以是字符串、数字、布尔值或任何可以序列化为对象或数组的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 将覆盖同一分段或子分段上之前记录的值。

例 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();
    }
  }

使用SDK适用于 Java IDs 的 X-Ray 录制用户

记录请求细分中的用户，以识别发送请求的用户。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，可以在单个行中链接这些调用。

例 src/main/java/scorekeeep/ .java — 用户 ID MoveController

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筛选表达式中使用 关键字。