使用适用于 Java 的 X-Ray 开发工具包将注释和元数据添加到分段 - Amazon X-Ray
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅中国的 Amazon Web Services 服务入门

本文属于机器翻译版本。若本译文内容与英语原文存在差异,则一律以英文原文为准。

使用适用于 Java 的 X-Ray 开发工具包将注释和元数据添加到分段

您可以使用注释和元数据记录有关请求、环境或应用程序的其他信息。您可以将注释和元数据添加到 X-Ray 开发工具包创建的分段或您创建的自定义子分段。

注释是带字符串、数字或布尔值的键-值对。注释编制索引,以便与筛选表达式。使用注释记录要用于对控制台中的跟踪进行分组的数据或在调用 GetTraceSummaries API 时使用的数据。

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

除了注释和元数据之外,您还可以记录用户 ID 字符串分段上。用户 ID 记录在分段的单独字段中,并且不会为其编制索引以用于搜索。

使用适用于 Java 的 X-Ray 开发工具包记录注释

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

注释要求

  • — 最多 500 个字母数字字符。无空格或符号,下划线除外。

  • — 最多 1000 个 Unicode 字符。

  • Entries— 每个跟踪最多 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");

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

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

使用适用于 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");

如果您没有指定命名空间,则开发工具包将使用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(); } }

使用适用于 Java 的 X-Ray 开发工具包记录用户 ID

记录请求分段上的用户 ID 以标识发送请求的用户。

记录用户 ID

  1. AWSXRay 获取对当前分段的引用。

    import com.amazonaws.xray.AWSXRay; import com.amazonaws.xray.entities.Segment; ... Segment document = AWSXRay.getCurrentSegment();
  2. CallsetUser使用发送请求的用户的字符串 ID。

    document.setUser("U12345");

您可以在控制器中调用 setUser 以便在应用程序开始处理请求后立即记录用户 ID。如果您只打算使用分段来设置用户 ID,可以在单个行中链接这些调用。

src/main/java/scorekeep/MoveController.java— User 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筛选表达式中使用 关键字。