Configuración de Stackdriver Trace para Java

OpenCensus, un conjunto de bibliotecas de métricas de seguimiento y aplicación que funcionan con varios backends, proporciona la asistencia de Java de Stackdriver Trace. En la página de GitHub, encontrarás información actualizada sobre OpenCensus para Java, además de documentación y ejemplos adicionales.

Cómo instalar la biblioteca

Para recopilar seguimientos, deberás agregar OpenCensus-Java y el exportador de Stackdriver a tu aplicación. Puedes hacerlo con Maven o Gradle:

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'

Cómo registrar el exportador

Deberás registrar el exportador de Stackdriver Trace:

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

Cómo agregar un intervalo de seguimiento personalizado

Si bien la biblioteca de Stackdriver Trace para Java integra automáticamente varios marcos de trabajo de RPC y web populares, también puedes interactuar manualmente con los seguimientos:

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!");
  // ...
}

Cómo habilitar el muestreo completo

De manera predeterminada, se realiza el muestreo de 1 en 10,000 seguimientos.

En el entorno de desarrollo, esa tasa de muestreo es demasiado baja para mostrar los datos de seguimiento. Puedes usar la opción alwaysSample para hacer el muestreo de todos los seguimientos. No utilices esta opción en un entorno de producción, ya que puede generar un gran volumen de datos de seguimiento y aumentar la facturación de uso.

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

Ejecución en Google Cloud Platform

No es necesario que proporciones credenciales de autenticación para las instancias que se ejecutan en Google Cloud Platform, siempre y cuando el nivel de acceso a la API de Stackdriver Trace esté habilitado en esa instancia. Sin embargo, recomendamos establecer el nivel de acceso más amplio posible para la instancia y, luego, usar Cloud Identity and Access Management a fin de restringir el acceso.

Para anular la selección automática de proyectos incluida en google-cloud-java (en la que se basa OpenCensus), reemplaza el código agregado cuando registres el exportador con el siguiente código:

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

Para anular la autenticación automática y la selección del proyecto, utiliza el siguiente código:

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

Entorno flexible de App Engine

En el entorno flexible de App Engine, el nivel de acceso a la API de Stackdriver Trace está habilitado de forma predeterminada, y la biblioteca cliente de OpenCensus se puede usar sin proporcionar credenciales o un ID del proyecto.

Entorno estándar de App Engine

En el entorno estándar de App Engine, el nivel de acceso a la API de Stackdriver Trace está habilitado de forma predeterminada, y la biblioteca cliente de OpenCensus se puede usar sin proporcionar credenciales o un ID del proyecto.

GKE

En GKE, agrega el nivel de acceso de OAuth trace.append cuando crees el clúster:

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

No puedes cambiar los niveles de acceso del clúster una vez creado.

Compute Engine

Para las instancias de VM de Compute Engine, debes habilitar explícitamente el nivel de acceso a la API de Stackdriver Trace trace.append para cada instancia de VM. Cuando crees una instancia nueva con Google Cloud Platform Console, selecciona los siguientes valores en la sección Identidad y acceso a la API en el panel Crear una instancia:

  1. Selecciona Cuenta de servicio predeterminada de Compute Engine para Cuenta de servicio.
  2. Selecciona Permitir el acceso total a todas las API de Cloud para Niveles de servicio.

Para usar una cuenta que no sea la cuenta de servicio predeterminada de Compute Engine, consulta las secciones Cómo crear y habilitar cuentas de servicio para instancias y Cómo ejecutar de manera local y en otro lugar. Lo importante es que la cuenta de servicio que uses tenga la función de Agente de Cloud Trace.

Cómo ejecutar de manera local y en otro lugar

Para ejecutar Trace fuera de GCP, debes proporcionar tu ID del proyecto de GCP y las credenciales de la cuenta de servicio correspondiente directamente en Trace. Esto se aplica a la ejecución de la biblioteca en tu propia estación de trabajo, en las computadoras de tu centro de datos o en las instancias de VM de otro proveedor de servicios en la nube. A continuación, se detallan los pasos:

  1. Crea una cuenta de servicio nueva en tu proyecto de GCP. Debe tener al menos la función de Agente de Cloud Trace. Para obtener más instrucciones, consulta Cómo crear una cuenta de servicio.

  2. Descarga el archivo de credenciales de la clave de la cuenta de servicio a tu computadora. Para obtener más instrucciones, consulta Cómo crear y administrar claves de cuentas de servicio.

  3. Proporciona tu ID del proyecto de GCP y la ubicación del archivo de credenciales a Trace con los parámetros (project_id y keyfile) o variables de entorno (GOOGLE_CLOUD_PROJECT y GOOGLE_APPLICATION_CREDENTIALS).

Cómo usar las variables de entorno

Define las variables de entorno de forma que estén visibles para Trace. Si están visibles de forma más amplia, podrían interferir en las autorizaciones existentes para otras aplicaciones.

Linux/macOS

export GOOGLE_CLOUD_PROJECT=your-project-id
export GOOGLE_APPLICATION_CREDENTIALS=/path/to/key.json

Windows

Ventana de comando:

set GOOGLE_CLOUD_PROJECT=your-project-id
set GOOGLE_APPLICATION_CREDENTIALS=/path/to/key.json

PowerShell:

$env:GOOGLE_CLOUD_PROJECT="your-project-id"
$env:GOOGLE_APPLICATION_CREDENTIALS="/path/to/key.json"

Cómo ver los seguimientos

Después de la implementación, puedes ver los seguimientos en el lector de seguimiento de GCP Console.

Ir a la página del Lector de seguimiento

¿Te sirvió esta página? Envíanos tu opinión:

Enviar comentarios sobre…

¿Necesitas ayuda? Visita nuestra página de asistencia.