Java e OpenTelemetry

Questa pagina è progettata per gli sviluppatori di applicazioni che vogliono raccogliere dati di Cloud Trace per applicazioni Java utilizzando OpenTelemetry. OpenTelemetry è un framework di strumentazione indipendente dal fornitore che puoi usare per raccogliere dati di tracce e metriche. Per informazioni sulla strumentazione del tuo codice, consulta Strumentazione e osservabilità.

  • Installare i pacchetti OpenTelemetry.
  • Configura la tua applicazione per esportare gli intervalli in Cloud Trace.
  • Configura la tua piattaforma.

Per informazioni sulla release, consulta le pagine seguenti:

Per i contenuti di riferimento di OpenTelemetry, vedi quanto segue:

Per i dettagli più recenti su OpenTelemetry per Java, insieme alla documentazione aggiuntiva e agli esempi, consulta OpenTelemetry.

Prima di iniziare

  • Devi utilizzare Java 8 o versioni successive.

  • Nel pannello di navigazione della console Google Cloud, seleziona API e servizi, fai clic su Abilita API e servizi e poi abilita l'Cloud Trace API:

    Vai alle impostazioni dell'API Cloud Trace

  • Se viene visualizzato API abilitata, significa che l'API è già abilitata. In caso contrario, fai clic sul pulsante Attiva.

Installare i pacchetti OpenTelemetry

Per raccogliere le tracce, aggiungi il tracciamento di OpenTelemetry e l'esportatore Cloud Trace per OpenTelemetry al file Maven o Gradle della tua applicazione:

  • Per l'elenco delle dipendenze di OpenTelemetry pubblicato più di recente, vedi Maven e Gradle.

  • Per le dipendenze dell'esportatore necessarie, vedi la seguente tabella:

    Maven

    <dependency>
  <groupId>com.google.cloud.opentelemetry</groupId>
  <artifactId>exporter-trace</artifactId>
  <version>0.15.0</version>
</dependency>

    Le istruzioni precedenti specificano una versione dell'esportatore. Assicurati di selezionare la release più recente dell'esportatore.

    Gradle

    implementation 'com.google.cloud.opentelemetry:exporter-trace:0.15.0'

    L'istruzione precedente specifica una versione dell'esportatore. Assicurati di selezionare la release più recente dell'esportatore.

Configura l'esportazione di intervalli in Cloud Trace

Per esportare i dati di Trace raccolti, utilizza un oggetto TraceExporter. Di seguito viene illustrato come creare questo oggetto con una configurazione predefinita:

TraceExporter traceExporter = TraceExporter.createWithDefaultConfiguration();

Puoi anche specificare una configurazione e passarla all'esportatore. Ad esempio, il codice seguente imposta il progetto Google Cloud:

TraceExporter traceExporter = TraceExporter.createWithConfiguration(
  TraceConfiguration.builder().setProjectId("MY_PROJECT").build());

Dopo aver configurato l'esportatore, imposta TracerProvider:

OpenTelemetrySdk.builder()
          .setTracerProvider(
              SdkTracerProvider.builder()
                  .addSpanProcessor(BatchSpanProcessor.builder(traceExporter).build())
                  .build())
          .buildAndRegisterGlobal();

Nell'esempio precedente, la chiamata a BatchSpanProcessor configura il provider per l'invio di intervalli con un processo in background.

Per informazioni su come impostare i campi di autenticazione, consulta la sezione relativa alla configurazione dell'esportatore di Cloud Trace per OpenTelemetry.

Crea intervalli

Per informazioni su come configurare l'applicazione per acquisire intervalli di traccia, consulta OpenTelemetry Tracciamento. In questa pagina viene descritto come effettuare tutte le seguenti operazioni:

  • Crea un intervallo
  • Crea intervalli nidificati
  • Imposta attributi intervallo
  • Creare intervalli con eventi
  • Creare intervalli con link

Configura il campionamento

Per informazioni su come configurare il momento in cui le tracce vengono campionate, consulta OpenTelemetry Sampler. In questa pagina vengono descritte le opzioni di campionamento disponibili.

Applicazione di esempio

Per un'applicazione di esempio, consulta TraceExporterExample.java.

Configura la tua piattaforma

Puoi utilizzare Cloud Trace su Google Cloud e altre piattaforme.

In esecuzione su Google Cloud

Quando la tua applicazione è in esecuzione su Google Cloud, non è necessario fornire alla libreria client le credenziali di autenticazione sotto forma di account di servizio. Tuttavia, devi assicurarti che per la tua piattaforma Google Cloud sia abilitato l'ambito di accesso all'API Cloud Trace.

Per un elenco degli ambienti Google Cloud supportati, consulta la pagina relativa all'assistenza per gli ambienti.

Per le seguenti configurazioni, le impostazioni predefinite dell'ambito di accesso abilitano l'Cloud Trace API:

Se utilizzi ambiti di accesso personalizzati, devi assicurarti che l'ambito di accesso all'API Cloud Trace sia abilitato:

  • Per informazioni su come configurare gli ambiti di accesso per il tuo ambiente utilizzando la console Google Cloud, consulta Configurazione del progetto Google Cloud.

  • Per gli utenti gcloud, specifica gli ambiti di accesso utilizzando il flag --scopes e includi l'ambito di accesso all'Cloud Trace API trace.append. Ad esempio, per creare un cluster GKE in cui è abilitata solo l'Cloud Trace API:

    gcloud container clusters create example-cluster-name --scopes=https://www.googleapis.com/auth/trace.append

Esecuzione in locale e altrove

Se la tua applicazione viene eseguita al di fuori di Google Cloud, devi fornire alla libreria client le credenziali di autenticazione sotto forma di account di servizio. L'account di servizio deve contenere il ruolo agente Cloud Trace. Per le istruzioni, vedi Creazione di un account di servizio.

Le librerie client di Google Cloud utilizzano le Credenziali predefinite dell'applicazione (ADC) per trovare le credenziali della tua applicazione.

Puoi fornire queste credenziali in uno dei tre modi seguenti:

  • Esegui gcloud auth application-default login

  • Inserisci l'account di servizio in un percorso predefinito per il tuo sistema operativo. Di seguito sono elencati i percorsi predefiniti per Windows e Linux:

    • Windows: %APPDATA%/gcloud/application_default_credentials.json

    • Linux: $HOME/.config/gcloud/application_default_credentials.json

  • Imposta la variabile di ambiente GOOGLE_APPLICATION_CREDENTIALS sul percorso al tuo account di servizio:

Linux/macOS

    export GOOGLE_APPLICATION_CREDENTIALS=path-to-your-service-accounts-private-key

Windows

    set GOOGLE_APPLICATION_CREDENTIALS=path-to-your-service-accounts-private-key

PowerShell:

    $env:GOOGLE_APPLICATION_CREDENTIALS="path-to-your-service-accounts-private-key"

Visualizza tracce

Nel pannello di navigazione della console Google Cloud, seleziona Trace e poi Trace Explorer:

Vai a Trace Explorer

Risoluzione dei problemi

Per informazioni sulla risoluzione dei problemi relativi a Cloud Trace, vai alla pagina Risoluzione dei problemi.

Risorse