Configura Cloud Trace para Java

Puedes habilitar las aplicaciones de Cloud Trace para 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 sobre OpenCensus para Java, junto con 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.26.0</version>
</dependency>
<dependency>
  <groupId>io.opencensus</groupId>
  <artifactId>opencensus-exporter-trace-stackdriver</artifactId>
  <version>0.26.0</version>
</dependency>
<dependency>
  <groupId>io.opencensus</groupId>
  <artifactId>opencensus-impl</artifactId>
  <version>0.26.0</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 automáticamente estos datos de 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 explícitamente el ID del proyecto de Google Cloud, la biblioteca Java google-cloud determina automáticamente si se configura la variable de entorno GOOGLE_CLOUD_PROJECT. Si se configura esta variable, la biblioteca usa el valor de GOOGLE_CLOUD_PROJECT como el ID de tu proyecto de Google Cloud.

Para obtener más información, consulta google-cloud-library cómo especificar un ID del proyecto. 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 de proyectos. Por ejemplo, el siguiente ejemplo ilustra cómo crear un exportador cuyas credenciales caducan a los 60 segundos de la 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 forma de una cuenta de servicio a la biblioteca cliente. Sin embargo, debes asegurarte de que tu Google Cloud Platform 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 permiso de acceso a la API de Cloud Trace esté habilitado. Para los usuarios de gcloud, especifica los permisos de acceso mediante la marca --scopes y, luego, incluye el permiso de acceso a la API de Cloud Trace trace.append. Por ejemplo, para crear un clúster de GKE con solo la API de Cloud Trace habilitada, haz lo siguiente:

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 forma 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 Crea una cuenta de servicio.

Las bibliotecas cliente de Google Cloud usan credenciales predeterminadas de la aplicación (ADC) para encontrar las credenciales de tu aplicación. Para proporcionar estas credenciales, configura 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