Migra al exportador de OTLP

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

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

Habilita la API de Telemetry

El exportador otlphttp escribe 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 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. Estos comandos suponen que usas Workload Identity Federation 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 en 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 la función 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 ve de la siguiente manera:

env:
- name: PROJECT_ID
  value: PROJECT_ID

Ubica el exportador que se reemplazará

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

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

Agrega configuración para el exportador 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 ningún problema porque la estructura de los descriptores de métricas creados por los dos métodos difiere. Son métricas separadas.
  • Si usas métricas de Prometheus, verás colisiones hasta que quites el exportador googlemanagedpromethus.

La configuración actualizada se ve de la siguiente manera. Asegúrate de configurar el procesador metricstarttime durante la migración:

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 nombres de métricas nuevos que genera el exportador otlphttp. El exportador otlphttp no cambia el nombre de las métricas para que sean "estilo Prometheus" con reemplazos de guion bajo.

Quita la configuración del exportador anterior

Después de actualizar tus paneles y alertas para hacer referencia a las métricas exportadas por 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 paneles y políticas de alertas, si es necesario

Si usaste el exportador googlemanagedprometheus solo para 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 recopilaste métricas de Prometheus con caracteres UTF-8, debes actualizar tus paneles y alertas para usar el nombre de 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 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.

Debido a 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 unir los nombres de métricas antiguos y nuevos.

No recomendamos escribir reglas de procesador para volver a crear estas transformaciones y 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 fácilmente los recursos de código abierto que hacen referencia a los nombres de métricas UTF-8.