Como configurar o Stackdriver Trace para Java

O suporte Java do Trace é fornecido pelo OpenCensus, um conjunto de bibliotecas de instrumentação de métricas de aplicação e traces que trabalham com vários back-ends. Veja os detalhes mais recentes sobre o OpenCensus para Java, além de documentação e exemplos adicionais na página do GitHub.

Como instalar a biblioteca

Para coletar traces, adicione o rastreamento 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.12.2</version>
</dependency>
<dependency>
  <groupId>io.opencensus</groupId>
  <artifactId>opencensus-exporter-trace-stackdriver</artifactId>
  <version>0.12.2</version>
</dependency>
<dependency>
  <groupId>io.opencensus</groupId>
  <artifactId>opencensus-impl</artifactId>
  <version>0.12.2</version>
  <scope>runtime</scope>
</dependency>

Gradle

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

Como configurar o exportador do Stackdriver

Para exportar os dados coletados, use um exportador do Stackdriver. O exportador do Stackdriver usa o Application Default Credentials para autenticação. É possível omitir o código do projeto se ele for executado no Google Cloud Platform (GCP):

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

Adicionar um período de trace personalizado

Mesmo que a biblioteca do Stackdriver Trace para Java contenha integrações automáticas para várias bibliotecas conhecidas da Web e RPC, também é possível interagir manualmente com os traces:

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 ativar a amostragem completa

Por padrão, apenas 1 em 10 mil traces é amostrado.

Em um ambiente de desenvolvedor, essa taxa de amostragem é geralmente muito baixa para mostrar dados de trace. Você pode usar a opção alwaysSample para amostrar todos os traces. Não use essa opção em um ambiente de produção, isso pode gerar um grande volume de dados de trace e aumentar sua fatura de uso.

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 executar no Google Cloud Platform

Não será preciso fornecer credenciais de autenticação para instâncias em execução no Google Cloud Platform se o escopo de acesso da API Stackdriver Trace estiver ativado nessa instância. No entanto, recomendamos configurar o escopo de acesso mais amplo possível para sua instância e, em seguida, usar o Cloud Identity e o Access Management para restringir o acesso.

Para modificar a autenticação e a seleção de projetos automáticas, use o seguinte:

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

Ambiente flexível do App Engine

No ambiente flexível do App Engine, o escopo de acesso da API Stackdriver Trace é ativado por padrão. Além disso, a biblioteca de cliente OpenCensus pode ser usada sem a necessidade de fornecer credenciais ou um código de projeto.

Ambiente padrão do App Engine

No ambiente padrão do App Engine, o escopo de acesso da API Stackdriver Trace é ativado por padrão. Além disso, e a biblioteca de cliente do OpenCensus pode ser usada sem fornecer credenciais ou um código de projeto.

GKE

Para usar o Trace no GKE, adicione o escopo de acesso do OAuth trace.append ao criar um cluster.

Para criar um cluster usando o gcloud, faça o seguinte:

  1. Atualize o gcloud para a versão mais recente (opcional):
    gcloud components update
  2. Defina o código do projeto padrão:
    gcloud config set project [PROJECT_ID]
  3. Se você estiver trabalhando com clusters zonais, defina a zona de computação padrão:
    gcloud config set compute/zone [COMPUTE_ZONE]
  4. Se você estiver trabalhando com clusters regionais, defina a região de computação padrão:
    gcloud config set compute/region [COMPUTE_REGION]
  5. Execute o comando de criação:
    gcloud container clusters create example-cluster-name --scopes https://www.googleapis.com/auth/trace.append

Para informações mais detalhadas sobre como criar um cluster, consulte Como criar um cluster.

Compute Engine

Para as instâncias do Compute Engine, é preciso ativar explicitamente o escopo de acesso trace.append da API Stackdriver Trace para cada instância de VM. Ao criar uma nova instância por meio do Console do Google Cloud Platform, selecione os seguintes valores na seção Identidade e acesso à API do painel Criar uma instância:

  1. Selecione a Conta de serviço padrão do Compute Engine como a Conta de serviço
  2. Selecione Permitir acesso completo a todas as APIs do Cloud em Escopos de acesso.

Para usar algo diferente da conta de serviço padrão do Compute Engine, consulte as seções Como criar e ativar contas de serviços para instâncias e Como executar localmente e em outro local. O importante é que a conta de serviço que você usa tenha o papel de agente do Cloud Trace.

Como executar localmente e em outro local

Para executar o Stackdriver Trace fora do GCP, é necessário fornecer seu código de projeto do GCP e credenciais da conta de serviço apropriadas diretamente para a biblioteca de cliente do OpenCensus. Sua conta de serviço precisa conter o papel de agente do Cloud Trace. Para mais instruções, consulte Como criar uma conta de serviço.

Código do projeto

Forneça um código do projeto para o OpenCensus, conforme exibido em Como configurar o exportador do Stackdriver. Recomendamos que você defina a variável de ambiente GOOGLE_CLOUD_PROJECT como seu código do projeto e modifique seu aplicativo para ler essa variável. Essa última etapa não é obrigatória no Java, uma vez que a biblioteca google-cloud-java, que é invocada pelo OpenCensus, lê e usa essa variável de ambiente quando está disponível. Para mais informações, consulte a seção Como especificar um código de projeto na biblioteca do Google Cloud.

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"

Credenciais

As bibliotecas de cliente do GCP usam o Application Default Credentials (ADC) para localizar as credenciais do seu aplicativo. Você fornece credenciais à biblioteca de cliente do OpenCensus ao definir 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, você pode consultar os traces no visualizador de traces do Console do GCP.

Acesse a página do visualizador do Trace

Esta página foi útil? Conte sua opinião sobre:

Enviar comentários sobre…

Precisa de ajuda? Acesse nossa página de suporte.