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á.

# Gerar subsegmentos personalizados com o X-Ray SDK para Java
<a name="xray-sdk-java-subsegments"></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 

Os subsegmentos estendem o [segmento](xray-concepts.md#xray-concepts-segments) de um rastreamento com detalhes sobre o trabalho realizado para atender a uma solicitação. Sempre que você faz uma chamada com um cliente instrumentado, o X-Ray SDK registra as informações geradas em um subsegmento. Você pode criar subsegmentos adicionais para agrupar outros subsegmentos, medir o desempenho de uma seção do código ou registrar anotações e metadados.

Para gerenciar subsegmentos, use os métodos `beginSubsegment` e `endSubsegment`.

**Example GameModel.java - subsegmento personalizado**  

```
import [com.amazonaws.xray.AWSXRay](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/AWSXRay.html);
...
  public void saveGame(Game game) throws SessionNotFoundException {
    // wrap in subsegment
    Subsegment subsegment = AWSXRay.beginSubsegment("Save Game");
    try {
      // check session
      String sessionId = game.getSession();
      if (sessionModel.loadSession(sessionId) == null ) {
        throw new SessionNotFoundException(sessionId);
      }
      mapper.save(game);
    } catch (Exception e) {
      subsegment.addException(e);
      throw e;
    } finally {
      AWSXRay.endSubsegment();
    }
  }
```

Neste exemplo, o código dentro do subsegmento carrega a sessão do jogo do DynamoDB com um método no modelo de sessão e usa o mapeador do DynamoDB para AWS SDK para Java salvar o jogo. O encapsulamento desse código em um subsegmento transforma as chamadas do DynamoDB em filhas do subsegmento `Save Game` na visualização de rastreamento no console.

![\[Timeline showing Scorekeep and DynamoDB operations with durations and status checks.\]](http://docs.aws.amazon.com/pt_br/xray/latest/devguide/images/scorekeep-PUTrules-timeline-subsegments.png)


Se o código no seu subsegmento lança exceções verificadas, encapsule-o em um bloco `try` e chame `AWSXRay.endSubsegment()` em um bloco `finally` para garantir que o subsegmento esteja sempre fechado. Se um subsegmento não estiver fechado, o segmento pai não poderá ser concluído e não será enviado para o X-Ray.

Para código que não lança exceções verificadas, você pode transmitir o código para `AWSXRay.CreateSubsegment` como uma função do Lambda.

**Example Função de subsegmento do Lambda**  

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

AWSXRay.createSubsegment("getMovies", (subsegment) -> {
    // function code
});
```

Quando você cria um subsegmento dentro de um segmento ou outro subsegmento, o X-Ray SDK para Java gera um ID para ele e registra a hora de início e de término.

**Example Subsegmento com metadados**  

```
"subsegments": [{
  "id": "6f1605cd8a07cb70",
  "start_time": 1.480305974194E9,
  "end_time": 1.4803059742E9,
  "name": "Custom subsegment for UserModel.saveUser function",
  "metadata": {
    "debug": {
      "test": "Metadata string from UserModel.saveUser"
    }
  },
```

Para programação assíncrona e com vários threads, você deve passar manualmente o subsegmento para o método `endSubsegment()` para garantir que ele seja fechado corretamente, pois o contexto do X-Ray pode ser modificado durante a execução assíncrona. Se um subsegmento assíncrono for fechado após o fechamento do segmento pai, esse método transmitirá automaticamente o segmento inteiro para o daemon do X-Ray.

**Example Subsegmento assíncrono**  

```
@GetMapping("/api")
public ResponseEntity<?> api() {
  CompletableFuture.runAsync(() -> {
      Subsegment subsegment = AWSXRay.beginSubsegment("Async Work");
      try {
          Thread.sleep(3000);
      } catch (InterruptedException e) {
          subsegment.addException(e);
          throw e;
      } finally {
          AWSXRay.endSubsegment(subsegment);
      }
  });
  return ResponseEntity.ok().build();
}
```