As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.

# Adicionar anotações e metadados aos segmentos com o X-Ray SDK para Java
<a name="xray-sdk-java-segment"></a>

**nota**  
Aviso de SDK/Daemon manutenção do X-Ray — Em 25 de fevereiro de 2026, o AWS X-Ray SDKs/Daemon entrará no modo de manutenção, onde AWS limitará as versões do X-Ray SDK e do Daemon para tratar apenas de problemas de segurança. Para obter mais informações sobre a linha do tempo do suporte, consulte [Cronograma de suporte do X-Ray SDK e do Daemon Support](xray-sdk-daemon-timeline.md). Recomendamos migrar para o. OpenTelemetry Para obter mais informações sobre a migração para OpenTelemetry, consulte [Migrando da instrumentação X-Ray para a instrumentação](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html). OpenTelemetry 

Você pode registrar informações adicionais sobre solicitações, o ambiente ou o aplicativo com anotações e metadados. Também é possível adicionar anotações e metadados aos segmentos que o X-Ray SDK cria ou aos subsegmentos personalizados que você cria.

**Anotações** são pares de chave-valor com valores boolianos, de string ou número. As anotações são indexadas para serem usadas com [expressões de filtro](xray-console-filters.md). Use anotações para registrar dados que você deseja usar para agrupar rastreamentos no console ou ao chamar a API [https://docs.aws.amazon.com/xray/latest/api/API_GetTraceSummaries.html](https://docs.aws.amazon.com/xray/latest/api/API_GetTraceSummaries.html).

**Metadados** são pares chave-valor que podem ter valores de qualquer tipo, incluindo objetos e listas, mas não são indexados para uso com expressões de filtro. Use metadados para registrar dados adicionais que você deseja armazenar no rastreamento e não precisa usar com a pesquisa.

Além de anotações e metadados, você também pode [registrar strings de ID de usuário](#xray-sdk-java-segment-userid) em segmentos. IDs Os usuários são registrados em um campo separado nos segmentos e são indexados para uso com a pesquisa.

**Topics**
+ [Registrar anotações com o X-Ray SDK para Java](#xray-sdk-java-segment-annotations)
+ [Registrar metadados com o X-Ray SDK para Java](#xray-sdk-java-segment-metadata)
+ [Gravando usuário IDs com o X-Ray SDK for Java](#xray-sdk-java-segment-userid)

## Registrar anotações com o X-Ray SDK para Java
<a name="xray-sdk-java-segment-annotations"></a>

Use anotações para registrar informações em segmentos ou subsegmentos que você deseja indexar para pesquisa.

**Requisitos de anotação**
+ **Chaves**: a chave para uma anotação do X-Ray pode ter até 500 caracteres alfanuméricos. Você não pode usar espaços ou símbolos que não sejam um ponto (.)
+ **Valores**: o valor de uma anotação do X-Ray pode ter até 1.000 caracteres Unicode.
+ O número de **anotações**: você pode usar até cinquenta anotações por rastreamento.

**Como registrar anotações**

1. Obtenha uma referência para o segmento ou subsegmento atual no `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();
   ```

   ou

   ```
   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. Chame `putAnnotation` com uma chave de string e um valor de número, string ou booliano.

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

   O exemplo a seguir mostra como chamar `putAnnotation` com uma chave String que inclui um ponto e um valor booliano, numérico ou de string.

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

O SDK registra anotações como pares de chave-valor em um objeto `annotations` no documento de segmentos. Chamar `putAnnotation` duas vezes com a mesma chave substitui os valores registrados anteriormente no mesmo segmento ou subsegmento.

Para encontrar rastreamentos que têm anotações com valores específicos, use a palavra-chave `annotation[key]` em uma [expressão de filtro](xray-console-filters.md).

**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): anotações e metadados**  

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

## Registrar metadados com o X-Ray SDK para Java
<a name="xray-sdk-java-segment-metadata"></a>

Use metadados para registrar informações em segmentos ou subsegmentos dos quais você não precisa indexados para pesquisa. Valores de metadados podem ser strings, números, boolianos ou qualquer objeto que possa ser serializado em uma matriz ou objeto JSON.

**Como registrar metadados**

1. Obtenha uma referência para o segmento ou subsegmento atual no `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();
   ```

   ou

   ```
   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. Chame `putMetadata` com um namespace de string e uma chave de string e um valor booleano, de número, string ou objeto.

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

   or

   Chame `putMetadata` com apenas uma chave e valor.

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

Se você não especificar um namespace, o SDK usará `default`. Chamar `putMetadata` duas vezes com a mesma chave substitui os valores registrados anteriormente no mesmo segmento ou subsegmento.

**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): anotações e metadados**  

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

## Gravando usuário IDs com o X-Ray SDK for Java
<a name="xray-sdk-java-segment-userid"></a>

Registre o usuário IDs nos segmentos da solicitação para identificar o usuário que enviou a solicitação.

**Para gravar usuário IDs**

1. Obtenha uma referência para o segmento atual em `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. Chame `setUser` com um ID de string do usuário que enviou a solicitação.

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

Você pode acionar `setUser` em seus controladores para registrar o ID de usuário assim que o aplicativo começar a processar uma solicitação. Se pretende usar o segmento apenas para definir o ID de usuário, você pode vincular as chamadas em uma única linha.

**Example [src/main/java/scorekeep/MoveController.java](https://github.com/awslabs/eb-java-scorekeep/tree/xray/src/main/java/scorekeep/MoveController.java) — ID do usuário**  

```
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);
  }
```

Para encontrar rastreamentos para um ID de usuário, use a `user` palavra-chave em uma [expressão de filtragem](xray-console-filters.md).