Migra al exportador de OTLP

Esta función está con sujeción a las "Condiciones de las Ofertas de la Fase Previa a la DG" de la sección Términos Generales del Servicio de los Términos Específicos del Servicio. Las funciones de la fase previa a la DG están disponibles sin modificaciones y pueden tener asistencia limitada. Para obtener más información, consulta las descripciones de la etapa de lanzamiento.

En este documento, se describe cómo modificar una configuración del recopilador de OpenTelemetry que usa un exportador existente (en este caso, el exportador googlemanagedprometheus) para usar el exportador otlphttp y la API de Telemetría (OTLP), telemetry.googleapis.com.

OTLP para las métricas de Prometheus solo funciona cuando se usa la versión 0.140.0 o posterior del recopilador de OpenTelemetry.

Habilita la API de Telemetry

El exportador de otlphttp escribe en la API de Telemetry, por lo que esa API debe estar habilitada en tu proyecto. Habilita la API de Telemetry ejecutando el siguiente comando:

gcloud services enable telemetry.googleapis.com

Autoriza la cuenta de servicio de Kubernetes

La cuenta de servicio de Kubernetes debe tener permiso para usar la API de Telemetry. Los siguientes comandos otorgan el rol de Identity and Access Management (IAM) necesario a la cuenta de servicio de Kubernetes. En estos comandos, se supone que usas la federación de identidades para cargas de trabajo para GKE:

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

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

Reemplaza la variable PROJECT_ID por el ID de tu Google Cloud proyecto.

Si tu cuenta de servicio tiene un formato diferente, puedes usar el comando de la documentación de Google Cloud Managed Service para Prometheus para autorizar la cuenta de servicio con los siguientes cambios:

• Reemplaza el nombre de la cuenta de servicio gmp-test-sa por tu cuenta de servicio.
• Ejecuta el comando para otorgar el rol de roles/telemetry.metricsWriter.

Configura la variable de entorno PROJECT_ID.

Configura la variable de entorno PROJECT_ID en la implementación del recopilador. El resultado se verá de la siguiente manera:

env:
- name: PROJECT_ID
  value: PROJECT_ID

Busca el exportador que se reemplazará

En tu archivo de configuración, busca el exportador y el servicio que lo usa:

exporters:
  googlemanagedprometheus:
service:
  pipelines:
    metrics:
      exporters: [googlemanagedprometheus]

Agrega la configuración para el exportador de otlphttp

En este paso, agregarás el exportador otlphttp y el procesador metricstarttime a la configuración. Este exportador adicional hace que el recopilador escriba las métricas dos veces.

• Si usas métricas nativas de OTLP, la escritura doble no causa problemas porque la estructura de los descriptores de métricas creados por los dos métodos difiere. Son métricas independientes.
• Si usas métricas de Prometheus, verás colisiones hasta que quites el exportador de googlemanagedpromethus.

La configuración actualizada se verá de la siguiente manera:

exporters:
  googlemanagedprometheus:
  otlphttp:
    encoding: json
    endpoint: https://telemetry.googleapis.com
    auth:
      authenticator: googleclientauth
processors:
  # This processor ensures the start time is set for Prometheus metrics. This must be set in the pipeline before the k8sattributes processor, if used.
  metricstarttime:
    strategy: subtract_initial_point
  resource/gcp_project_id:
    attributes:
    - action: insert
      # Make sure you set the PROJECT_ID environment variable.
      value: ${PROJECT_ID}
      key: gcp.project_id
extensions:
  googleclientauth:
service:
  extensions: [googleclientauth]
  pipelines:
    metrics:
      processors: [resource/gcp_project_id, metricstarttime]
      exporters: [googlemanagedprometheus, otlphttp]

Después de escribir tus métricas dos veces, actualiza tus paneles y políticas de alertas para usar los nuevos nombres de métricas que genera el exportador de otlphttp. El exportador de otlphttp no cambia el nombre de las métricas para que sean "al estilo de Prometheus" con reemplazos de guiones bajos.

Nota: Debido a que la API de Telemetry establece el tipo de valor de todas las métricas en DOUBLE, es posible que haya colisiones de tipos de valores, en especial si anteriormente enviaste métricas de INT64 target_info. Si encuentras colisiones, la mejor solución a largo plazo es que borres el descriptor de métrica para las métricas de INT64 target_info. Para borrar este descriptor de tu permiso de métricas, usa esta secuencia de comandos de Golang.

Quita la configuración del exportador anterior

Después de actualizar tus paneles y alertas para que hagan referencia a las métricas exportadas con otlphttp, quita el exportador anterior, googlemanagedprometheus en este caso, de la configuración. La configuración revisada se ve de la siguiente manera:

exporters:
  otlphttp:
    encoding: json
    endpoint: https://telemetry.googleapis.com
    auth:
      authenticator: googleclientauth
processors:
  # This processor ensures the start time is set for Prometheus metrics. This must be set in the pipeline before the k8sattributes processor, if used.
  metricstarttime:
    strategy: subtract_initial_point
  resource/gcp_project_id:
    attributes:
    - action: insert
      # Make sure you set the PROJECT_ID environment variable.
      value: ${PROJECT_ID}
      key: gcp.project_id
extensions:
  googleclientauth:
service:
  extensions: [googleclientauth]
  pipelines:
    metrics:
      processors: [resource/gcp_project_id, metricstarttime]
      exporters: [otlphttp]

Migra los paneles y las políticas de alertas, si es necesario

Si usaste el exportador de googlemanagedprometheus solo para los datos de métricas de Prometheus, cuando cambies al exportador de OTLP, tus paneles y políticas de alertas existentes seguirán funcionando.

Sin embargo, si usaste el exportador googlemanagedprometheus para recopilar y enviar datos que se emitieron originalmente con OTLP, o si recuperaste métricas de Prometheus con caracteres UTF-8, debes actualizar tus paneles y alertas para que usen el nombre de la métrica UTF-8.

Esto se debe a las siguientes diferencias entre las métricas exportadas con OTLP y las métricas exportadas con el exportador de googlemanagedprometheus:

• La API de Telemetry permite usar los caracteres de punto (.) y barra diagonal (/) en los nombres de las métricas. El exportador de googlemanagedprometheus convierte todas las instancias de estos caracteres en el carácter de guion bajo (_). Por ejemplo, el exportador de OTLP exporta literalmente una métrica de OTLP llamada prometheus.googleapis.com/foo.bar/gauge, pero el exportador de 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 acceso a la 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 exportador otlphttp. Si usas ambas rutas de acceso de transferencia, tendrás dos conjuntos de métricas. Para obtener resultados completos cuando realices consultas, deberás unir manualmente los resultados de las versiones de Prometheus y OTLP de las métricas.

• La API de Telemetry no agrega una unidad al nombre de una métrica cuando hay una unidad presente, y no agrega un sufijo _total a los contadores. Por lo tanto, una métrica exportada como prometheus.googleapis.com/foo/counter cuando se usa la API de Telemetry se exporta como prometheus.googleapis.com/foo_seconds_total/counter con el exportador googlemanagedprometheus. 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 de googlemanagedprometheus y la API de Telemetry.

Dado que las reglas de transformación no se aplican a las métricas con caracteres UTF-8, debes volver a escribir tus paneles y políticas de alertas para usar los nombres de métricas nuevos o para unir los nombres de métricas antiguos y nuevos.

No recomendamos escribir reglas del procesador para recrear estas transformaciones y seguir escribiendo métricas UTF-8 como si las recopilara el exportador googlemanagedprometheus. Si lo haces, se conservará la retrocompatibilidad, pero se sacrificará la compatibilidad con versiones posteriores y no podrás usar fácilmente los recursos de código abierto que hacen referencia a los nombres de las métricas en UTF-8.