Configura Cloud Trace para Java

Puedes habilitar Cloud Trace para aplicaciones de Java con OpenCensus. OpenCensus es un conjunto de bibliotecas de instrumentación para recopilar datos de seguimiento y métricas que funcionan con varios backends. Para obtener los detalles más recientes de OpenCensus para Java, además de la documentación y ejemplos adicionales, ve a census-instrumentation/opencensus-java.

Instala la biblioteca

Para recopilar seguimientos, agrega el seguimiento de OpenCensus y el exportador de Stackdriver al archivo Maven o Gradle de tu aplicación:

Maven

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

Configura el exportador de Stackdriver

Para exportar los datos de Trace recopilados, usa un objeto StackdriverTraceExporter:

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

Si ejecutas en la infraestructura de Google Cloud, no necesitas llamar a setProjectID y proporcionar tu ID del proyecto de Google Cloud. Si no configuras este campo, la biblioteca cliente para Java recopila de forma automática estos datos desde un servidor de metadatos de Google Cloud.

Si no ejecutas en la infraestructura de Google Cloud, debes proporcionar el ID del proyecto de Google Cloud a tu aplicación.

Cuando no configuras de forma explícita el ID del proyecto de Google Cloud, la biblioteca de google-cloud de Java determina de forma automática si la variable de entorno GOOGLE_CLOUD_PROJECT está configurada. Si se establece esta variable, la biblioteca usa el valor de GOOGLE_CLOUD_PROJECT como tu ID del proyecto de Google Cloud.

Para obtener más información, consulta cómo especificar un ID del proyecto con google-cloud-library. Para configurar la variable de entorno, sigue estos pasos:

Linux o macOS

export GOOGLE_CLOUD_PROJECT=your-project-id

Windows

set GOOGLE_CLOUD_PROJECT=your-project-id

PowerShell:

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

Agrega un intervalo de seguimiento personalizado

Si bien la biblioteca de OpenCensus contiene integraciones automáticas para varios frameworks web y framework RPC populares, también puedes crear seguimientos 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!");
  // ...
}

Configura la integración con Cloud Logging

Para obtener información sobre cómo enviar datos de Cloud Trace a Cloud Logging, consulta Integra con Cloud Logging.

Habilita el muestreo completo

De forma predeterminada, de 10,000 seguimientos, solo 1 se muestrea.

En un entorno de desarrollador, esta tasa de muestreo puede ser demasiado lenta para mostrarte datos de seguimiento. Para muestrear todos los seguimientos, puedes usar la opción alwaysSample.

Para habilitar el muestreo completo, usa el método setSampler y especifica la opción alwaysSample:

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

Anula la autenticación automática

Puedes anular la autenticación automática y la selección del proyecto. Por ejemplo, en la siguiente muestra se detalla cómo crear un exportador cuyas credenciales vencen 60 segundos después de su creación:

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

Configura tu plataforma

Puedes usar Cloud Trace en Google Cloud y otras plataformas.

Ejecuta en Google Cloud

Cuando tu aplicación se ejecuta en Google Cloud, no necesitas proporcionar credenciales de autenticación en el formato de una cuenta de servicio a la biblioteca cliente. Sin embargo, debes asegurarte de que tu plataforma de Google Cloud tenga habilitado el permiso de acceso a la API de Cloud Trace.

Para las siguientes opciones de configuración, la configuración predeterminada del permiso de acceso habilita la API de Cloud Trace:

  • Entorno flexible de App Engine
  • Entorno estándar de App Engine

  • Google Kubernetes Engine (GKE)

  • Compute Engine

Si usas permisos de acceso personalizados, debes asegurarte de que el nivel de acceso a la API de Cloud Trace esté habilitado. Para los usuarios de gcloud, especifica los permisos de acceso con la marca --scopes y, también, incluye el permiso de acceso a la API de Cloud Trace trace.append. Por ejemplo, para crear un clúster de GKE solo con la API de Cloud Trace habilitada, sigue estos pasos:

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

Ejecuta de forma local y en otros lugares

Si tu aplicación se ejecuta fuera de Google Cloud, debes proporcionar credenciales de autenticación en el formato de una cuenta de servicio a la biblioteca cliente. La cuenta de servicio debe contener la función de agente de Cloud Trace. Para obtener más instrucciones, consulta Cómo crear una cuenta de servicio.

Las bibliotecas cliente de Google Cloud usan las credenciales predeterminadas de la aplicación (ADC) para encontrar las credenciales de tu aplicación. Estas credenciales se proporcionan mediante la configuración de la variable de entorno 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"

Cómo ver los seguimientos

Después de la implementación, puedes ver los seguimientos en el visor de seguimientos de Cloud Console.

Ir a la página del Lector de seguimiento

Soluciona problemas

Para obtener información sobre cómo solucionar problemas con Cloud Trace, ve a la página de solución de problemas.

Recursos