Java e OpenTelemetry

Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Esta página é voltada a desenvolvedores de aplicativos que querem coletar dados do Cloud Trace para aplicativos Java usando o OpenTelemetry. O OpenTelemetry é um conjunto de bibliotecas de instrumentação para coletar dados de rastreamento e métrica. Essas bibliotecas funcionam com vários back-ends. Para coletar traces com OpenTelemetry e Java, faça o seguinte, conforme descrito nesta página:

  • Instale os pacotes do OpenTelemetry.
  • Configure seu aplicativo para exportar períodos para o Cloud Trace.
  • Configure sua plataforma.

Para ver informações sobre a versão, consulte:

Para ver os detalhes mais recentes sobre o OpenTelemetry para Java, além de documentação e exemplos extras, consulte OpenTelemetry.

Antes de começar

  • É necessário usar o Java 8 ou mais recente.
  • Verifique se a API Cloud Trace está ativada no seu projeto do Google Cloud:

    1. Clique no botão a seguir ou, no console do Google Cloud, selecione APIs e serviços e, em seguida, selecione API Cloud Trace:

      Acessar a API Trace

    2. Na página API Cloud Trace, se o botão Ativar for exibido, clique nele. Se esse botão não for exibido, a API Cloud Trace estará ativada para o projeto selecionado.

Instalar os pacotes do OpenTelemetry

Para coletar traces, adicione o rastreamento do OpenTelemetry e o exportador do Cloud Trace para OpenTelemetry ao arquivo Maven ou Gradle do aplicativo:

  • Para uma lista das dependências do OpenTelemetry publicada mais recentemente, consulte Maven e Gradle.

  • Para as dependências de exportador necessárias, consulte a tabela a seguir:

    Maven

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

    As instruções anteriores especificam uma versão do exportador: Verifique se você selecionou a versão mais recente do exportador.

    Gradle

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

    A instrução anterior especifica uma versão do exportador. Verifique se você selecionou a versão mais recente do exportador.

Configurar a exportação de períodos para o Cloud Trace

Para exportar os dados do Trace coletados, use um objeto TraceExporter: Veja a seguir como criar esse objeto com uma configuração padrão:

TraceExporter traceExporter = TraceExporter.createWithDefaultConfiguration();

Também é possível especificar uma configuração e transmiti-la para o exportador. Por exemplo, o código a seguir define o projeto do Google Cloud:

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

Depois que o exportador for configurado, defina o TracerProvider:

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

No exemplo anterior, a chamada para BatchSpanProcessor configura o provedor para enviar períodos com um processo em segundo plano. Recomendamos usar essa configuração, exceto se você estiver usando o Cloud Run. O Cloud Run não é compatível com processos em segundo plano.

Para informações sobre como definir campos de autenticação, consulte a seção de configuração do exportador do Cloud Trace para OpenTelemetry.

Criar períodos

Para ver informações sobre como configurar seu aplicativo para capturar períodos de rastreamento, consulte Rastreamento do OpenTelemetry. Esta página descreve como fazer o seguinte:

  • Criar um período
  • Criar períodos aninhados
  • Definir atributos de período
  • Criar períodos com eventos
  • Criar períodos com links

Configurar a amostragem

Para informações sobre como configurar quando os traces forem amostrados, consulte Amostrador do OpenTelemetry. Nesta página, descrevemos as opções de amostragem disponíveis.

Exemplo de aplicativo

Para um exemplo de aplicativo, consulte TraceExporterExample.java.

Configurar sua plataforma

Você pode usar o Cloud Trace no Google Cloud e em outras plataformas.

Como executar no Google Cloud

Quando seu aplicativo está em execução no Google Cloud, não é necessário fornecer credenciais de autenticação na forma de uma conta de serviço para a biblioteca de cliente. No entanto, verifique se o escopo de acesso da API Cloud Trace está ativado no Google Cloud Platform.

Para uma lista de ambientes do Google Cloud compatíveis, consulte Suporte ao ambiente.

Para as seguintes configurações, as definições de escopo de acesso padrão ativam a API Cloud Trace:

  • Ambiente flexível do App Engine
  • Ambiente padrão do App Engine

  • Google Kubernetes Engine (GKE)

  • Compute Engine

  • Cloud Run

Se você usar escopos de acesso personalizados, verifique se o escopo de acesso da API Cloud Trace está ativado.

  • Para informações sobre como configurar os escopos de acesso do ambiente usando o Console do Google Cloud, consulte Como configurar seu projeto do Google Cloud.

  • Para usuários do gcloud, especifique os escopos de acesso usando a sinalização --scopes e inclua o escopo de acesso da API Cloud Trace trace.append. Por exemplo, para criar um cluster do GKE com apenas a API Cloud Trace ativada, faça o seguinte:

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

Execução local e em outro lugar

Se o aplicativo estiver em execução fora do Google Cloud, forneça as credenciais de autenticação na forma de uma conta de serviço para a biblioteca de cliente. A conta de serviço precisa conter o papel de agente do Cloud Trace. Para instruções, consulte Como criar uma conta de serviço.

As bibliotecas de cliente do Google Cloud usam o Application Default Credentials (ADC) para encontrar as credenciais do aplicativo.

Você pode fornecer essas credenciais de três maneiras:

  • Executar gcloud auth application-default login

  • Colocar a conta de serviço em um caminho padrão para seu sistema operacional. A seguir, listamos os caminhos padrão do Windows e do Linux:

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

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

  • Defina a variável de ambiente GOOGLE_APPLICATION_CREDENTIALS como o caminho para a conta de serviço:

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"

Como visualizar os traces

Após a implantação, é possível visualizar os traces no visualizador de traces do console do Google Cloud.

Acesse a página do visualizador do Trace

Solução de problemas

Para informações sobre como solucionar problemas com o Cloud Trace, acesse a página de solução de problemas.

Recursos