Java y OpenTelemetry

Esta página está destinada a desarrolladores de aplicaciones que desean recopilar datos de Cloud Trace para aplicaciones de Java mediante OpenTelemetry. OpenTelemetry es un framework de instrumentación neutral al proveedor que puedes usar para recopilar datos de seguimiento y métricas. Para obtener información sobre cómo instrumentar tu código, consulta Instrumentación y observabilidad.

En esta página, se te guiará a través de los siguientes pasos:

  • Instala los paquetes de OpenTelemetry.
  • Configura la aplicación para exportar intervalos a Cloud Trace.
  • Configura tu plataforma.

Para obtener información sobre la versión, consulta los siguientes vínculos:

Para obtener contenido de referencia de OpenTelemetry, consulta lo siguiente:

Si deseas obtener los detalles más recientes de OpenTelemetry para Java, además de documentación y ejemplos adicionales, consulta OpenTelemetry.

Antes de comenzar

  • Debes usar Java 8 o una versión posterior.

  • Habilita la API necesaria.

    Habilita la API

Instala los paquetes de OpenTelemetry

Si deseas recopilar seguimientos, agrega el seguimiento de OpenTelemetry y el exportador de Cloud Trace para OpenTelemetry al archivo Maven o Gradle de tu aplicación:

  • Para obtener la lista de dependencias de OpenTelemetry publicada más recientemente, consulta Maven y Gradle.

  • Para conocer las dependencias del exportador necesarias, consulta la siguiente tabla:

    Maven

    <dependency>
  <groupId>com.google.cloud.opentelemetry</groupId>
  <artifactId>exporter-trace</artifactId>
  <version>0.15.0</version>
</dependency>

    Las sentencias anteriores especifican una versión de exportador. Asegúrate de seleccionar la versión más reciente del exportador.

    Gradle

    implementation 'com.google.cloud.opentelemetry:exporter-trace:0.15.0'

    La sentencia anterior especifica una versión del exportador. Asegúrate de seleccionar la versión más reciente del exportador.

Configura la exportación de intervalos a Cloud Trace

Para exportar los datos de Trace recopilados, usa un objeto TraceExporter. A continuación, se muestra cómo crear este objeto con una configuración predeterminada:

TraceExporter traceExporter = TraceExporter.createWithDefaultConfiguration();

También puedes especificar una configuración y, luego, pasarla al exportador. Por ejemplo, el siguiente código configura el proyecto de Google Cloud:

TraceExporter traceExporter = TraceExporter.createWithConfiguration(
  TraceConfiguration.builder().setProjectId("MY_PROJECT").build());

Después de configurar el exportador, establece el TracerProvider:

OpenTelemetrySdk.builder()
          .setTracerProvider(
              SdkTracerProvider.builder()
                  .addSpanProcessor(BatchSpanProcessor.builder(traceExporter).build())
                  .build())
          .buildAndRegisterGlobal();

En el ejemplo anterior, la llamada a BatchSpanProcessor configura el proveedor para que envíe intervalos con un proceso en segundo plano.

Para obtener información sobre cómo configurar los campos de autenticación, consulta la sección de configuración del exportador de Cloud Trace para OpenTelemetry.

Crear intervalos

Si deseas obtener información sobre cómo configurar tu aplicación para capturar intervalos de seguimiento, consulta Registro de OpenTelemetry. En esta página, se describe cómo hacer todo lo siguiente:

  • Crear un intervalo
  • Crear intervalos anidados
  • Establecer atributos de intervalo
  • Crear intervalos con eventos
  • Crear intervalos con vínculos

Configura el muestreo

Para obtener información sobre cómo configurar cuándo se muestrean los seguimientos, consulta Muestra de OpenTelemetry. En esta página, se describen las opciones de muestreo disponibles.

Aplicación de ejemplo

Para ver una aplicación de ejemplo, consulta TraceExporterExample.java.

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 Google Cloud Platform tenga habilitado el permiso de acceso a la API de Cloud Trace.

Para obtener una lista de los entornos de Google Cloud compatibles, consulta Compatibilidad de entornos.

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

Si usas permisos de acceso personalizados, debes asegurarte de que el permiso de acceso a la API de Cloud Trace esté habilitado:

  • Si quieres obtener información para configurar los permisos de acceso de tu entorno mediante la consola de Google Cloud, consulta Configura tu proyecto de Google Cloud.

  • Para los usuarios de gcloud, especifica los niveles 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 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 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.

Puedes proporcionar estas credenciales de una de estas tres maneras:

  • Ejecución gcloud auth application-default login

  • Coloca la cuenta de servicio en una ruta de acceso predeterminada para tu sistema operativo. A continuación, se muestran las rutas predeterminadas para Windows y Linux:

    • Windows: %APPDATA%/gcloud/application_default_credentials.json

    • Linux: $HOME/.config/gcloud/application_default_credentials.json

  • Establece la variable de entorno GOOGLE_APPLICATION_CREDENTIALS en la ruta de acceso a la cuenta de servicio:

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"

Ver seguimientos

En la consola de Google Cloud, ve a la página Explorador de seguimiento:

Ve al Explorador de seguimiento

También puedes usar la barra de búsqueda para encontrar esta página.

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