Empezar a usar el recopilador de OpenTelemetry

En este documento se describe cómo configurar OpenTelemetry Collector para recoger métricas estándar de Prometheus y enviarlas a Google Cloud Managed Service para Prometheus. OpenTelemetry Collector es un agente que puedes desplegar y configurar para exportar datos a Managed Service para Prometheus. La configuración es similar a la de Managed Service para Prometheus con la recogida autodesplegada.

Puede elegir OpenTelemetry Collector en lugar de la recogida con despliegue automático por los siguientes motivos:

• El Collector de OpenTelemetry te permite enrutar tus datos de telemetría a varios back-ends configurando diferentes exportadores en tu canal.
• El Collector también admite señales de métricas, registros y trazas, por lo que, si lo usas, puedes gestionar los tres tipos de señales en un solo agente.
• El formato de datos independiente del proveedor de OpenTelemetry (el protocolo OpenTelemetry u OTLP) admite un ecosistema sólido de bibliotecas y componentes de Collector conectables. Esto permite una amplia gama de opciones de personalización para recibir, procesar y exportar tus datos.

La contrapartida de estas ventajas es que, para ejecutar un OpenTelemetry Collector, se necesita un enfoque de despliegue y mantenimiento autogestionado. El enfoque que elijas dependerá de tus necesidades específicas, pero en este documento te ofrecemos directrices recomendadas para configurar OpenTelemetry Collector con Managed Service para Prometheus como backend.

Antes de empezar

En esta sección se describe la configuración necesaria para las tareas que se indican en este documento.

Configurar proyectos y herramientas

Para usar Google Cloud Managed Service para Prometheus, necesitas los siguientes recursos:

• Un Google Cloud proyecto con la API de Cloud Monitoring habilitada.

  • Si no tienes ningún Google Cloud proyecto, haz lo siguiente:

    1. En la Google Cloud consola, ve a Nuevo proyecto:

       Crear un proyecto

    2. En el campo Nombre del proyecto, escribe el nombre que quieras darle al proyecto y, a continuación, haz clic en Crear.

    3. Ve a Facturación:

       Ir a Facturación

    4. Selecciona el proyecto que acabas de crear si aún no está seleccionado en la parte superior de la página.

    5. Se te pedirá que elijas un perfil de pagos o que crees uno.

    La API Monitoring está habilitada de forma predeterminada en los proyectos nuevos.

  • Si ya tienes un Google Cloud proyecto, asegúrate de que la API Monitoring esté habilitada:

    1. Vaya a APIs y servicios:

       Ve a APIs y servicios.

    2. Selecciona el proyecto.

    3. Haz clic en Habilitar APIs y servicios.

    4. Busca "Monitorización".

    5. En los resultados de búsqueda, haz clic en "API Cloud Monitoring".

    6. Si no se muestra "API habilitada", haz clic en el botón Habilitar.

• Un clúster de Kubernetes. Si no tienes un clúster de Kubernetes, sigue las instrucciones de la guía de inicio rápido de GKE.

También necesitas las siguientes herramientas de línea de comandos:

• gcloud
• kubectl

Las herramientas gcloud y kubectl forman parte de Google Cloud CLI. Para obtener información sobre cómo instalarlos, consulta Gestionar componentes de Google Cloud CLI. Para ver los componentes de la CLI de gcloud que tienes instalados, ejecuta el siguiente comando:

gcloud components list

Configurar el entorno

Para no tener que introducir repetidamente el ID del proyecto o el nombre del clúster, haz la siguiente configuración:

• Configura las herramientas de línea de comandos de la siguiente manera:

  • Configura gcloud CLI para que haga referencia al ID de tu proyectoGoogle Cloud :

    gcloud config set project PROJECT_ID
    

  • Configura la CLI de kubectl para que use tu clúster:

    kubectl config set-cluster CLUSTER_NAME
    

  Para obtener más información sobre estas herramientas, consulta los siguientes artículos:

  • Información general sobre la CLI de gcloud
  • Comandos de kubectl

Configurar un espacio de nombres

Crea el espacio de nombres de Kubernetes NAMESPACE_NAME para los recursos que crees como parte de la aplicación de ejemplo:

kubectl create ns NAMESPACE_NAME

Verificar las credenciales de la cuenta de servicio

Si tu clúster de Kubernetes tiene habilitada la federación de identidades de carga de trabajo para GKE, puedes saltarte esta sección.

Cuando se ejecuta en GKE, Managed Service para Prometheus obtiene automáticamente las credenciales del entorno en función de la cuenta de servicio predeterminada de Compute Engine. La cuenta de servicio predeterminada tiene los permisos necesarios, monitoring.metricWriter y monitoring.viewer, de forma predeterminada. Si no usas Workload Identity Federation para GKE y has quitado alguno de esos roles de la cuenta de servicio de nodo predeterminada, tendrás que volver a añadir los permisos que faltan antes de continuar.

Configurar una cuenta de servicio para Workload Identity Federation for GKE

Si tu clúster de Kubernetes no tiene habilitada la federación de identidades de carga de trabajo para GKE, puedes saltarte esta sección.

Managed Service para Prometheus captura datos de métricas mediante la API de Cloud Monitoring. Si tu clúster usa la federación de Workload Identity para GKE, debes conceder permiso a tu cuenta de servicio de Kubernetes para usar la API Monitoring. En esta sección se describe lo siguiente:

• Crear una Google Cloud cuenta de servicio gmp-test-sa.
• Asociar la cuenta de servicio Google Cloud a la cuenta de servicio de Kubernetes predeterminada en un espacio de nombres de prueba. NAMESPACE_NAME
• Conceder el permiso necesario a la cuenta de servicio Google Cloud .

Crear y vincular la cuenta de servicio

Este paso aparece en varios lugares de la documentación de Managed Service para Prometheus. Si ya has completado este paso en una tarea anterior, no tienes que repetirlo. Vaya a la sección Autorizar la cuenta de servicio.

La siguiente secuencia de comandos crea la cuenta de servicio gmp-test-sa y la vincula a la cuenta de servicio predeterminada de Kubernetes en el espacio de nombres NAMESPACE_NAME:

gcloud config set project PROJECT_ID \
&&
gcloud iam service-accounts create gmp-test-sa \
&&
gcloud iam service-accounts add-iam-policy-binding \
  --role roles/iam.workloadIdentityUser \
  --member "serviceAccount:PROJECT_ID.svc.id.goog[NAMESPACE_NAME/default]" \
  gmp-test-sa@PROJECT_ID.iam.gserviceaccount.com \
&&
kubectl annotate serviceaccount \
  --namespace NAMESPACE_NAME \
  default \
  iam.gke.io/gcp-service-account=gmp-test-sa@PROJECT_ID.iam.gserviceaccount.com

Si usas un espacio de nombres o una cuenta de servicio de GKE diferentes, ajusta los comandos según corresponda.

Autorizar la cuenta de servicio

Los grupos de permisos relacionados se recogen en roles, y tú asignas los roles a una entidad principal, en este ejemplo, la Google Cloudcuenta de servicio. Para obtener más información sobre los roles de Monitoring, consulta Control de acceso.

El siguiente comando concede a la cuenta de servicio Google Cloud , gmp-test-sa, los roles de la API Monitoring que necesita para escribir datos de métricas.

Si ya has concedido un rol específico a la Google Cloud cuenta de servicio como parte de una tarea anterior, no es necesario que lo hagas de nuevo.

gcloud projects add-iam-policy-binding PROJECT_ID\
  --member=serviceAccount:gmp-test-sa@PROJECT_ID.iam.gserviceaccount.com \
  --role=roles/monitoring.metricWriter

Depurar la configuración de Workload Identity Federation para GKE

Si tienes problemas para que funcione Workload Identity Federation para GKE, consulta la documentación sobre cómo verificar la configuración de Workload Identity Federation para GKE y la guía para solucionar problemas de Workload Identity Federation para GKE.

Como las erratas y las acciones de copiar y pegar parciales son las fuentes de errores más habituales al configurar la federación de identidades de carga de trabajo para GKE, te recomendamos encarecidamente que uses las variables editables y los iconos de copiar y pegar en los que se puede hacer clic que se incluyen en los ejemplos de código de estas instrucciones.

Workload Identity Federation para GKE en entornos de producción

En el ejemplo que se describe en este documento, se vincula la Google Cloud cuenta de servicio Google Clouda la cuenta de servicio predeterminada de Kubernetes y se le otorgan todos los permisos necesarios para usar la API Monitoring.

En un entorno de producción, puede que quieras usar un enfoque más detallado, con una cuenta de servicio para cada componente, cada una con permisos mínimos. Para obtener más información sobre cómo configurar cuentas de servicio para la gestión de identidades de cargas de trabajo, consulta Usar Workload Identity Federation para GKE.

Configurar el recopilador de OpenTelemetry

En esta sección se explica cómo configurar y usar OpenTelemetry Collector para obtener métricas de una aplicación de ejemplo y enviar los datos a Google Cloud Managed Service para Prometheus. Para obtener información detallada sobre la configuración, consulta las siguientes secciones:

• Recoger métricas de Prometheus
• Añadir procesadores
• Configurar el exportador googlemanagedprometheus

OpenTelemetry Collector es análogo al binario del agente de Managed Service para Prometheus. La comunidad de OpenTelemetry publica periódicamente versiones, que incluyen código fuente, archivos binarios e imágenes de contenedores.

Puedes implementar estos artefactos en máquinas virtuales o clústeres de Kubernetes con los valores predeterminados recomendados, o bien usar collector builder para crear tu propio recolector con los componentes que necesites. Para crear un recopilador que se pueda usar con Managed Service para Prometheus, necesitas los siguientes componentes:

• El exportador de Managed Service para Prometheus, que escribe tus métricas en Managed Service para Prometheus.
• Un receptor para raspar tus métricas. En este documento se da por hecho que usas el receptor Prometheus de OpenTelemetry, pero el exportador de Managed Service para Prometheus es compatible con cualquier receptor de métricas de OpenTelemetry.
• Procesadores para agrupar y marcar tus métricas con el fin de incluir identificadores de recursos importantes en función de tu entorno.

Estos componentes se habilitan mediante un archivo de configuración que se transfiere al Collector con la marca --config.

En las siguientes secciones se explica cómo configurar cada uno de estos componentes con más detalle. En este documento se describe cómo ejecutar el recolector en GKE y en otros lugares.

Configurar e implementar el recopilador

Tanto si ejecutas tu recogida en Google Cloud como en otro entorno, puedes configurar OpenTelemetry Collector para que exporte datos a Managed Service para Prometheus. La mayor diferencia será la forma de configurar el recolector. En entornos que no sean deGoogle Cloud , es posible que se necesite un formato adicional de los datos de métricas para que sean compatibles con Managed Service para Prometheus. Sin embargo, en Google Cloud, el Collector puede detectar automáticamente gran parte de este formato.

Ejecutar el OpenTelemetry Collector en GKE

Puedes copiar la siguiente configuración en un archivo llamado config.yaml para configurar el OpenTelemetry Collector en GKE:

receivers:
  prometheus:
    config:
      scrape_configs:
      - job_name: 'SCRAPE_JOB_NAME'
        kubernetes_sd_configs:
        - role: pod
        relabel_configs:
        - source_labels: [__meta_kubernetes_pod_label_app_kubernetes_io_name]
          action: keep
          regex: prom-example
        - source_labels: [__meta_kubernetes_pod_annotation_prometheus_io_path]
          action: replace
          target_label: __metrics_path__
          regex: (.+)
        - source_labels: [__address__, __meta_kubernetes_pod_annotation_prometheus_io_port]
          action: replace
          regex: (.+):(?:\d+);(\d+)
          replacement: $$1:$$2
          target_label: __address__
        - action: labelmap
          regex: __meta_kubernetes_pod_label_(.+)

processors:
  resourcedetection:
    detectors: [gcp]
    timeout: 10s

  transform:
    # "location", "cluster", "namespace", "job", "instance", and "project_id" are reserved, and
    # metrics containing these labels will be rejected.  Prefix them with exported_ to prevent this.
    metric_statements:
    - context: datapoint
      statements:
      - set(attributes["exported_location"], attributes["location"])
      - delete_key(attributes, "location")
      - set(attributes["exported_cluster"], attributes["cluster"])
      - delete_key(attributes, "cluster")
      - set(attributes["exported_namespace"], attributes["namespace"])
      - delete_key(attributes, "namespace")
      - set(attributes["exported_job"], attributes["job"])
      - delete_key(attributes, "job")
      - set(attributes["exported_instance"], attributes["instance"])
      - delete_key(attributes, "instance")
      - set(attributes["exported_project_id"], attributes["project_id"])
      - delete_key(attributes, "project_id")

  batch:
    # batch metrics before sending to reduce API usage
    send_batch_max_size: 200
    send_batch_size: 200
    timeout: 5s

  memory_limiter:
    # drop metrics if memory usage gets too high
    check_interval: 1s
    limit_percentage: 65
    spike_limit_percentage: 20

# Note that the googlemanagedprometheus exporter block is intentionally blank
exporters:
  googlemanagedprometheus:

service:
  pipelines:
    metrics:
      receivers: [prometheus]
      processors: [batch, memory_limiter, resourcedetection, transform]
      exporters: [googlemanagedprometheus]

La configuración anterior usa el receptor de Prometheus y el exportador de Managed Service para Prometheus para obtener los endpoints de métricas de los pods de Kubernetes y exportar esas métricas a Managed Service para Prometheus. Los procesadores de la canalización dan formato a los datos y los agrupan en lotes.

Para obtener más información sobre la función de cada parte de esta configuración, así como sobre las configuraciones de diferentes plataformas, consulta las secciones detalladas sobre métricas de raspado y adición de procesadores.

Cuando se usa una configuración de Prometheus con el receptor prometheus del OpenTelemetry Collector, sustituya los caracteres de signo de dólar único, , por caracteres dobles, , para evitar que se active la sustitución de variables de entorno. Para obtener más información, consulta Recoger métricas de Prometheus.

Puedes modificar esta configuración en función de tu entorno, proveedor y las métricas que quieras obtener, pero la configuración de ejemplo es un punto de partida recomendado para ejecutar en GKE.

Ejecutar el Collector de OpenTelemetry fuera Google Cloud

Ejecutar el Collector de OpenTelemetry fuera de Google Cloud, como en un entorno local o en otros proveedores de servicios en la nube, es similar a ejecutarlo en GKE. Sin embargo, es menos probable que las métricas que obtengas incluyan automáticamente datos que se adapten al formato de Managed Service para Prometheus. Por lo tanto, debes tener especial cuidado al configurar el recopilador para que dé formato a las métricas de forma que sean compatibles con Managed Service para Prometheus.

Puedes usar la siguiente configuración en un archivo llamado config.yaml para configurar el OpenTelemetry Collector para el despliegue en un clúster de Kubernetes que no sea de GKE:

receivers:
  prometheus:
    config:
      scrape_configs:
      - job_name: 'SCRAPE_JOB_NAME'
        kubernetes_sd_configs:
        - role: pod
        relabel_configs:
        - source_labels: [__meta_kubernetes_pod_label_app_kubernetes_io_name]
          action: keep
          regex: prom-example
        - source_labels: [__meta_kubernetes_pod_annotation_prometheus_io_path]
          action: replace
          target_label: __metrics_path__
          regex: (.+)
        - source_labels: [__address__, __meta_kubernetes_pod_annotation_prometheus_io_port]
          action: replace
          regex: (.+):(?:\d+);(\d+)
          replacement: $$1:$$2
          target_label: __address__
        - action: labelmap
          regex: __meta_kubernetes_pod_label_(.+)

processors:
  resource:
    attributes:
    - key: "cluster"
      value: "CLUSTER_NAME"
      action: upsert
    - key: "namespace"
      value: "NAMESPACE_NAME"
      action: upsert
    - key: "location"
      value: "REGION"
      action: upsert

  transform:
    # "location", "cluster", "namespace", "job", "instance", and "project_id" are reserved, and
    # metrics containing these labels will be rejected.  Prefix them with exported_ to prevent this.
    metric_statements:
    - context: datapoint
      statements:
      - set(attributes["exported_location"], attributes["location"])
      - delete_key(attributes, "location")
      - set(attributes["exported_cluster"], attributes["cluster"])
      - delete_key(attributes, "cluster")
      - set(attributes["exported_namespace"], attributes["namespace"])
      - delete_key(attributes, "namespace")
      - set(attributes["exported_job"], attributes["job"])
      - delete_key(attributes, "job")
      - set(attributes["exported_instance"], attributes["instance"])
      - delete_key(attributes, "instance")
      - set(attributes["exported_project_id"], attributes["project_id"])
      - delete_key(attributes, "project_id")

  batch:
    # batch metrics before sending to reduce API usage
    send_batch_max_size: 200
    send_batch_size: 200
    timeout: 5s

  memory_limiter:
    # drop metrics if memory usage gets too high
    check_interval: 1s
    limit_percentage: 65
    spike_limit_percentage: 20

exporters:
  googlemanagedprometheus:
    project: "PROJECT_ID"

service:
  pipelines:
    metrics:
      receivers: [prometheus]
      processors: [batch, memory_limiter, resource, transform]
      exporters: [googlemanagedprometheus]

Esta configuración hace lo siguiente:

• Configura un raspado de descubrimiento de servicios de Kubernetes para Prometheus. Para obtener más información, consulta el artículo sobre recogida de métricas de Prometheus.
• Define manualmente los atributos de recursos cluster, namespace y location. Para obtener más información sobre los atributos de recursos, incluida la detección de recursos para Amazon EKS y Azure AKS, consulta Detectar atributos de recursos.
• Define la opción project en el exportador googlemanagedprometheus. Para obtener más información sobre el exportador, consulta Configurar el exportador googlemanagedprometheus.

Cuando se usa una configuración de Prometheus con el receptor prometheus del OpenTelemetry Collector, sustituya los caracteres de signo de dólar único, , por caracteres dobles, , para evitar que se active la sustitución de variables de entorno. Para obtener más información, consulta Recoger métricas de Prometheus.

Para obtener información sobre las prácticas recomendadas para configurar el Collector en otras nubes, consulta Amazon EKS o Azure AKS.

Desplegar la aplicación de ejemplo

La aplicación de ejemplo emite la métrica de contador example_requests_total y la métrica de histograma example_random_numbers (entre otras) en su puerto metrics. El manifiesto de este ejemplo define tres réplicas.

Para desplegar la aplicación de ejemplo, ejecuta el siguiente comando:

kubectl -n NAMESPACE_NAME apply -f https://raw.githubusercontent.com/GoogleCloudPlatform/prometheus-engine/v0.15.3/examples/example-app.yaml

Crea la configuración del recopilador como ConfigMap

Una vez que hayas creado el archivo de configuración y lo hayas colocado en un archivo llamado config.yaml, utiliza ese archivo para crear un objeto ConfigMap de Kubernetes basado en tu archivo config.yaml. Cuando se implementa el recopilador, monta el ConfigMap y carga el archivo.

Para crear un ConfigMap llamado otel-config con tu configuración, usa el siguiente comando:

kubectl -n NAMESPACE_NAME create configmap otel-config --from-file config.yaml

Implementar el recopilador

Crea un archivo llamado collector-deployment.yaml con el siguiente contenido:

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: NAMESPACE_NAME:prometheus-test
rules:
- apiGroups: [""]
  resources:
  - pods
  verbs: ["get", "list", "watch"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: NAMESPACE_NAME:prometheus-test
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: NAMESPACE_NAME:prometheus-test
subjects:
- kind: ServiceAccount
  namespace: NAMESPACE_NAME
  name: default
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: otel-collector
spec:
  replicas: 1
  selector:
    matchLabels:
      app: otel-collector
  template:
    metadata:
      labels:
        app: otel-collector
    spec:
      containers:
      - name: otel-collector
        image: otel/opentelemetry-collector-contrib:0.128.0
        args:
        - --config
        - /etc/otel/config.yaml
        - --feature-gates=exporter.googlemanagedprometheus.intToDouble
        volumeMounts:
        - mountPath: /etc/otel/
          name: otel-config
      volumes:
      - name: otel-config
        configMap:
          name: otel-config

Crea el despliegue de Collector en tu clúster de Kubernetes ejecutando el siguiente comando:

kubectl -n NAMESPACE_NAME create -f collector-deployment.yaml

Una vez que se inicia el pod, raspa la aplicación de ejemplo y envía métricas a Managed Service para Prometheus.

Para obtener información sobre las formas de consultar tus datos, consulta Consultar con Cloud Monitoring o Consultar con Grafana.

Proporcionar credenciales explícitamente

Cuando se ejecuta en GKE, el OpenTelemetry Collector obtiene automáticamente las credenciales del entorno en función de la cuenta de servicio del nodo. En los clústeres de Kubernetes que no son de GKE, las credenciales se deben proporcionar explícitamente al OpenTelemetry Collector mediante marcas o la variable de entorno GOOGLE_APPLICATION_CREDENTIALS.

1. Define el contexto de tu proyecto de destino:

   gcloud config set project PROJECT_ID
   

2. Crea una cuenta de servicio:

   gcloud iam service-accounts create gmp-test-sa
   

   En este paso se crea la cuenta de servicio que puede que ya hayas creado en las instrucciones de Workload Identity Federation para GKE.

3. Concede los permisos necesarios a la cuenta de servicio:

   gcloud projects add-iam-policy-binding PROJECT_ID\
     --member=serviceAccount:gmp-test-sa@PROJECT_ID.iam.gserviceaccount.com \
     --role=roles/monitoring.metricWriter
   

4. Crea y descarga una clave para la cuenta de servicio:

   gcloud iam service-accounts keys create gmp-test-sa-key.json \
     --iam-account=gmp-test-sa@PROJECT_ID.iam.gserviceaccount.com
   

5. Añade el archivo de claves como secreto a tu clúster que no sea de GKE:

   kubectl -n NAMESPACE_NAME create secret generic gmp-test-sa \
     --from-file=key.json=gmp-test-sa-key.json
   

6. Abre el recurso de implementación de OpenTelemetry para editarlo:

   kubectl -n NAMESPACE_NAME edit deployment otel-collector
   

1. Añade el texto que se muestra en negrita al recurso:

   apiVersion: apps/v1
   kind: Deployment
   metadata:
     namespace: NAMESPACE_NAME
     name: otel-collector
   spec:
     template
       spec:
         containers:
         - name: otel-collector
           env:
           - name: "GOOGLE_APPLICATION_CREDENTIALS"
             value: "/gmp/key.json"
   ...
           volumeMounts:
           - name: gmp-sa
             mountPath: /gmp
             readOnly: true
   ...
         volumes:
         - name: gmp-sa
           secret:
             secretName: gmp-test-sa
   ...
   

2. Guarda el archivo y cierra el editor. Una vez aplicado el cambio, los pods se vuelven a crear y empiezan a autenticarse en el backend de métricas con la cuenta de servicio proporcionada.

Raspar métricas de Prometheus

En esta sección y en la siguiente se proporciona información adicional sobre la personalización para usar OpenTelemetry Collector. Esta información puede ser útil en determinadas situaciones, pero no es necesaria para ejecutar el ejemplo descrito en Configurar el Collector de OpenTelemetry.

Si tus aplicaciones ya exponen endpoints de Prometheus, el OpenTelemetry Collector puede raspar esos endpoints con el mismo formato de configuración de raspado que usarías con cualquier configuración estándar de Prometheus. Para ello, habilita el receptor Prometheus en la configuración del recopilador.

Una configuración de receptor de Prometheus para pods de Kubernetes podría tener este aspecto:

receivers:
  prometheus:
    config:
      scrape_configs:
      - job_name: 'kubernetes-pods'
        kubernetes_sd_configs:
        - role: pod
        relabel_configs:
        - source_labels: [__meta_kubernetes_pod_annotation_prometheus_io_scrape]
          action: keep
          regex: true
        - source_labels: [__meta_kubernetes_pod_annotation_prometheus_io_path]
          action: replace
          target_label: __metrics_path__
          regex: (.+)
        - source_labels: [__address__, __meta_kubernetes_pod_annotation_prometheus_io_port]
          action: replace
          regex: (.+):(?:\d+);(\d+)
          replacement: $$1:$$2
          target_label: __address__
        - action: labelmap
          regex: __meta_kubernetes_pod_label_(.+)

service:
  pipelines:
    metrics:
      receivers: [prometheus]

Se trata de una configuración de raspado basada en el descubrimiento de servicios que puedes modificar según sea necesario para raspar tus aplicaciones.

Cuando se usa una configuración de Prometheus con el receptor prometheus del OpenTelemetry Collector, sustituya los caracteres de signo de dólar único, , por caracteres dobles, , para evitar que se active la sustitución de variables de entorno. Esto es especialmente importante para el valor replacement de la sección relabel_configs. Por ejemplo, si tienes la siguiente sección relabel_config:

- source_labels: [__address__, __meta_kubernetes_pod_annotation_prometheus_io_port]
  action: replace
  regex: (.+):(?:\d+);(\d+)
  replacement: $1:$2
  target_label: __address__

Después, reescríbela para que sea:

- source_labels: [__address__, __meta_kubernetes_pod_annotation_prometheus_io_port]
  action: replace
  regex: (.+):(?:\d+);(\d+)
  replacement: $$1:$$2
  target_label: __address__

Para obtener más información, consulta la documentación de OpenTelemetry.

A continuación, te recomendamos que uses procesadores para dar formato a tus métricas. En muchos casos, los procesadores deben usarse para dar el formato adecuado a las métricas.

Añadir procesadores

Los procesadores de OpenTelemetry modifican los datos de telemetría antes de exportarlos. Puedes usar los siguientes procesadores para asegurarte de que tus métricas se escriben en un formato compatible con Managed Service para Prometheus.

Detectar atributos de recursos

El exportador de Managed Service para Prometheus de OpenTelemetry usa el prometheus_target recurso monitorizado para identificar de forma única los puntos de datos de series temporales. El exportador analiza los campos de recursos monitorizados obligatorios de los atributos de recursos de los puntos de datos de métricas. Los campos y los atributos de los que se extraen los valores son los siguientes:

• project_id detectado automáticamente por Credenciales predeterminadas de la aplicación, gcp.project.id o project en la configuración del exportador (consulta configurar el exportador)
• Ubicación: location, cloud.availability_zone, cloud.region
• Clúster: cluster, k8s.cluster_name
• namespace: namespace, k8s.namespace_name
• Trabajo: service.name + service.namespace
• Instancia: service.instance.id

Si no asigna valores únicos a estas etiquetas, se producirán errores de "serie temporal duplicada" al exportar datos a Managed Service for Prometheus. En muchos casos, los valores de estas etiquetas se pueden detectar automáticamente, pero en otros es posible que tengas que asignarlos tú. En el resto de esta sección se describen estas situaciones.

El receptor de Prometheus define automáticamente el atributo service.name en función del job_name de la configuración de extracción y el atributo service.instance.id en función del instance del destino de extracción. El receptor también define k8s.namespace.name cuando se usa role: pod en la configuración de raspado.

Cuando sea posible, rellena los demás atributos automáticamente mediante el procesador de detección de recursos. Sin embargo, en función de tu entorno, es posible que algunos atributos no se detecten automáticamente. En este caso, puede usar otros procesadores para insertar estos valores manualmente o analizarlos a partir de etiquetas de métricas. En las siguientes secciones se muestran configuraciones para detectar recursos en varias plataformas.

GKE

Cuando ejecutes OpenTelemetry en GKE, debes habilitar el procesador de detección de recursos para rellenar las etiquetas de recursos. Asegúrese de que sus métricas no contengan ya ninguna de las etiquetas de recursos reservadas. Si no puede evitarlo, consulte el artículo Evitar colisiones de atributos de recursos cambiando el nombre de los atributos.

processors:
  resourcedetection:
    detectors: [gcp]
    timeout: 10s

Esta sección se puede copiar directamente en el archivo de configuración, sustituyendo la sección processors si ya existe.

Amazon EKS

El detector de recursos de EKS no rellena automáticamente los atributos cluster o namespace. Puedes proporcionar estos valores manualmente mediante el procesador de recursos , como se muestra en el siguiente ejemplo:

processors:
  resourcedetection:
    detectors: [eks]
    timeout: 10s

  resource:
    attributes:
    - key: "cluster"
      value: "my-eks-cluster"
      action: upsert
    - key: "namespace"
      value: "my-app"
      action: upsert

También puedes convertir estos valores de etiquetas de métricas mediante el groupbyattrsprocesador (consulta la sección Mover etiquetas de métricas a etiquetas de recursos más abajo).

Azure AKS

El detector de recursos de AKS no rellena automáticamente los atributos cluster o namespace. Puedes proporcionar estos valores manualmente mediante el procesador de recursos, como se muestra en el siguiente ejemplo:

processors:
  resourcedetection:
    detectors: [aks]
    timeout: 10s

  resource:
    attributes:
    - key: "cluster"
      value: "my-eks-cluster"
      action: upsert
    - key: "namespace"
      value: "my-app"
      action: upsert

También puede convertir estos valores de etiquetas de métricas mediante el groupbyattrs procesador. Consulte Mover etiquetas de métricas a etiquetas de recursos.

Entornos on-premise y que no son en la nube

En los entornos locales o que no están en la nube, probablemente no puedas detectar ninguno de los atributos de recursos necesarios de forma automática. En este caso, puede emitir estas etiquetas en sus métricas y moverlas a atributos de recurso (consulte Mover etiquetas de métrica a etiquetas de recurso) o definir manualmente todos los atributos de recurso, como se muestra en el siguiente ejemplo:

processors:
  resource:
    attributes:
    - key: "cluster"
      value: "my-on-prem-cluster"
      action: upsert
    - key: "namespace"
      value: "my-app"
      action: upsert
    - key: "location"
      value: "us-east-1"
      action: upsert

En Crear una configuración de recopilador como ConfigMap se explica cómo usar la configuración. En esa sección se presupone que has colocado la configuración en un archivo llamado config.yaml.

El atributo de recurso project_id se puede seguir configurando automáticamente al ejecutar el recolector con credenciales predeterminadas de la aplicación. Si tu Collector no tiene acceso a las credenciales predeterminadas de la aplicación, consulta Configuración de project_id.

También puede definir manualmente los atributos de recursos que necesite en una variable de entorno, OTEL_RESOURCE_ATTRIBUTES, con una lista de pares clave-valor separados por comas. Por ejemplo:

export OTEL_RESOURCE_ATTRIBUTES="cluster=my-cluster,namespace=my-app,location=us-east-1"

A continuación, usa el envprocesador de detector de recursos para definir los atributos de recursos:

processors:
  resourcedetection:
    detectors: [env]

Evitar colisiones de atributos de recursos cambiando el nombre de los atributos

Si tus métricas ya contienen etiquetas que entran en conflicto con los atributos de recursos obligatorios (como location, cluster o namespace), cámbiales el nombre para evitar el conflicto. La convención de Prometheus consiste en añadir el prefijo exported_ al nombre de la etiqueta. Para añadir este prefijo, usa el transform processor.

La siguiente configuración de processors cambia el nombre de cualquier posible colisión y resuelve cualquier conflicto de claves de la métrica:

processors:
  transform:
    # "location", "cluster", "namespace", "job", "instance", and "project_id" are reserved, and
    # metrics containing these labels will be rejected.  Prefix them with exported_ to prevent this.
    metric_statements:
    - context: datapoint
      statements:
      - set(attributes["exported_location"], attributes["location"])
      - delete_key(attributes, "location")
      - set(attributes["exported_cluster"], attributes["cluster"])
      - delete_key(attributes, "cluster")
      - set(attributes["exported_namespace"], attributes["namespace"])
      - delete_key(attributes, "namespace")
      - set(attributes["exported_job"], attributes["job"])
      - delete_key(attributes, "job")
      - set(attributes["exported_instance"], attributes["instance"])
      - delete_key(attributes, "instance")
      - set(attributes["exported_project_id"], attributes["project_id"])
      - delete_key(attributes, "project_id")

Mover etiquetas de métricas a etiquetas de recursos

En algunos casos, es posible que tus métricas informen intencionadamente de etiquetas como namespace porque tu exportador está monitorizando varios espacios de nombres. Por ejemplo, al ejecutar el exportador kube-state-metrics.

En este caso, estas etiquetas se pueden mover a los atributos de recursos mediante el procesador groupbyattrs:

processors:
  groupbyattrs:
    keys:
    - namespace
    - cluster
    - location

En el ejemplo anterior, dada una métrica con las etiquetas namespace, cluster o location, esas etiquetas se convertirán en los atributos de recurso correspondientes.

Limitar las solicitudes a la API y el uso de memoria

Otros dos procesadores, batch processor y memory limiter processor, te permiten limitar el consumo de recursos de tu recopilador.

Procesamiento por lotes

Las solicitudes por lotes te permiten definir cuántos puntos de datos quieres enviar en una sola solicitud. Ten en cuenta que Cloud Monitoring tiene un límite de 200 series temporales por solicitud. Habilita el procesador por lotes con los siguientes ajustes:

processors:
  batch:
    # batch metrics before sending to reduce API usage
    send_batch_max_size: 200
    send_batch_size: 200
    timeout: 5s

Limitación de memoria

Te recomendamos que habilites el procesador de limitación de memoria para evitar que tu recolector falle en momentos de alto rendimiento. Para habilitar el tratamiento, usa los siguientes ajustes:

processors:
  memory_limiter:
    # drop metrics if memory usage gets too high
    check_interval: 1s
    limit_percentage: 65
    spike_limit_percentage: 20

Configurar el exportador googlemanagedprometheus

De forma predeterminada, no es necesario configurar nada más para usar el exportador googlemanagedprometheus en GKE. En muchos casos prácticos, solo tienes que habilitarlo con un bloque vacío en la sección exporters:

exporters:
  googlemanagedprometheus:

Sin embargo, el exportador ofrece algunos ajustes de configuración opcionales. En las secciones siguientes se describen los demás ajustes de configuración.

Configurando project_id

Para asociar tu serie temporal a un Google Cloud proyecto, el recurso monitorizado prometheus_target debe tener project_id definido.

Cuando se ejecuta OpenTelemetry en Google Cloud, el exportador de Managed Service para Prometheus establece de forma predeterminada este valor en función de las credenciales predeterminadas de la aplicación que encuentre. Si no hay credenciales disponibles o quieres anular el proyecto predeterminado, tienes dos opciones:

• Definir project en la configuración del exportador
• Añada un atributo de recurso gcp.project.id a sus métricas.

Te recomendamos que utilices el valor predeterminado (sin definir) de project_id en lugar de definirlo explícitamente, siempre que sea posible.

Definir project en la configuración del exportador

El siguiente fragmento de configuración envía métricas al servicio gestionado de Prometheus en el proyecto Google Cloud MY_PROJECT:

receivers:
  prometheus:
    config:
    ...

processors:
  resourcedetection:
    detectors: [gcp]
    timeout: 10s

exporters:
  googlemanagedprometheus:
    project: MY_PROJECT

service:
  pipelines:
    metrics:
      receivers: [prometheus]
      processors: [resourcedetection]
      exporters: [googlemanagedprometheus]

La única diferencia con respecto a los ejemplos anteriores es la nueva línea project: MY_PROJECT. Este ajuste es útil si sabe que todas las métricas que proceden de este Collector deben enviarse a MY_PROJECT.

Definir el atributo de recurso gcp.project.id

Puede definir la asociación de proyectos por métrica añadiendo un atributo de recurso gcp.project.id a sus métricas. Asigna al atributo el nombre del proyecto al que debe asociarse la métrica.

Por ejemplo, si su métrica ya tiene una etiqueta project, esta etiqueta se puede mover a un atributo de recurso y cambiarle el nombre a gcp.project.id mediante procesadores en la configuración del Collector, como se muestra en el siguiente ejemplo:

receivers:
  prometheus:
    config:
    ...

processors:
  resourcedetection:
    detectors: [gcp]
    timeout: 10s

  groupbyattrs:
    keys:
    - project

  resource:
    attributes:
    - key: "gcp.project.id"
      from_attribute: "project"
      action: upsert

exporters:
  googlemanagedprometheus:

service:
  pipelines:
    metrics:
      receivers: [prometheus]
      processors: [resourcedetection, groupbyattrs, resource]
      exporters: [googlemanagedprometheus]

Configurar opciones de cliente

El exportador googlemanagedprometheus usa clientes gRPC para Managed Service para Prometheus. Por lo tanto, hay ajustes opcionales disponibles para configurar el cliente gRPC:

• compression: habilita la compresión gzip para las solicitudes gRPC, lo que resulta útil para minimizar las tarifas de transferencia de datos al enviar datos de otras nubes a Managed Service for Prometheus (valores válidos: gzip).
• user_agent: anula la cadena user-agent enviada en las solicitudes a Cloud Monitoring. Solo se aplica a las métricas. El valor predeterminado es el número de compilación y de versión de tu OpenTelemetry Collector. Por ejemplo, opentelemetry-collector-contrib 0.128.0.
• endpoint: define el endpoint al que se van a enviar los datos de métricas.
• use_insecure: si es true, usa gRPC como transporte de comunicación. Solo tiene efecto cuando el valor de endpoint no es "".
• grpc_pool_size: define el tamaño del grupo de conexiones en el cliente gRPC.
• prefix: configura el prefijo de las métricas enviadas a Managed Service para Prometheus. El valor predeterminado es prometheus.googleapis.com. No cambies este prefijo, ya que, de lo contrario, las métricas no se podrán consultar con PromQL en la interfaz de Cloud Monitoring.

En la mayoría de los casos, no es necesario cambiar estos valores predeterminados. Sin embargo, puedes cambiarlos para adaptarlos a circunstancias especiales.

Todos estos ajustes se definen en un bloque metric de la sección del exportador googlemanagedprometheus, como se muestra en el siguiente ejemplo:

receivers:
  prometheus:
    config:
    ...

processors:
  resourcedetection:
    detectors: [gcp]
    timeout: 10s

exporters:
  googlemanagedprometheus:
    metric:
      compression: gzip
      user_agent: opentelemetry-collector-contrib 0.128.0
      endpoint: ""
      use_insecure: false
      grpc_pool_size: 1
      prefix: prometheus.googleapis.com

service:
  pipelines:
    metrics:
      receivers: [prometheus]
      processors: [resourcedetection]
      exporters: [googlemanagedprometheus]

Siguientes pasos

• Usa PromQL en Cloud Monitoring para consultar métricas de Prometheus.
• Usa Grafana para consultar métricas de Prometheus.
• Configura OpenTelemetry Collector como agente sidecar en Cloud Run.

• La página Gestión de métricas de Cloud Monitoring proporciona información que puede ayudarte a controlar el importe que gastas en métricas facturables sin que esto afecte a la observabilidad. En la página Gestión de métricas se muestra la siguiente información:

  • Volúmenes de ingesta para la facturación basada en bytes y en muestras, en todos los dominios de métricas y para métricas concretas.
  • Datos sobre las etiquetas y la cardinalidad de las métricas.
  • Número de lecturas de cada métrica.
  • Uso de métricas en políticas de alertas y paneles de control personalizados.
  • Tasa de errores de escritura de métricas.

  También puede usar la página Gestión de métricas para excluir las métricas que no necesite y, de esta forma, no incurrir en los costes de ingesta. Para obtener más información sobre la página Gestión de métricas, consulta el artículo Ver y gestionar el uso de métricas.