Implementa OpenTelemetry administrado para GKE

En este documento, se explica cómo configurar OpenTelemetry administrado para GKE y enviar registros, métricas y seguimientos del protocolo OpenTelemetry (OTLP) a Google Cloud Observability desde aplicaciones que se ejecutan en GKE.

Para obtener más detalles sobre cómo funciona Managed OpenTelemetry para GKE, consulta Managed OpenTelemetry para GKE.

Puedes usar Managed OpenTelemetry para GKE para hacer lo siguiente:

  • Configura las cargas de trabajo que se ejecutan en GKE para enviar seguimientos, métricas y registros de OpenTelemetry Protocol (OTLP) al recopilador administrado.
  • Recibe registros, métricas y seguimientos del protocolo OpenTelemetry (OTLP) de las aplicaciones que se ejecutan en GKE.
  • Exportar esos datos a Google Cloud Observability

Si necesitas filtros y controles a nivel del recopilador, usa el recopilador de OpenTelemetry integrado en Google en lugar de esta oferta administrada.

Antes de comenzar

  1. Accede a tu cuenta de Google Cloud . Si eres nuevo en Google Cloud, crea una cuenta para evaluar el rendimiento de nuestros productos en situaciones reales. Los clientes nuevos también obtienen $300 en créditos gratuitos para ejecutar, probar y, además, implementar cargas de trabajo.

  2. Instala Google Cloud CLI.

  3. Si usas un proveedor de identidad externo (IdP), primero debes acceder a la gcloud CLI con tu identidad federada.

  4. Para inicializar gcloud CLI, ejecuta el siguiente comando: 

    gcloud init

  5. Crea o selecciona un Google Cloud proyecto.

    Roles necesarios para seleccionar o crear un proyecto

    • Selecciona un proyecto: Para seleccionar un proyecto, no se requiere un rol de IAM específico. Puedes seleccionar cualquier proyecto en el que se te haya otorgado un rol.
    • Crear un proyecto: Para crear un proyecto, necesitas el rol de Creador de proyectos (roles/resourcemanager.projectCreator), que contiene el permiso resourcemanager.projects.create. Obtén más información para otorgar roles.

    • Crea un proyecto de Google Cloud :

      gcloud projects create PROJECT_ID

      Reemplaza PROJECT_ID por un nombre para el proyecto Google Cloud que estás creando.

    • Selecciona el proyecto Google Cloud que creaste:

      gcloud config set project PROJECT_ID

      Reemplaza PROJECT_ID por el nombre de tu proyecto de Google Cloud .

  6. Verifica que tengas los permisos necesarios para completar esta guía.

  7. Verifica que la facturación esté habilitada para tu proyecto de Google Cloud .

  8. Habilita las APIs de GKE, Telemetry (OTLP), Cloud Logging, Cloud Monitoring y Cloud Trace:

    Roles necesarios para habilitar las APIs

    Para habilitar las APIs, necesitas el rol de IAM de administrador de Service Usage (roles/serviceusage.serviceUsageAdmin), que contiene el permiso serviceusage.services.enable. Obtén más información para otorgar roles. 

    gcloud services enable container.googleapis.com telemetry.googleapis.com logging.googleapis.com monitoring.googleapis.com cloudtrace.googleapis.com

  9. Instala Google Cloud CLI.

  10. Si usas un proveedor de identidad externo (IdP), primero debes acceder a la gcloud CLI con tu identidad federada.

  11. Para inicializar gcloud CLI, ejecuta el siguiente comando: 

    gcloud init

  12. Crea o selecciona un Google Cloud proyecto.

    Roles necesarios para seleccionar o crear un proyecto

    • Selecciona un proyecto: Para seleccionar un proyecto, no se requiere un rol de IAM específico. Puedes seleccionar cualquier proyecto en el que se te haya otorgado un rol.
    • Crear un proyecto: Para crear un proyecto, necesitas el rol de Creador de proyectos (roles/resourcemanager.projectCreator), que contiene el permiso resourcemanager.projects.create. Obtén más información para otorgar roles.

    • Crea un proyecto de Google Cloud :

      gcloud projects create PROJECT_ID

      Reemplaza PROJECT_ID por un nombre para el proyecto Google Cloud que estás creando.

    • Selecciona el proyecto Google Cloud que creaste:

      gcloud config set project PROJECT_ID

      Reemplaza PROJECT_ID por el nombre de tu proyecto de Google Cloud .

  13. Verifica que tengas los permisos necesarios para completar esta guía.

  14. Verifica que la facturación esté habilitada para tu proyecto de Google Cloud .

  15. Habilita las APIs de GKE, Telemetry (OTLP), Cloud Logging, Cloud Monitoring y Cloud Trace:

    Roles necesarios para habilitar las APIs

    Para habilitar las APIs, necesitas el rol de IAM de administrador de Service Usage (roles/serviceusage.serviceUsageAdmin), que contiene el permiso serviceusage.services.enable. Obtén más información para otorgar roles. 

    gcloud services enable container.googleapis.com telemetry.googleapis.com logging.googleapis.com monitoring.googleapis.com cloudtrace.googleapis.com
    16.

Requisitos

Para usar Managed OpenTelemetry para GKE, debes cumplir con los siguientes requisitos:

  • El clúster debe tener la versión 1.34.1-gke.2178000 de GKE o una posterior.
  • Gcloud CLI debe estar habilitada con la versión 551.0.0 o posterior.
  • Si usas Terraform para aprovisionar tu infraestructura de GKE, debes usar el proveedor terraform-provider-google-beta en la versión v7.17.0 o una posterior.

Roles obligatorios

Para obtener los permisos que necesitas para habilitar y usar OpenTelemetry administrado por GKE, pídele a tu administrador que te otorgue los siguientes roles de IAM en tu proyecto:

Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.

También puedes obtener los permisos necesarios a través de roles personalizados o cualquier otro rol predefinido.

Costos

Consulta la sección Facturación para obtener detalles sobre los costos relacionados con el uso de Managed OpenTelemetry para GKE.

Habilita Managed OpenTelemetry para GKE en un clúster

Para configurar Managed OpenTelemetry para GKE, debes hacer lo siguiente:

  • Habilita OpenTelemetry administrado para GKE en un clúster.
  • Configura la aplicación que supervisas para que envíe indicadores al extremo del recopilador administrado.

Cuando habilitas OpenTelemetry administrado para GKE, se implementan los siguientes objetos en el clúster:

  • Es una implementación del recopilador de OpenTelemetry administrado por GKE que se implementa en el espacio de nombres gke-managed-otel. El extremo HTTP del colector de OpenTelemetry administrado en el clúster para registros, métricas y seguimientos es el siguiente: http://opentelemetry-collector.gke-managed-otel.svc.cluster.local:4318.

  • Una definición de recurso personalizado, instrumentations.telemetry.googleapis.com, que puedes usar para configurar automáticamente tus cargas de trabajo.

    Para obtener más detalles sobre los recursos personalizados, consulta recurso personalizado en la documentación de Kubernetes.

Habilita en un clúster nuevo

Para habilitar Managed OpenTelemetry para GKE en un clúster nuevo, sigue estos pasos:

gcloud

Para un clúster de Autopilot, usa el siguiente comando:

gcloud beta container clusters create-auto CLUSTER_NAME \
  --project=PROJECT_ID \
  --managed-otel-scope=COLLECTION_AND_INSTRUMENTATION_COMPONENTS \
  --location=LOCATION \
  --cluster-version=VERSION

Reemplaza lo siguiente:

  • CLUSTER_NAME: el nombre del clúster
  • PROJECT_ID: Es el ID del proyecto de Google Cloud .
  • LOCATION: la región o la zona.
  • VERSION: La versión, que debe ser 1.34.1-gke.2178000 o posterior.

Para un clúster de Standard, usa el siguiente comando:

gcloud beta container clusters create CLUSTER_NAME \
  --project=PROJECT_ID \
  --managed-otel-scope=COLLECTION_AND_INSTRUMENTATION_COMPONENTS \
  --location=LOCATION \
  --cluster-version=VERSION

Reemplaza lo siguiente:

  • CLUSTER_NAME: el nombre del clúster
  • PROJECT_ID: Es el ID del proyecto de Google Cloud .
  • LOCATION: la región o la zona.
  • VERSION: La versión, que debe ser 1.34.1-gke.2178000 o posterior.

Console

  • Para un clúster de Autopilot, haz lo siguiente:

    1. En la consola de Google Cloud , ve a la página Crea un clúster de Autopilot.

      Ir a Crea un clúster de Autopilot

    2. En el panel de navegación, haz clic en Configuración avanzada.

    3. En la sección Operaciones, selecciona Habilitar OpenTelemetry administrado.

    4. Haz clic en Guardar.

  • Para un clúster de Standard, haz lo siguiente:

    1. En la consola de Google Cloud , ve a la página Crea un clúster de Kubernetes.

      Ir a Crea un clúster de Kubernetes

    2. En el panel de navegación, haz clic en Funciones.

    3. En la sección Operaciones, selecciona Habilitar OpenTelemetry administrado.

    4. Haz clic en Guardar.

Terraform

Para habilitar OpenTelemetry administrado para GKE en un clúster nuevo con Terraform, consulta el siguiente ejemplo:

terraform {
  required_providers {
    google-beta = {
      source  = "hashicorp/google-beta"
      version = ">= 7.17.0"
    }
  }
}

resource "google_container_cluster" "default" {
  name     = "gke-standard-regional-with-managed-otel"
  provider = google-beta
  location = "us-west1"

  initial_node_count = 1
  release_channel {
    channel = "RAPID" # The default rapid version already has the feature available.
  }

  managed_opentelemetry_config {
    scope = "COLLECTION_AND_INSTRUMENTATION_COMPONENTS"
  }
}

Si deseas obtener más información sobre el uso de Terraform, consulta Compatibilidad con Terraform para GKE.

Habilita en un clúster existente

Para habilitar Managed OpenTelemetry para GKE en un clúster existente, sigue estos pasos:

gcloud

  1. Asegúrate de que la versión del clúster sea 1.34.1-gke.2178000 o posterior. Para obtener detalles sobre cómo actualizar un clúster existente, consulta Actualizaciones de clústeres de Standard y Actualizaciones de clústeres de Autopilot.

  2. Habilita Managed OpenTelemetry para GKE con el siguiente comando:

    gcloud beta container clusters update CLUSTER_NAME \
  --project=PROJECT_ID \
  --managed-otel-scope=COLLECTION_AND_INSTRUMENTATION_COMPONENTS \
  --location=LOCATION

    Reemplaza lo siguiente:

    • CLUSTER_NAME: el nombre del clúster
    • PROJECT_ID: Es el ID del proyecto de Google Cloud .
    • LOCATION: la región o la zona.

Console

  1. Asegúrate de que la versión del clúster sea 1.34.1-gke.2178000 o posterior. Para obtener detalles sobre cómo actualizar un clúster existente, consulta Actualizaciones de clústeres de Standard y Actualizaciones de clústeres de Autopilot.

  2. En la consola de Google Cloud , accede a la página de clústeres de Kubernetes:

    Ir a clústeres de Kubernetes

  3. Haz clic en el nombre del clúster.

  4. En la lista Funciones, busca la opción Managed OpenTelemetry. Si aparece como inhabilitado, haz clic en editar Editar y, luego, selecciona Habilitar OpenTelemetry administrado.

  5. Haz clic en Guardar cambios.

Terraform

Para habilitar Managed OpenTelemetry para GKE en un clúster existente, agrega el bloque managed_opentelemetry_config a tu recurso google_container_cluster existente, de forma similar al siguiente ejemplo:

terraform {
  required_providers {
    google-beta = {
      source  = "hashicorp/google-beta"
      version = ">= 7.17.0"
    }
  }
}

resource "google_container_cluster" "default" {
  name     = "gke-standard-regional-with-managed-otel"
  provider = google-beta
  location = "us-west1"

  initial_node_count = 1
  release_channel {
    channel = "RAPID" # The default rapid version already has the feature available.
  }

  managed_opentelemetry_config {
    scope = "COLLECTION_AND_INSTRUMENTATION_COMPONENTS"
  }
}

Si deseas obtener más información sobre el uso de Terraform, consulta Compatibilidad con Terraform para GKE.

Configura tu aplicación para usar el recopilador de OpenTelemetry administrado

Las aplicaciones deben configurarse para poder enviar indicadores al extremo del recopilador administrado. Cuando se configuran las aplicaciones, el recopilador de OpenTelemetry administrado recibe indicadores de las aplicaciones que se ejecutan en el clúster en el que está habilitado el recopilador. Los indicadores de la aplicación incluyen registros, métricas y seguimientos.

Para enviar indicadores de OpenTelemetry, las aplicaciones ya deben estar instrumentadas para generar métricas de OpenTelemetry. Para obtener más información, consulta las cargas de trabajo compatibles.

Puedes configurar tu aplicación de forma manual para enviar indicadores al extremo del recopilador administrado o usar la configuración automática. No recomendamos usar ambos métodos juntos para la misma carga de trabajo, ya que la configuración automática puede anular los cambios manuales. Esta combinación puede dificultar el seguimiento de los cambios en la configuración.

En las siguientes secciones, se describe cómo configurar las aplicaciones para que envíen indicadores al recopilador con la configuración automática.

Cómo configurar la configuración automática

La configuración automática usa variables de entorno para configurar las cargas de trabajo de modo que envíen indicadores al extremo del recopilador administrado.

Para habilitar la inserción automática de variables de entorno en los Pods, usa el recurso personalizado Instrumentation. Las variables de entorno tienen la configuración de OpenTelemetry y se pueden insertar en algunos Pods con etiquetas coincidentes en un espacio de nombres o en todos los Pods de un espacio de nombres.

Luego, cuando se implementa una aplicación en el espacio de nombres, GKE usa la configuración para insertar automáticamente variables de entorno en los Pods en los que se ejecutan las cargas de trabajo.

  1. Para configurar el recurso personalizado Instrumentation, haz lo siguiente:

    1. Guarda el siguiente manifiesto Instrumentation en un archivo llamado otlp-auto-config-namespace.yaml:

      apiVersion: telemetry.googleapis.com/v1alpha1
kind: Instrumentation
metadata:
  namespace: NAMESPACE
  name: NAME
spec:
  selector:
    matchLabels:
      KEY: VALUE
  autoInstrumentationConfig:
    configInjection:
      enabled: true
  otelSDKConfig:
    tracer_provider:
      sampler:
        parent_based:
          root:
            trace_id_ratio_based:
              ratio: "TRACE_RATIO"
    meter_provider:
      readers:
      - periodic:
          interval: METRICS_INTERVAL

      Reemplaza lo siguiente:

      • NAMESPACE: Es el espacio de nombres que contiene los Pods para los que deseas habilitar la instrumentación automática. Usa default para segmentar el espacio de nombres predeterminado.
      • NAME: Es el nombre del archivo de manifiesto. En este ejemplo, el nombre es otlp-auto-config-namespace.yaml.
      • (Opcional) Es la etiqueta adjunta a los Pods para la segmentación. Si se especifica un selector vacío ({}), se segmentarán todos los Pods del espacio de nombres.
        • KEY: la clave de la etiqueta.
        • VALUE: el valor de la etiqueta.
      • TRACE_RATIO: Es la proporción de datos de seguimiento que se recopilarán. Si no se especifica, el valor predeterminado es 1.0. Para obtener más detalles, consulta Cómo modificar la tasa de muestreo de registros.
      • METRICS_INTERVAL: Es el intervalo, en milisegundos, de los datos de supervisión que se recopilarán. El valor predeterminado es 30000. El valor debe ser no negativo, con un mínimo de 5,000 ms, un máximo de 300,000 ms y un múltiplo de 5,000 ms. Para obtener más detalles, consulta Cómo modificar el intervalo de exportación de métricas.

    2. Si deseas modificar alguno de los parámetros de configuración, consulta la siguiente sección para modificar la configuración.

    3. Aplica la configuración ejecutando el siguiente comando:

      kubectl apply -f otlp-auto-config-namespace.yaml

  2. Para insertar las variables de entorno automáticamente, debes implementar la aplicación en el espacio de nombres de tu clúster que tiene aplicada la configuración.

    • Para aplicar la configuración a una carga de trabajo que aún no se ejecuta en el espacio de nombres, implementa la carga de trabajo con el siguiente comando:

      kubectl apply -f DEPLOYMENT_NAME -n NAMESPACE

      Reemplaza lo siguiente:

      • DEPLOYMENT_NAME: El nombre de la implementación.
      • NAMESPACE: es el espacio de nombres.

    • Para aplicar la configuración a una carga de trabajo que ya se está ejecutando en el espacio de nombres, vuelve a implementar la carga de trabajo con el siguiente comando:

      kubectl rollout restart deployment DEPLOYMENT_NAME -n NAMESPACE

      Reemplaza lo siguiente:

      • DEPLOYMENT_NAME: El nombre de la implementación.
      • NAMESPACE: es el espacio de nombres.

Después de aplicar la configuración al clúster, GKE configura automáticamente todas las cargas de trabajo cuando se implementan en el clúster. Las cargas de trabajo se instrumentan insertando variables de entorno en los Pods en los que se ejecutan.

Cuando una carga de trabajo configurada con estas variables de entorno se ejecuta en un clúster en el que se implementa el recopilador administrado, a medida que se ejecuta la carga de trabajo, envía indicadores de OpenTelemetry al recopilador administrado. Estos indicadores están disponibles para que los veas en Google Cloud Observability.

Para obtener más detalles sobre cómo ver los indicadores, consulta Visualiza la telemetría. Para ver un ejemplo, consulta Cómo generar datos de telemetría de muestra.

Modifique la configuración

Para modificar la configuración, debes hacer lo siguiente:

  1. Modifica el archivo de manifiesto Instrumentation.

  2. Aplica la configuración modificada.

  3. Vuelve a implementar o reiniciar las aplicaciones en el espacio de nombres correspondiente de tu clúster después de aplicar la configuración modificada.

Para obtener más detalles sobre estos pasos, sigue las instrucciones de la sección Crea y, luego, implementa la configuración.

Modificar la cantidad o la frecuencia de la recopilación de datos

Puedes modificar la cantidad de datos de seguimiento recopilados modificando la tasa de muestreo del seguimiento.

Puedes modificar la frecuencia con la que se envían los datos de supervisión a Cloud Monitoring modificando el intervalo de exportación de métricas.

No puedes modificar la cantidad ni la frecuencia de los datos de registro recopilados. Sin embargo, puedes inhabilitar la recopilación de todos los datos de registro, métricas o seguimiento. Para obtener más información, consulta Cómo seleccionar el tipo de señal que se recopilará.

Cómo modificar la tasa de muestreo de registros

Una carga de trabajo puede generar una gran cantidad de datos de seguimiento. En tu caso, es importante que determines el equilibrio entre el costo de recopilar y almacenar datos, y el nivel de detalle que necesitas para que los datos sean útiles.

El comportamiento predeterminado del SDK de OpenTelemetry es always_on, lo que equivale a una proporción de 1.

A continuación, se muestra un ejemplo de la configuración de la frecuencia de muestreo del registro. En este ejemplo, la proporción es 0.25, por lo que los datos de seguimiento se recopilan a una tasa del 25%. Modifica este número de proporción para cambiar la frecuencia de muestreo.

    tracer_provider:
      sampler:
        parent_based:
          root:
            trace_id_ratio_based:
              ratio: "0.25"

Cómo modificar el intervalo de exportación de métricas

El intervalo de exportación de métricas determina la granularidad de los datos que puedes ver en los gráficos de Cloud Monitoring.

A continuación, se muestra un ejemplo de la configuración del intervalo de exportación de métricas. En este ejemplo, el intervalo de exportación es de 30,000 ms.

El intervalo de exportación de métricas se usa para especificar el intervalo de demora entre el inicio de dos exportaciones consecutivas de métricas desde el SDK de OpenTelemetry.

El valor de este intervalo debe ser no negativo, con un mínimo de 5,000 ms, un máximo de 300,000 ms y un múltiplo de 5,000 ms. El valor se expresa en milisegundos.

meter_provider:
  readers:
  - periodic:
      interval: 30000

Selecciona los tipos de indicadores que deseas recopilar

Puedes controlar qué tipos de indicadores se recopilan de una carga de trabajo inhabilitando los tipos de indicadores que no deseas recopilar. Los tipos de indicadores son registros, métricas y seguimientos.

Puedes inhabilitar los tipos de señales con las variables de entorno en el contenedor en el que se ejecuta la carga de trabajo. Para modificar las variables de entorno, debes modificar el recurso personalizado Instrumentation y, luego, volver a implementar la carga de trabajo en el contenedor.

El siguiente ejemplo es un archivo de manifiesto de Instrumentation configurado para la recopilación de solo datos de seguimiento. La recopilación de registros y métricas está inhabilitada porque meter_provider y logger_provider están configurados como null.

apiVersion: telemetry.googleapis.com/v1alpha1
kind: Instrumentation
metadata:
  namespace: default
  name: otlp-auto-config-disable-metrics-logs
spec:
  selector:
    matchLabels: # Update the labels to match your workloads
      app: telemetrygen-app
  autoInstrumentationConfig:
    configInjection:
      enabled: true
  otelSDKConfig:
    meter_provider: null
    logger_provider: null

Recopila datos de instrucciones y respuestas multimodales

Puedes configurar Managed OpenTelemetry para GKE para recopilar datos de instrucciones y respuestas multimodales.

Esta funcionalidad está disponible para los agentes de LangGraph ReAct y los agentes de IA generativa creados con el framework del Kit de desarrollo de agentes (ADK).

Cuando recopilas datos de instrucciones y respuestas multimodales con Managed OpenTelemetry para GKE, se recopila el contenido completo de las instrucciones y respuestas de tu usuario final. Estos datos de instrucciones y respuestas se almacenan en un bucket de Cloud Storage. Para obtener detalles sobre cómo administrar el bucket de almacenamiento, incluido el control del acceso o la eliminación de datos, consulta la documentación de Cloud Storage.

Puedes usar productos como Model Armor y Sensitive Data Protection para administrar los datos sensibles que podrían estar en las instrucciones y respuestas.

Para configurar Managed OpenTelemetry para GKE de modo que recopile datos de instrucciones y respuestas multimodales, haz lo siguiente:

  1. Configura tu proyecto Google Cloud y el SDK que usas siguiendo las instrucciones de la sección Recopila instrucciones y respuestas multimodales.

  2. Crea o identifica un bucket de Cloud Storage para recopilar instrucciones y respuestas multimodales. Para obtener más información, consulta Crea un bucket.

  3. Otorga a la cuenta de servicio que usa tu aplicación el permiso storage.objects.create para el bucket de Cloud Storage.

    Este permiso permite que tu aplicación escriba objetos en el bucket de Cloud Storage. Estos objetos almacenan las instrucciones y las respuestas que crea y recibe la aplicación basada en agentes. Para obtener más información, consulta Configura y administra políticas de IAM en buckets.

  4. Configura el campo promptsResponses.uploadBasePath en el recurso personalizado Instrumentation, por ejemplo:

    apiVersion: telemetry.googleapis.com/v1alpha1
kind: Instrumentation
metadata:
  namespace: default
  name: prompts-responses
spec:
  selector: {}
  promptsResponses:
    uploadBasePath: gs://BUCKET_NAME

    Reemplaza BUCKET_NAME por el nombre del bucket de Cloud Storage.

Cuando se actualiza el recurso personalizado Instrumentation y se reinician las cargas de trabajo, las variables de entorno que configuran las instrucciones y las respuestas se insertan en los contenedores de las cargas de trabajo.

Para obtener más detalles sobre los tipos de contenido multimedia que puedes recopilar y cómo explorar tus instrucciones y respuestas multimodales, consulta Recopila y visualiza instrucciones y respuestas multimodales.

Inhabilita la configuración automática de las cargas de trabajo

Para inhabilitar la instrumentación automática de cargas de trabajo con la configuración especificada, borra el recurso personalizado Instrumentation de tu clúster. Para ello, usa el siguiente comando:

kubectl delete instrumentations.telemetry.googleapis.com INSTRUMENTATION_NAME -n NAMESPACE

Reemplaza lo siguiente:

  • INSTRUMENTATION_NAME: es el nombre del recurso personalizado de Instrumentation.
  • NAMESPACE: Es el espacio de nombres que contiene los Pods en los que quieres inhabilitar la configuración automática.

Para inhabilitar temporalmente la inyección automática de variable de entorno y, al mismo tiempo, conservar la configuración de la instrumentación automática para su uso futuro, establece autoInstrumentationConfig.configInjection.enabled en false y aplica el recurso personalizado actualizado.

A continuación, se muestra un ejemplo del recurso personalizado con la inyección automática de variable de entorno inhabilitada temporalmente:

apiVersion: telemetry.googleapis.com/v1alpha1
kind: Instrumentation
metadata:
  namespace: default
  name: otlp-auto-config-example
spec:
  selector:
    matchLabels: # Update the labels to match your workloads
      app: telemetrygen-app
  autoInstrumentationConfig:
    configInjection:
      enabled: false # disable environment variables config injection
  otelSDKConfig:
  ... # preserve OpenTelemetry configuration for future use

Después de borrar el recurso personalizado o actualizarlo para inhabilitar la inyección automática de configuración, GKE no instrumenta automáticamente las cargas de trabajo nuevas a las que se dirige el recurso personalizado Instrumentation.

Para dejar de exportar indicadores de OTLP al recopilador administrado desde una carga de trabajo que se instrumentó anteriormente con el recurso personalizado, debes reiniciar la carga de trabajo para que el cambio se aplique. Para ello, usa el siguiente comando:

kubectl rollout restart deployment DEPLOYMENT_NAME -n NAMESPACE

Reemplaza lo siguiente:

  • DEPLOYMENT_NAME: El nombre de la implementación.
  • NAMESPACE: es el espacio de nombres.

Ver telemetría

Cuando una carga de trabajo configurada se ejecuta en GKE, donde se habilitó OpenTelemetry administrado para GKE, los indicadores de OpenTelemetry se envían a Google Cloud Observability.

Para obtener detalles sobre cómo ver datos en Google Cloud Observability, consulta lo siguiente:

Genera telemetría de muestra

En esta sección, se describe cómo implementar una aplicación de ejemplo y cómo apuntar esa aplicación al extremo de OTLP del recopilador de OpenTelemetry administrado. Luego, puedes ver la telemetría en Google Cloud.

La aplicación de muestra es un pequeño generador que exporta seguimientos, registros y métricas al extremo HTTP del recopilador de OpenTelemetry administrado en el clúster. El extremo de OTLP está codificado de forma rígida dentro de la aplicación y apunta a http://opentelemetry-collector.gke-managed-otel.svc.cluster.local:4318.

Si ya tienes una aplicación instrumentada con un SDK de OpenTelemetry, puedes generar telemetría desde tu aplicación apuntándola al extremo del recopilador o configurando la instrumentación automática para la aplicación.

Para implementar la aplicación de ejemplo, haz lo siguiente:

  1. Conéctate al clúster en el que habilitaste OpenTelemetry administrado. Para ello, consulta Configura un clúster predeterminado para los comandos de kubectl.

  2. Ejecuta el comando siguiente:

    kubectl apply -f https://raw.githubusercontent.com/GoogleCloudPlatform/otlp-k8s-ingest/main/sample/gke-app.yaml

    Después de unos minutos, la telemetría que genera la aplicación comienza a fluir a través del recopilador hacia el backend de Google Cloud para cada indicador.

    1. Para verificar que se ingiere la telemetría, consulta los registros, las métricas y los seguimientos de la aplicación de demostración en la consola de Google Cloud :

    2. Para ver las métricas, haz lo siguiente:

      1. En la consola de Google Cloud , ve a la página Explorador de métricas:

        Ir al Explorador de métricas

      2. Ejecuta la siguiente consulta de PromQL en el Explorador de métricas:

        sum(avg_over_time({"__name__"="gen","namespace"="opentelemetry-demo","job"="telemetrygen"}[1h]))

    3. Para ver los registros, haz lo siguiente:

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

        Ir al Explorador de seguimiento

      2. Filtra los intervalos de seguimiento por nombre de intervalo igual a lets-go.

    4. Para ver los registros, haz lo siguiente:

      1. En la consola de Google Cloud , accede a la página Explorador de registros.

        Ve al Explorador de registros

      2. Ejecute la siguiente consulta:

        resource.type="k8s_pod"
resource.labels.namespace_name="opentelemetry-demo"

Inhabilita Managed OpenTelemetry para GKE

Puedes inhabilitar OpenTelemetry administrado para GKE en el clúster. Cuando inhabilitas el recopilador, se quita el recopilador de OpenTelemetry administrado del clúster y no se recopilan datos de telemetría nuevos.

Para inhabilitar Managed OpenTelemetry para GKE, sigue estos pasos.

gcloud

Para inhabilitar Managed OpenTelemetry para GKE en un clúster, ejecuta el siguiente comando de gcloud:

  gcloud beta container clusters update CLUSTER_NAME \
  --project=PROJECT_ID \
  --managed-otel-scope=NONE \
  --location=LOCATION

Reemplaza lo siguiente:

  • CLUSTER_NAME: el nombre del clúster
  • PROJECT_ID: Es el ID del proyecto de Google Cloud .
  • LOCATION: la región o la zona.

Console

  1. En la consola, ve a la lista de clústeres:

    Ir a clústeres de Kubernetes

  2. Selecciona el clúster en el que deseas inhabilitar el recopilador de Managed OpenTelemetry.

  3. En Detalles del clúster, junto a OpenTelemetry administrado, selecciona el ícono de edición.

  4. Desmarca la casilla de verificación para inhabilitar la función.

Terraform

Para inhabilitar Managed OpenTelemetry para GKE, actualiza el bloque managed_opentelemetry_config en tu recurso google_container_cluster para establecer el alcance en NONE.

  1. Actualiza tu archivo de configuración de Terraform:

    resource "google_container_cluster" "default" {
  provider = google-beta
  name     = "CLUSTER_NAME"
  location = "LOCATION"
  project  = "PROJECT_ID"

  # ... other configuration ...

  managed_opentelemetry_config {
    scope = "NONE"
  }
}

  2. Aplica la configuración de Terraform:

    terraform apply

Reemplaza lo siguiente:

  • CLUSTER_NAME: el nombre del clúster
  • LOCATION: la región o la zona.
  • PROJECT_ID: Es el ID del proyecto de Google Cloud .

Cuando inhabilitas Managed OpenTelemetry para GKE, no se quitan del clúster la definición del recurso personalizado Instrumentation ni los recursos personalizados Instrumentation. Si vuelves a habilitar OpenTelemetry administrado, se usará la configuración conservada en los recursos personalizados Instrumentation.

Si ya recopilaste datos de telemetría con Managed OpenTelemetry para GKE, inhabilitar el recopilador no afectará estos datos. Los datos existentes aún se almacenan en Google Cloud Observability y no se recopilan datos de telemetría nuevos.

Soluciona problemas

Cargas de trabajo con privilegios de socios de Autopilot

Si intentas usar la configuración automática con una carga de trabajo privilegiada de un socio de Autopilot, es posible que veas que se rechazó el Pod de la carga de trabajo.

La inyección de configuración de OpenTelemetry no es compatible con las cargas de trabajo privilegiadas de los socios de GKE Autopilot. Si segmentas esas cargas de trabajo con un recurso personalizado Instrumentation para habilitar la inserción de variable de entorno de OpenTelemetry, es posible que la carga de trabajo no coincida con la lista de entidades permitidas de cargas de trabajo con privilegios de Autopilot, lo que significa que GKE Autopilot rechazaría el Pod insertado en la configuración.

Los registros, las métricas o los seguimientos no se ven en la consola de Google Cloud

Los datos pueden no ser visibles por muchos motivos diferentes. Entre estos motivos, se incluyen la falta de permisos para ver los datos o una configuración incorrecta que impide la recopilación de datos.

Estos son los pasos que puedes seguir para resolver problemas habituales:

  • Asegúrate de tener habilitadas todas las APIs requeridas en tu proyecto.

  • Asegúrate de que el recurso personalizado Instrumentation esté configurado correctamente, con el espacio de nombres que coincida con el espacio de nombres en el que se ejecuta la carga de trabajo y el selector que coincida con la etiqueta de tu carga de trabajo.

  • Inspecciona el Pod de la carga de trabajo para ver si las variables de entorno se insertaron correctamente.

  • Verifica los registros del contenedor del recopilador de OpenTelemetry para ver si hay errores en el recopilador. Para ello, ejecuta el siguiente comando:

    kubectl logs -n gke-managed-otel -l app=opentelemetry-collector -c opentelemetry-collector

No funciona la inhabilitación de un indicador de telemetría

Cuando inhabilites un indicador de telemetría con el recurso personalizado Instrumentation, asegúrate de aplicar el recurso personalizado y volver a implementar las cargas de trabajo.

Cuando apliques el recurso personalizado, usa Server-Side Apply en el comando kubectl apply cuando actualices el recurso personalizado Instrumentation.

Para obtener detalles sobre cómo inhabilitar un indicador de telemetría, consulta Selecciona los tipos de indicadores que se recopilarán.

Las variables insertadas de OpenTelemetry no son visibles en mi carga de trabajo

Las variables se insertan en los contenedores de los Pods de carga de trabajo , no en la carga de trabajo. Verifica los Pods, no los objetos propietarios, como ReplicaSets o Deployments.

Por ejemplo, para confirmar que las variables se insertan correctamente para la carga de trabajo de muestra en el espacio de nombres predeterminado que se usó en la sección anterior Genera telemetría, haz lo siguiente:

  1. Ejecuta el comando siguiente:

    kubectl get pods -n default -l app=telemetrygen-app -o yaml

  2. Examina el spec.containers[*].env de los Pods.

  3. Asegúrate de que haya un objeto Instrumentation en el mismo espacio de nombres y verifica que esté segmentando el Pod y que tenga habilitada la función de inserción de configuración. Para ello, ejecuta el siguiente comando:

    kubectl get instrumentations.telemetry.googleapis.com -n default -o yaml

Las variables se insertan en los contenedores solo cuando se crean los Pods, ya que la API de Kubernetes no permite modificar la mayoría de los campos en la especificación de un Pod existente, como las variables de entorno. Para que la configuración surta efecto en las cargas de trabajo que se crearon antes de que crearas el objeto Instrumentation, reinicia la carga de trabajo. Por ejemplo, para una Deployment llamada telemetry-gen-app, ejecuta el siguiente comando:

kubectl rollout restart deployment -n default telemetry-gen-app

Una cantidad excesiva de datos de seguimiento en Cloud Trace

Para reducir la cantidad de datos recopilados por Cloud Trace, puedes configurar un muestreador basado en la relación de IDs de seguimiento para solo muestrear un porcentaje de tus seguimientos.

Por ejemplo, agrega lo siguiente al objeto Instrumentation:

spec:
  otelSDKConfig:
    tracer_provider:
      sampler:
        parent_based:
          root:
            trace_id_ratio_based:
              ratio: "0.01"

El comportamiento predeterminado del SDK de OpenTelemetry es el registro de seguimiento "always_on", que equivale a una proporción de 1.

Las variables de entorno no coinciden con la configuración

Si actualizaste el objeto Instrumentation, verifica que hayas reiniciado tus Pods como se describe en la sección Modifica la configuración.

Si ves la configuración incorrecta para tu Pod, verifica que el objeto Instrumentation apunte correctamente al Pod y que no tengas varios objetos Instrumentation que apunten al mismo Pod:

kubectl get instrumentations --all-namespaces \
-o custom-columns=NAMESPACE:.metadata.namespace,NAME:.metadata.name,SELECTOR:.spec.selector

kubectl get pod -n ${NAMESPACE:?} ${POD_NAME:?} --show-labels

Ten en cuenta que un selector vacío segmenta todos los Pods en su espacio de nombres.

Si varias instrumentaciones segmentan el mismo Pod cuando se crea, se aplica la instrumentación que se actualizó por última vez.

El comando kubectl logs no devuelve ningún resultado.

Cuando los registros se transmiten directamente desde una aplicación a un recopilador de OpenTelemetry, se omite la ruta de registro estándar para el tiempo de ejecución del contenedor. Este es el caso común cuando se usa OpenTelemetry para los registros. De forma predeterminada, el exportador envía los registros al extremo otlp en lugar de a los flujos stdout y stderr.

En este caso, como los registros no se escriben en los flujos stdout o stderr para que el tiempo de ejecución del contenedor los capture, el comando kubectl logs no mostrará ningún resultado para esa aplicación. En cambio, la salida de registro está disponible en Cloud Logging.

Si deseas usar el SDK de OpenTelemetry y también enviar registros a la transmisión stdout, puedes configurar esto con el exportador de registros. Para obtener más información, consulta Logs Exporter: salida estándar.

¿Qué sigue?