Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.

# Generazione di sottosegmenti personalizzati con X-Ray SDK for Java
<a name="xray-sdk-java-subsegments"></a>

**Nota**  
Avviso di SDK/Daemon manutenzione a raggi X: il 25 febbraio 2026, X-Ray SDKs/Daemon entrerà in modalità di manutenzione, in cui AWS limiterà le versioni di AWS X-Ray SDK e Daemon per risolvere solo problemi di sicurezza. Per ulteriori informazioni sulla tempistica del supporto, consulta. [Cronologia di X-Ray SDK e Daemon Support](xray-sdk-daemon-timeline.md) Ti consigliamo di migrare a. OpenTelemetry Per ulteriori informazioni sulla migrazione a OpenTelemetry, vedere [Migrazione dalla strumentazione a raggi X](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html) alla strumentazione. OpenTelemetry 

I sottosegmenti estendono il [segmento](xray-concepts.md#xray-concepts-segments) di una traccia con dettagli sul lavoro svolto per soddisfare una richiesta. Ogni volta che si effettua una chiamata con un client dotato di strumentazione, l'X-Ray SDK registra le informazioni generate in un sottosegmento. È possibile creare sottosegmenti aggiuntivi per raggruppare altri sottosegmenti, misurare le prestazioni di una sezione di codice o registrare annotazioni e metadati.

Per gestire i sottosegmenti, utilizza i metodi `beginSubsegment` e `endSubsegment`.

**Example GameModel.java - sottosegmento personalizzato**  

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

In questo esempio, il codice all'interno del sottosegmento carica la sessione del gioco da DynamoDB con un metodo sul modello di sessione e utilizza il mapper DynamoDB per salvare il AWS SDK per Java gioco. Inserendo questo codice in un sottosegmento, le chiamate DynamoDB sono figli del `Save Game` sottosegmento nella vista trace della console.

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


Se il codice nel tuo sottosegmento genera eccezioni gestite, eseguine il wrapping in un blocco `try` e chiama `AWSXRay.endSubsegment()` in un blocco `finally` per assicurare che il sottosegmento sia sempre chiuso. Se un sottosegmento non è chiuso, il segmento principale non può essere completato e non verrà inviato a X-Ray.

Per il codice che non genera eccezioni controllate, puoi passare il codice a `AWSXRay.CreateSubsegment` come funzione Lambda.

**Example Funzione Lambda del sottosegmento**  

```
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 si crea un sottosegmento all'interno di un segmento o di un altro sottosegmento, X-Ray SDK for Java genera un ID per tale sottosegmento e registra l'ora di inizio e l'ora di fine.

**Example Sottosegmento con metadati**  

```
"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"
    }
  },
```

Per la programmazione asincrona e multithread, è necessario passare manualmente il sottosegmento al `endSubsegment()` metodo per assicurarsi che sia chiuso correttamente, poiché il contesto X-Ray può essere modificato durante l'esecuzione asincrona. Se un sottosegmento asincrono viene chiuso dopo la chiusura del segmento principale, questo metodo trasmetterà automaticamente l'intero segmento al demone X-Ray.

**Example Sottosegmento asincrono**  

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