Como configurar o Cloud Trace para Java

É possível ativar o Cloud Trace para aplicativos Java usando o OpenCensus. O OpenCensus é um conjunto de bibliotecas de instrumentação para coletar dados de trace e métrica que funcionam com vários back-ends. Para ver os detalhes mais recentes sobre o OpenCensus para Java, além de documentação e exemplos adicionais, acesse census-instrumentation/opencensus-java.

Como instalar a biblioteca

Para coletar traces, adicione o coletor de dados do OpenCensus e o exportador do Stackdriver ao arquivo Maven ou Gradle de aplicativos:

Maven

<dependency>
  <groupId>io.opencensus</groupId>
  <artifactId>opencensus-api</artifactId>
  <version>0.28.3</version>
</dependency>
<dependency>
  <groupId>io.opencensus</groupId>
  <artifactId>opencensus-exporter-trace-stackdriver</artifactId>
  <version>0.28.3</version>
  <exclusions>
    <exclusion>
      <groupId>io.grpc</groupId>
      <artifactId>grpc-api</artifactId>
    </exclusion>
  </exclusions>
</dependency>
<dependency>
  <groupId>io.opencensus</groupId>
  <artifactId>opencensus-impl</artifactId>
  <version>0.28.3</version>
  <scope>runtime</scope>
</dependency>
<dependency>
   <groupId>joda-time</groupId>
   <artifactId>joda-time</artifactId>
   <version>2.10.11</version>
</dependency>
<dependency>
  <groupId>com.google.api</groupId>
  <artifactId>gax-grpc</artifactId>
  <version>2.5.0</version>
</dependency>

Gradle

compile 'io.opencensus:opencensus-api:0.28.3'
compile 'io.opencensus:opencensus-exporter-trace-stackdriver:0.28.3'
runtime 'io.opencensus:opencensus-impl:0.28.3'

Como configurar o exportador do Stackdriver

Para exportar os dados do Trace coletados, use um objeto StackdriverTraceExporter:

public static void createAndRegisterGoogleCloudPlatform(String projectId) throws IOException {
  StackdriverTraceExporter.createAndRegister(
      StackdriverTraceConfiguration.builder().setProjectId(projectId).build());
}

Se você estiver executando na infraestrutura do Google Cloud, não será necessário chamar setProjectID e fornecer o código do projeto do Google Cloud. Se você não definir esse campo, a biblioteca de cliente para Java coletará automaticamente esses dados de um servidor de metadados do Google Cloud.

Se você não estiver executando na infraestrutura do Google Cloud, forneça o ID do projeto do Google Cloud ao aplicativo.

Quando você não define explicitamente o ID do projeto do Google Cloud, a biblioteca Java google-cloud determina automaticamente se a variável de ambiente GOOGLE_CLOUD_PROJECT está definida. Se essa variável for definida, a biblioteca usará o valor de GOOGLE_CLOUD_PROJECT como o ID do projeto do Google Cloud.

Para mais informações, acesse google-cloud-library como especificar um ID do projeto. Para definir a variável de ambiente, realize as seguintes ações:

Linux ou macOS

export GOOGLE_CLOUD_PROJECT=your-project-id

Windows

set GOOGLE_CLOUD_PROJECT=your-project-id

PowerShell:

$env:GOOGLE_CLOUD_PROJECT="your-project-id"

Adicionar um período de trace personalizado

Embora a biblioteca do OpenCensus contenha integrações automáticas para vários frameworks da Web e RPC conhecidos, também é possível criar traces personalizados:

private static final Tracer tracer = Tracing.getTracer();

public static void doWork() {
  // Create a child Span of the current Span.
  try (Scope ss = tracer.spanBuilder("MyChildWorkSpan").startScopedSpan()) {
    doInitialWork();
    tracer.getCurrentSpan().addAnnotation("Finished initial work");
    doFinalWork();
  }
}

private static void doInitialWork() {
  // ...
  tracer.getCurrentSpan().addAnnotation("Doing initial work");
  // ...
}

private static void doFinalWork() {
  // ...
  tracer.getCurrentSpan().addAnnotation("Hello world!");
  // ...
}

Como configurar a integração com o Cloud Logging

Para informações sobre como enviar dados do Cloud Trace para o Cloud Logging, consulte Como integrar ao Cloud Logging.

Como ativar a amostragem completa

Por padrão, de 10.000 traces, apenas um deles é amostrado.

Em um ambiente de desenvolvedor, essa taxa de amostragem pode ser muito lenta para exibir dados de trace. Para testar todos os traces, use a opção alwaysSample.

Para ativar a amostragem completa, use o método setSampler e especifique a opção alwaysSample:

public static void doWorkFullSampled() {
  try (Scope ss =
      tracer
          .spanBuilder("MyChildWorkSpan")
          .setSampler(Samplers.alwaysSample())
          .startScopedSpan()) {
    doInitialWork();
    tracer.getCurrentSpan().addAnnotation("Finished initial work");
    doFinalWork();
  }
}

Como substituir a autenticação automática

Você pode modificar a autenticação automática e a seleção do projeto. Por exemplo, a amostra a seguir ilustra como criar um exportador cujas credenciais expiram em 60 segundos a partir do momento da criação:

public static void createAndRegisterWithToken(String accessToken) throws IOException {
  Date expirationTime = DateTime.now().plusSeconds(60).toDate();

  GoogleCredentials credentials =
      GoogleCredentials.create(new AccessToken(accessToken, expirationTime));
  StackdriverTraceExporter.createAndRegister(
      StackdriverTraceConfiguration.builder()
          .setProjectId("MyStackdriverProjectId")
          .setCredentials(credentials)
          .build());
}

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 para o ambiente usando o Console do Google Cloud, consulte Como configurar o projeto do Google Cloud.

  • Para usuários gcloud, especifique os escopos de acesso usando a sinalização --scopes e inclua o escopo de acesso trace.append da API Cloud Trace. 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. Forneça essas credenciais definindo a variável de ambiente GOOGLE_APPLICATION_CREDENTIALS:

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 ver os traces no Visualizador de traces do Console do 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