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

Ver no GitHub (em inglês) Feedback
<dependency>
  <groupId>io.opencensus</groupId>
  <artifactId>opencensus-api</artifactId>
  <version>0.27.1</version>
</dependency>
<dependency>
  <groupId>io.opencensus</groupId>
  <artifactId>opencensus-exporter-trace-stackdriver</artifactId>
  <version>0.27.1</version>
</dependency>
<dependency>
  <groupId>io.opencensus</groupId>
  <artifactId>opencensus-impl</artifactId>
  <version>0.27.1</version>
  <scope>runtime</scope>
</dependency>
<dependency>
   <groupId>joda-time</groupId>
   <artifactId>joda-time</artifactId>
   <version>2.10.6</version>
</dependency>

Gradle

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

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

Como 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 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

Se você usar escopos de acesso personalizados, verifique se o escopo de acesso da API Cloud Trace está ativado. 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. 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

Resolver problemas

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

Recursos