Migra los recopiladores para que usen exportadores de OTLP

La API de Telemetry (OTLP) es una implementación del protocolo OpenTelemetry. La compatibilidad con OTLP te permite agregar exportadores genéricos otlphttp y otlp_grpc/otlp_logs a la configuración de tu recopilador, lo que evita los exportadores específicos del proveedor. Las aplicaciones pueden enviar datos de registro, métricas y seguimientos a la API de Telemetry.

Esta guía se aplica a ti si la configuración de tu recopilador usa el googlecloud exportador o el googlemanagedprometheus exportador:

Para migrar a los exportadores de OTLP, sigue estos pasos:

  1. Habilita la API de Telemetry.
  2. Autoriza la cuenta de servicio del recopilador.
  3. Configura la variable de entorno GOOGLE_CLOUD_PROJECT.
  4. Agrega la extensión googleclientauth.
  5. Agrega los exportadores otlphttp y otlp_grpc/otlp_logs.
  6. Agrega procesadores.
  7. Actualiza las canalizaciones de servicio.
  8. Valida tu configuración.
  9. Migra los paneles y las políticas de alertas.
  10. Quita los exportadores específicos del proveedor.

Habilita la API de Telemetry

Los exportadores de OTLP escriben en la API de Telemetry, por lo que esa API debe estar habilitada en tu proyecto. Para habilitar la API de Telemetry, ejecuta el siguiente comando:

gcloud services enable telemetry.googleapis.com

Autoriza la cuenta de servicio del recopilador

El recopilador se autentica en las Google Cloud APIs con la identidad del entorno en el que se ejecuta. La cuenta de servicio que ejecuta tu recopilador debe tener permiso para usar la API de Telemetry para escribir datos de registro, métricas y seguimientos. Además, como la API de Telemetry es una API de consumidor, debes especificar de forma explícita el Google Cloud proyecto cuya cuota consumen las llamadas a la API y otorgar a la cuenta de servicio los permisos necesarios para consumir la cuota de ese proyecto.

Roles obligatorios

Para asegurarte de que la cuenta de servicio que ejecuta tu recopilador tenga los permisos necesarios para enviar datos de registro, métricas y seguimientos, pídele a tu administrador que otorgue las siguientes funciones de IAM a la cuenta de servicio que ejecuta tu recopilador en tu proyecto:

Estos roles predefinidos contienen los permisos necesarios para enviar datos de registro, métricas y seguimientos. Para ver los permisos exactos que son necesarios, expande la sección Permisos requeridos:

Permisos necesarios

Se requieren los siguientes permisos para enviar datos de registro, métricas y seguimientos:

  • logging.logEntries.create
  • monitoring.timeSeries.create
  • telemetry.traces.write
  • serviceusage.services.use

Cuenta de servicio de Kubernetes

Si implementas el recopilador en Google Kubernetes Engine (GKE) con la federación de identidades para cargas de trabajo para GKE, otorga las funciones necesarias a tu cuenta de servicio de Kubernetes.

Puedes usar los siguientes comandos para otorgar las funciones necesarias si la cuota de la API se extrae del mismo Google Cloud proyecto que es el destino de las llamadas a la API de Telemetry. Antes de ejecutar los comandos, reemplaza PROJECT_ID por el ID de tu proyecto. Sin embargo, si usas un proyecto de cuota independiente, reemplaza PROJECT_ID en el segundo comando por el ID de tu proyecto de cuota:

export PROJECT_NUMBER=$(gcloud projects describe PROJECT_ID --format="value(projectNumber)")

gcloud projects add-iam-policy-binding PROJECT_ID \
  --role=roles/telemetry.writer \
  --member=principal://iam.googleapis.com/projects/$PROJECT_NUMBER/locations/global/workloadIdentityPools/PROJECT_ID.svc.id.goog/subject/ns/opentelemetry/sa/opentelemetry-collector \
  --condition=None

gcloud projects add-iam-policy-binding PROJECT_ID \
  --role=roles/serviceusage.serviceUsageConsumer \
  --member=principal://iam.googleapis.com/projects/$PROJECT_NUMBER/locations/global/workloadIdentityPools/PROJECT_ID.svc.id.goog/subject/ns/opentelemetry/sa/opentelemetry-collector \
  --condition=None

Cuenta de servicio para la federación de identidades para cargas de trabajo para GKE

Si configuraste una cuenta de servicio para la federación de identidades para cargas de trabajo para GKE, puedes usar el comando en la documentación de Google Cloud Managed Service para Prometheus para autorizar la cuenta de servicio, con los siguientes cambios:

  • Reemplaza gmp-test-sa por el nombre de tu cuenta de servicio.
  • Ejecuta el comando para otorgar las funciones necesarias para escribir datos de registro, métricas y seguimientos.

Otra cuenta de servicio

Si ejecutas el recopilador en una VM de Compute Engine o fuera de GKE, otorga las funciones necesarias a la Google Cloud cuenta de servicio que usa tu implementación.

Configura la variable de entorno GOOGLE_CLOUD_PROJECT

Configura la variable de entorno GOOGLE_CLOUD_PROJECT en la implementación de tu recopilador. El resultado se parece al siguiente:

env:
- name: GOOGLE_CLOUD_PROJECT
  value: PROJECT_ID

Agrega la extensión googleclientauth

Agrega la extensión googleclientauth a la configuración de tu recopilador. La API de Telemetry es una API de consumidor y requiere que especifiques tanto tu Google Cloud proyecto como tu proyecto de cuota. El resultado es similar al siguiente:

extensions:
  googleclientauth:
    project: ${GOOGLE_CLOUD_PROJECT}
    quota_project: ${GOOGLE_CLOUD_PROJECT}

Agrega los exportadores otlphttp y otlp_grpc/otlp_logs

Usa el exportador otlphttp para enviar datos de métricas y seguimientos con formato OTLP a tu proyecto, y usa el exportador otlp_grpc/otlp_logs para enviar datos de registro. Asegúrate de configurar ambos exportadores con la extensión googleclientauth.

El resultado es similar al siguiente:

exporters:
  # ... existing content ...
  otlphttp:
    encoding: proto
    endpoint: https://telemetry.googleapis.com
    auth:
      authenticator: googleclientauth
  otlp_grpc/otlp_logs:
    auth:
      authenticator: googleclientauth
    balancer_name: pick_first
    endpoint: telemetry.googleapis.com:443

Para el exportador otlp_grpc/otlp_logs, el campo endpoint debe especificarse con el formato host:port.

Agrega procesadores

En esta sección, se enumeran los procesadores que debes agregar a tu recopilador. Hay otros procesadores que quizás quieras usar. Por ejemplo, las configuraciones del recopilador de OpenTelemetry integrado en Google suelen incluir el procesador memory_limiter y uno que transforma los datos de métricas. Para ver un ejemplo, consulta Recopilador de OpenTelemetry integrado en Google en GKE.

Agrega el procesador resource/gcp_project_id

Agrega un resource procesador que capture información sobre tu Google Cloud proyecto.

  resource/gcp_project_id:
    attributes:
      - action: insert
        value: ${GOOGLE_CLOUD_PROJECT}
        key: gcp.project_id

Agrega el procesador resourcedetection

Si ejecutas en Google Cloud, considera agregar el resourcedetection procesador. Este procesador puede descubrir automáticamente información sobre tu arquitectura.

La siguiente configuración busca las variables de entorno estándar de OpenTelemetry y, luego, consulta el Google Cloud servidor de metadatos para recopilar información sobre tu infraestructura:

  resourcedetection:
    detectors: ["env", "gcp"]

Agrega el procesador batch

Para enviar tu telemetría a tu Google Cloud proyecto de manera más eficiente, te recomendamos que uses el batch procesador.

Por ejemplo, el recopilador de OpenTelemetry integrado en Google usa la siguiente configuración para el procesador por lotes:

batch:
  send_batch_max_size: 200
  send_batch_size: 200
  timeout: 5s

Agrega el procesador metricstarttime

Agrega el procesador metricstarttime a la configuración. Este procesador se asegura de que las métricas acumulativas incluyan una hora de inicio y una hora de observación. De forma predeterminada, las métricas de Prometheus solo incluyen una hora actual. Por lo tanto, si omites este procesador y tu aplicación genera métricas de Prometheus, es posible que se rechacen tus datos de métricas o que veas picos de datos.

Debes agregar este procesador si tu recopilador recibe métricas de Prometheus.

processors:
  # This processor ensures the start time is set for Prometheus metrics.
  # Set in the pipeline before the k8sattributes processor, if used.
  # No-op for OTLP metrics.
  metricstarttime:
    strategy: subtract_initial_point

Agrega el procesador de transformación

Para preservar la fuente y la versión de la instrumentación en tus datos de registro, agrega el siguiente procesador transform:

  transform/otlp_grpc/preserve_instrumentation_source_version:
    error_mode: ignore
    log_statements:
      - context: log
        statements:
          - set(attributes["instrumentation_source"], instrumentation_scope.name) where instrumentation_scope.name != ""
          - set(attributes["instrumentation_version"], instrumentation_scope.version) where instrumentation_scope.version != ""
          - set(attributes["service.name"], resource.attributes["service.name"]) where resource.attributes["service.name"] != nil
          - set(attributes["service.namespace"], resource.attributes["service.namespace"]) where resource.attributes["service.namespace"] != nil
          - set(attributes["service.instance.id"], resource.attributes["service.instance.id"]) where resource.attributes["service.instance.id"] != nil

Actualiza las canalizaciones de servicio

A continuación, actualiza las canalizaciones de tu recopilador para usar los exportadores otlp_grpc/otlp_logs y otlphttp. Para los datos de registro y seguimientos, estas instrucciones reemplazan tu exportador actual por el exportador de OTLP adecuado. Para tus datos de métricas, estas instrucciones generan escrituras dobles. Este enfoque te permite verificar que el exportador de OTLP esté enviando datos de métricas a tu Google Cloud proyecto. También te permite actualizar los gráficos y las políticas de alertas antes de desactivar las transmisiones de datos del exportador original.

Realiza los siguientes cambios en las configuraciones de canalización de tu recopilador:

  1. Agrega la extensión googleclientauth a la entrada service.
  2. Para tu canalización de registros, reemplaza googlecloud/logging por otlp_grpc/otlp_logs y, luego, agrega los siguientes procesadores a la lista de procesadores de la canalización:

    • resource/gcp_project_id
    • transform/otlp_grpc/preserve_instrumentation_source_version
    • resourcedetection (si agregaste este procesador)
    • batch

    Esta configuración realiza una sola escritura de datos de registro. Si deseas escribir tus datos de registro de forma doble, agrega el exportador otlp_grpc/otlp_logs a la lista de exportadores.

  3. Para tu canalización de métricas, agrega el exportador otlphttp a la lista de exportadores de la canalización junto con el exportador googlemanagedprometheus y, luego, agrega los siguientes procesadores:

    • resource/gcp_project_id
    • metricstarttime
    • resourcedetection (si agregaste este procesador)
    • batch

    Esta configuración realiza una escritura doble de datos de métricas. Después de validar el flujo de datos de métricas y actualizar los gráficos y las políticas de alertas, quita el exportador de Prometheus.

  4. Para tu canalización de seguimientos, reemplaza tu exportador actual por el exportador otlphttp y, luego, agrega los siguientes procesadores:

    • resource/gcp_project_id
    • resourcedetection (si agregaste este procesador)
    • batch

    Esta configuración realiza una sola escritura de datos de seguimientos.

El resultado de estos cambios es similar al siguiente:

service:
  extensions: ["googleclientauth"]
  pipelines:
    logs:
      receivers: ["otlp"]
      processors:
        - resourcedetection
        - resource/gcp_project_id
        - transform/otlp_grpc/preserve_instrumentation_source_version
        - batch
      exporters: ["otlp_grpc/otlp_logs"]
    metrics:
      receivers: ["otlp"]
      processors:
        - resourcedetection
        - resource/gcp_project_id
        - metricstarttime
        - batch
      exporters: ["googlemanagedprometheus", "otlphttp"]
    traces:
      receivers: ["otlp"]
      processors:
        - resourcedetection
        - resource/gcp_project_id
        - batch
      exporters: ["otlphttp"]

El fragmento anterior usa el receptor OTLP para tus datos de registro, métricas y seguimientos. La configuración de tu recopilador puede ser diferente. Por ejemplo, si tienes una aplicación que escribe datos de registro estructurados, el receptor filelog es adecuado.

Valida tu configuración

Reinicia tu implementación y, luego, verifica que tus otlphttp y otlp_grpc/otlp_logs exportadores envíen datos a tu Google Cloud proyecto. Para verificar tu configuración, haz lo siguiente:

  • Consulta tus entradas de registro para ver si hay errores relacionados con la escritura de datos de telemetría.
  • Consulta las tasas de error de la API de Cloud Logging, la API de Cloud Monitoring y la API de Telemetry.
  • Visualiza series temporales con el Explorador de métricas.

Migra los paneles y las políticas de alertas

Actualiza tus gráficos y paneles de la siguiente manera:

  1. Si supervisas el uso de la API de Cloud Logging o la API de Cloud Monitoring con gráficos o políticas de alertas, crea gráficos o políticas de alertas adicionales para supervisar el uso de la API de Telemetry.

  2. Si los receptores de métricas incluyen un receptor otlp o si tu recopilador extrae métricas de Prometheus con caracteres UTF-8, actualiza tus gráficos y paneles. El exportador otlphttp genera métricas diferentes del exportador googlemanagedprometheus. Para obtener más información, consulta Diferencias en el formato de las métricas exportadas.

    No es necesario que actualices tus gráficos y paneles si tu recopilador solo recibe datos de métricas de Prometheus.

  3. Si tus canalizaciones de métricas incluyen un prometheus receptor, se producirán colisiones de transmisión de datos entre las métricas generadas por los otlphttp y googlemanagedprometheus exportadores. Para resolver estas colisiones, quita el googlemanagedprometheus exportador.

Diferencias en el formato de las métricas exportadas

Las actualizaciones de los gráficos basados en métricas y las políticas de alertas son necesarias debido a las siguientes diferencias entre las métricas exportadas por los exportadores de OTLP y googlemanagedprometheus:

  • La API de Telemetry permite los caracteres de punto (.) y barra (/) con en los nombres de las métricas. El exportador googlemanagedprometheus convierte todas las instancias de estos caracteres en el carácter de guion bajo (_). Por ejemplo, el exportador de OTLP exporta una métrica de OTLP llamada prometheus.googleapis.com/foo.bar/gauge de forma literal, pero el exportador googlemanagedprometheus la exporta como prometheus.googleapis.com/foo_bar/gauge.

    Cuando se transfieren las métricas, Cloud Monitoring crea descriptores de métricas basados en los nombres. La diferencia en la forma en que las rutas de transferencia controlan los caracteres de punto (.) y barra (/) significa que los descriptores de métricas resultantes difieren entre las métricas transferidas con el exportador googlemanagedprometheus y las transferidas con el otlphttp exportador. Si usas ambas rutas de transferencia, tendrás dos conjuntos de métricas. Para obtener resultados completos cuando realices consultas, debes unir manualmente los resultados de las versiones de Prometheus y OTLP de las métricas.

  • La API de Telemetry no agrega una unidad a un nombre de métrica cuando hay una unidad presente y no agrega un sufijo _total a los contadores. Por lo tanto, el exportador googlemanagedprometheus exporta una métrica como prometheus.googleapis.com/foo/counter cuando se usa la API de Telemetry como prometheus.googleapis.com/foo_seconds_total/counter. Esta diferencia también se aplica a los sufijos _total y _ratio.

Para obtener más información sobre las diferencias entre las métricas, consulta Diferencias entre el exportador googlemanagedprometheus y la API de Telemetry.

Las reglas de transformación no se aplican a las métricas con caracteres UTF-8. Por lo tanto, debes volver a escribir tus paneles y políticas de alertas para usar los nombres de métricas nuevos o usar consultas que combinen los nombres de métricas antiguos y nuevos. No recomendamos escribir reglas de procesador para volver a crear estas transformaciones para seguir escribiendo métricas UTF-8 como si las recopilara el exportador googlemanagedprometheus. Si lo haces, se conserva la retrocompatibilidad, pero se sacrifica la compatibilidad con versiones posteriores y no podrás usar los recursos de código abierto que hacen referencia a los nombres de métricas UTF-8.

Quita los exportadores específicos del proveedor

Después de validar las nuevas transmisiones de datos y actualizar tus paneles y políticas de alertas, quita los exportadores googlecloud/logging y googlemanagedprometheus de la configuración de tu recopilador. Es posible que también debas quitar los procesadores que solo usaban los exportadores que se quitaron de la configuración.

Debes actualizar la lista de exportadores y las canalizaciones de servicio.

exporters:
  otlphttp: [...]
  otlp_grpc/otlp_logs: [...]

...
service:
  extensions: ["googleclientauth"]
  pipelines:
    logs:
      receivers: ["otlp"]
      processors: [...]
      exporters: ["otlp_grpc/otlp_logs"]
    metrics:
      receivers: ["otlp"]
      processors: [...]
      exporters: ["otlphttp"]
    traces:
      receivers: ["otlp"]
      processors: [...]
      exporters: ["otlphttp"]

Soluciona problemas

En esta sección, se describe cómo resolver las fallas que pueden ocurrir cuando migras la configuración de tu recopilador.

Faltan datos de métricas o picos en los datos de métricas

Si faltan tus datos de métricas o contienen picos, verifica que hayas agregado el procesador metricstarttime a la configuración del recopilador. Para obtener más información, consulta Agrega el procesador metricstarttime.

También puedes revisar los registros del recopilador, los registros del sistema y los registros de auditoría de acceso a datos de Monitoring. Por ejemplo, si falla una escritura en una serie temporal, se genera un registro de auditoría de acceso a datos que incluye el motivo de la falla.

Mensajes de error sobre la escritura de series temporales

El sistema genera mensajes de error cuando falla un intento de escribir datos en una serie temporal. Puedes usar estos mensajes para comprender por qué falló la escritura y cómo resolver el problema.

  • Mensaje de error que indica una falta de coincidencia de valores:

    "One or more TimeSeries could not be written: Value type DOUBLE does not match metric descriptor value type INT64."
    

    Este error se produce si enviaste métricas INT64 target_info anteriormente porque la API de Telemetry establece el tipo de valor de todas las métricas en DOUBLE. La mejor solución a largo plazo es borrar el descriptor de métrica para las métricas INT64 target_info. Para borrar este descriptor de tu permiso de métricas, usa esta secuencia de comandos de Golang.

  • Mensaje de error que indica que varias fuentes escriben datos de series temporales:

    "One or more TimeSeries could not be written: Points must be written in order. One or more of the points specified had an older end time than the most recent point."
    

    Para resolver este problema, quita el exportador googlemanagedprometheus de la configuración de tu recopilador. Para obtener más información, consulta Quita los exportadores específicos del proveedor.

¿Qué sigue?