Comienza a usar el recopilador de OpenTelemetry

En este documento, se describe cómo configurar el recopilador de OpenTelemetry para recopilar métricas de Prometheus estándar y, luego, informar esas métricas a Google Cloud Managed Service para Prometheus. El recopilador de OpenTelemetry es un agente que puedes implementar tú mismo y configurar para exportar al servicio administrado para Prometheus. La configuración es similar a la ejecución del servicio administrado para Prometheus con la recopilación autoimplementada.

Puedes elegir el recopilador de OpenTelemetry en lugar de la colección autoimplementada por los siguientes motivos:

• El recopilador de OpenTelemetry te permite enrutar tus datos de telemetría a varios backends mediante la configuración de diferentes exportadores en la canalización.
• El recopilador también admite señales de métricas, registros y seguimientos, por lo que, cuando lo usas, puedes controlar los tres tipos de indicadores en un agente.
• El formato de datos independiente del proveedor de OpenTelemetry (el protocolo de OpenTelemetry o OTLP) es compatible con un ecosistema sólido de bibliotecas y componentes de recopilador conectables. Esto permite una variedad de opciones de personalización para recibir, procesar y exportar tus datos.

La compensación de estos beneficios es que la ejecución de un recopilador de OpenTelemetry requiere un enfoque de implementación y mantenimiento autoadministrado. El enfoque que elijas dependerá de tus necesidades específicas, pero en este documento, ofrecemos lineamientos recomendados para configurar el recopilador de OpenTelemetry con el servicio administrado para Prometheus como backend.

Nota: La asistencia técnica de Google Cloud proporciona asistencia limitada para la recopilación con el recopilador de OpenTelemetry.

Antes de comenzar

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

Configura proyectos y herramientas

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

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

  • Si no tienes un proyecto de Google Cloud, haz lo siguiente:

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

       Crear un proyecto nuevo

    2. En el campo Nombre del proyecto, ingresa un nombre para tu proyecto y, luego, 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 solicitará que elijas un perfil de pagos existente o que crees uno nuevo.

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

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

    1. Ve a API y servicios:

       Ir a API y servicios (APIs & Services)

    2. Selecciona tu proyecto.

    3. Haga clic en Habilitar API y servicios.

    4. Busca “Monitoring”.

    5. En los resultados de la búsqueda, haz clic en "API de 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 en la Guía de inicio rápido para GKE.

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

• gcloud
• kubectl

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

gcloud components list

Configura tu entorno

Para evitar ingresar repetidamente el ID del proyecto o el nombre del clúster, realiza la siguiente configuración:

• Configura las herramientas de línea de comandos como se indica a continuación:

  • Configura la CLI de gcloud para hacer referencia al ID del proyecto de Google Cloud:

    gcloud config set project PROJECT_ID
    

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

    kubectl config set-cluster CLUSTER_NAME
    

  Para obtener más información sobre estas herramientas, consulta lo siguiente:

  • Descripción general de la CLI de gcloud
  • Comandos de kubectl

Configura un espacio de nombres

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

kubectl create ns NAMESPACE_NAME

Verifica las credenciales de la cuenta de servicio

Puedes omitir esta sección si tu clúster de Kubernetes tiene habilitada Workload Identity.

Cuando se ejecuta en GKE, el servicio administrado para Prometheus recupera credenciales de forma automática 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 y ya quitaste cualquiera de esas funciones de la cuenta de servicio de nodo predeterminada, tendrás que volver a agregar esos permisos faltantes antes de continuar.

Si no ejecutas en GKE, consulta Proporciona credenciales explícitamente.

Configura una cuenta de servicio para Workload Identity

Puedes omitir esta sección si tu clúster de Kubernetes no tiene habilitada Workload Identity.

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

• Crea una cuenta de servicio dedicada de Google Cloud, gmp-test-sa.
• Vincula la cuenta de servicio de Google Cloud a la cuenta de servicio de Kubernetes predeterminada en un espacio de nombres de prueba, NAMESPACE_NAME.
• Otorgar el permiso necesario a la cuenta de servicio de Google Cloud

Crea y vincula la cuenta de servicio

Este paso aparece en varios lugares en la documentación del servicio administrado para Prometheus. Si ya realizaste este paso como parte de una tarea anterior, no es necesario que lo repitas. Ve a la sección Autoriza la cuenta de servicio.

Con la siguiente secuencia de comandos, se crea la cuenta de servicio gmp-test-sa y se la vincula a la cuenta de servicio de Kubernetes predeterminada 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 de forma adecuada.

Autoriza la cuenta de servicio

Los grupos de permisos relacionados se recopilan en funciones y se otorgan las funciones a una principal, en este ejemplo, la cuenta de servicio de Google Cloud. Para obtener más información sobre las funciones de Monitoring, consulta Control de acceso.

Con el siguiente comando, se otorga a la cuenta de servicio de Google Cloud, gmp-test-sa, las funciones de la API de Monitoring que necesita para leer datos de métricas.

Si ya otorgaste a la cuenta de servicio de Google Cloud una función específica como parte de la tarea anterior, no necesitas volver a hacerlo.

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

Depura la configuración de Workload Identity

Si tienes problemas para lograr que Workload Identity funcione, consulta la documentación a fin de verificar la configuración de Workload Identity y la Guía de solución de problemas de Workload Identity.

Como los errores tipográficos y de copia parcial son las fuentes de errores más comunes en la configuración de Workload Identity, recomendamos usar las variables editables y los íconos de copiar y pegar en los que se puede hacer clic incorporados en las muestras de código de estas instrucciones.

Workload Identity en entornos de producción

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

En un entorno de producción, se recomienda usar un enfoque más detallado, con una cuenta de servicio para cada componente, cada una con permisos mínimos. Si deseas obtener más información sobre la configuración de cuentas de servicio para la administración de identidades de cargas de trabajo, consulta Usa Workload Identity.

Configura el recopilador de OpenTelemetry

En esta sección, se explica cómo configurar y usar el recopilador de OpenTelemetry para recopilar 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:

• Recopila métricas de Prometheus
• Agrega procesadores
• Configura el exportador googlemanagedprometheus

El recopilador de OpenTelemetry es análogo al servicio administrado para el objeto binario del agente de Prometheus. La comunidad de OpenTelemetry publica versiones con regularidad, incluidos el código fuente, los objetos binarios y las imágenes de contenedor.

Puedes implementar estos artefactos en VMs o clústeres de Kubernetes mediante las prácticas recomendadas predeterminadas o puedes usar el compilador de recopilador para compilar tu propio recopilador que consiste solo en un componentes que necesitas. Para compilar un recopilador para usar con el Servicio administrado para Prometheus, necesitas los siguientes componentes:

• El exportador de servicios administrados para Prometheus, que escribe las métricas en el servicio administrado para Prometheus.
• Un receptor para recopilar tus métricas. En este documento, se supone que usas el receptor de Prometheus para OpenTelemetry, pero el exportador del servicio administrado para Prometheus es compatible con cualquier receptor de métricas de OpenTelemetry.
• Procesadores para agrupar por lotes y marcar tus métricas para incluir identificadores de recursos importantes según tu entorno.

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

En las siguientes secciones, se analiza cómo configurar cada uno de estos componentes con más detalle. En este documento, se describe cómo ejecutar el recopilador en GKE y en otro lugar.

Configura e implementa el recopilador

Ya sea que ejecutes tu colección en Google Cloud o en otro entorno, aún puedes configurar el recopilador de OpenTelemetry para exportar al servicio administrado para Prometheus. La mayor diferencia estará en cómo configurar el recopilador. En entornos que no son de Google Cloud, es posible que haya un formato adicional de los datos de métricas que se necesita para que sea compatible con el servicio administrado para Prometheus. Sin embargo, en Google Cloud, el recopilador puede detectar automáticamente gran parte de este formato.

Ejecuta el recopilador de OpenTelemetry en GKE

Puedes copiar la siguiente configuración en un archivo llamado config.yaml para configurar el recopilador de OpenTelemetry 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 servicios administrados para Prometheus a fin de recopilar los extremos de las métricas en los Pods de Kubernetes y exportaresas métricas a Managed Service para Prometheus. Los procesadores de canalización formatean y agrupan los datos en lotes.

Para obtener más información sobre lo que hace cada parte de esta configuración, junto con las opciones de configuración de diferentes plataformas, consulta las secciones detalladas a continuación sobre recopilar métricas y agregar procesadores.

Cuando se ejecute en clústeres con una configuración de Prometheus existente, reemplaza cualquier carácter $ por $$ para evitar activar la sustitución de variable de entorno. Para obtener más información, consulta Recopila métricas de Prometheus.

Puedes modificar esta configuración según el entorno, el proveedor y las métricas que deseas recopilar, pero la configuración de ejemplo es un punto de partida recomendado para ejecutar en GKE.

Ejecuta el recopilador de OpenTelemetry fuera de Google Cloud

Ejecutar el recopilador de OpenTelemetry fuera de Google Cloud, como local o en otros proveedores de servicios en la nube, es similar a ejecutar el recopilador en GKE. Sin embargo, es menos probable que las métricas que recopilas incluyan de forma automática los datos que lo formaten mejor para el servicio administrado para Prometheus. Por lo tanto, debes tener especial cuidado a fin de configurar el recopilador para formatear las métricas a fin de que sean compatibles con el servicio administrado para Prometheus.

Puedes configurar el siguiente archivo en un archivo llamado config.yaml a fin de configurar el recopilador de OpenTelemetry para la implementación 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:

• Establece una configuración de recopilación de servicios de Kubernetes para Prometheus. Para obtener más información, consulta Recopila métricas de Prometheus.
• Configura de forma manual los atributos de recursos cluster, namespace y location. Si deseas obtener más información sobre los atributos de recursos, incluida la detección de recursos para Amazon EKS y Azure AKS, consulta Detecta atributos de recursos.
• Configura la opción project en el exportador googlemanagedprometheus. Para obtener más información sobre el exportador, consulta Configura el exportador googlemanagedprometheus.

Cuando se ejecute en clústeres con una configuración de Prometheus existente, reemplaza cualquier carácter $ por $$ para evitar activar la sustitución de variable de entorno. Para obtener más información, consulta Recopila métricas de Prometheus.

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

Implementa 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 para este ejemplo define tres réplicas

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

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

Crea tu configuración de recopilador como un ConfigMap

Después de crear tu configuración y colocarla en un archivo llamado config.yaml, usa ese archivo para crear un ConfigMap de Kubernetes basado en tu archivo config.yaml. Cuando se implementa el recopilador, se activa 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

Implementa 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.92.0
        args:
        - --config
        - /etc/otel/config.yaml
        volumeMounts:
        - mountPath: /etc/otel/
          name: otel-config
      volumes:
      - name: otel-config
        configMap:
          name: otel-config

Para crear la implementación del recopilador en tu clúster de Kubernetes, ejecuta el siguiente comando:

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

Una vez que se inicia el Pod, se recopilan la aplicación de ejemplo y genera informes de las métricas del servicio administrado de Prometheus.

Si deseas obtener información sobre cómo consultar tus datos, visita Consulta mediante Cloud Monitoring o Consulta mediante Grafana.

Proporciona credenciales de forma explícita

Cuando se ejecuta en GKE, el recopilador de OpenTelemetry recupera automáticamente las credenciales del entorno según la cuenta de servicio del nodo. En clústeres de Kubernetes que no son de GKE, las credenciales deben proporcionarse de forma explícita al Recopilador de OpenTelemetry mediante marcas o la variable de entorno GOOGLE_APPLICATION_CREDENTIALS.

1. Configura el contexto en tu proyecto de destino:

   gcloud config set project PROJECT_ID
   

2. Crear una cuenta de servicio:

   gcloud iam service-accounts create gmp-test-sa
   

   En este paso, se crea la cuenta de servicio que puedes haber creado ya en las instrucciones de Workload Identity.

3. Otorga permisos obligatorios 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. Agrega el archivo de claves como un secreto a tu clúster que no es 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. Agrega 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. Después de aplicar el cambio, los Pods se vuelven a crear y comienzan a autenticarse en el backend de la métrica con la cuenta de servicio determinada.

Recopila métricas de Prometheus

En esta sección y la sección posterior, se proporciona información adicional de personalización para usar el recopilador de OpenTelemetry. Esta información puede ser útil en ciertas situaciones, pero ninguna es necesaria para ejecutar el ejemplo descrito en Configura el recopilador de OpenTelemetry.

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

Una configuración de receptor de Prometheus simple para los pods de Kubernetes podría verse de la siguiente manera:

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]

Esta es una configuración de scraping simple basada en el descubrimiento de servicios que puedes modificar según sea necesario para recopilar tus aplicaciones.

Cuando se ejecute en clústeres con una configuración de Prometheus existente, reemplaza cualquier carácter $ por $$ para evitar activar la sustitución de variable de entorno. Esto es muy importante para el valor replacement dentro de tu 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__

Luego, vuelve a escribirlo para que sea el siguiente:

- 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 formatear tus métricas de forma adecuada.

Agrega procesadores

Los procesadores de OpenTelemetry modifican los datos de telemetría antes de que se exporten. Puedes usar los procesadores que se indican a continuación para asegurarte de que tus métricas estén escritas en un formato compatible con el servicio administrado para Prometheus.

Detecta atributos de recursos

El exportador del Servicio administrado para Prometheus para OpenTelemetry usa el recurso supervisado prometheus_target a fin de identificar de manera inquívoca los datos de series temporales. El exportador analiza los campos de recursos supervisados necesarios de los atributos de recursos en los datos de la métrica. Los campos y los atributos de los que se extraen los valores son los siguientes:

• project_id: se detecta de forma automática mediante las credenciales predeterminadas de la aplicación, gcp.project.id o project en la configuración del exportador (consulta Configura el recurso) exportador)
• ubicación: location, cloud.availability_zone, cloud.region
• clúster: cluster, k8s.cluster_name
• espacio de nombres: namespace, k8s.namespace_name
• job: service.name + service.namespace
• instancia : service.instance.id

Si no se configuran estas etiquetas con valores únicos, se pueden generar errores de “serie temporal duplicada” cuando se exporta al servicio administrado para Prometheus.

Nota: Los términos etiquetas y atributos, cuando se refieren a los datos de métricas, representan básicamente el mismo concepto en Prometheus y OpenTelemetry, respectivamente. En este contexto, una métrica de Prometheus con la etiqueta foo se convertirá en un dato de OpenTelemetry con un atributo foo. Las etiquetas o los atributos específicos mencionados anteriormente se convierten en atributos de recursos, que son otro concepto de OpenTelemetry para identificar datos específicos de la fuente de los datos. Estos atributos de recursos se asignan a los campos de recursos supervisados enumerados.

El receptor de Prometheus establece de forma automática el atributo service.name en función del job_name en la configuración de recopilación y el atributo service.instance.id en función del instance del objetivo de recopilación. El receptor también configura k8s.namespace.name cuando se usa role: pod en la configuración de recopilación.

Recomendamos propagar de forma automática los otros atributos con el procesador de detección de recursos. Sin embargo, según tu entorno, es posible que algunos atributos no se puedan detectar de forma automática. En este caso, puedes usar otros procesadores para insertar de forma manual estos valores o analizarlos desde etiquetas de métricas. En las siguientes secciones, se ilustran opciones de configuración para realizar este procesamiento en varias plataformas.

GKE

Cuando ejecutas OpenTelemetry en GKE, solo debes habilitar el procesador de detección de recursos para completar las etiquetas de recursos. Asegúrate de que tus métricas no contengan ninguna de las etiquetas de recursos reservadas. Si esto es inevitable, consulta Evita los conflictos de atributos de recursos mediante el cambio de nombre de los atributos.

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

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

Amazon EKS

El detector de recursos EKS no completa automáticamente los atributos cluster o namespace. Puedes proporcionar estos valores de forma manual con 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 procesador groupbyattrs (consulta Mueve etiquetas de métricas a etiquetas de recursos a continuación).

Azure AKS

El detector de recursos AKS no completa de forma automática los atributos cluster o namespace. Puedes proporcionar estos valores de forma manual con 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 puedes convertir estos valores de las etiquetas de métricas con el procesador groupbyattrs. Consulta Mueve etiquetas de métricas a etiquetas de recursos.

Entornos locales y no basados en la nube

Con entornos locales o que no son de nube, es probable que no puedas detectar ninguno de los atributos de recursos necesarios de forma automática. En este caso, puedes emitir estas etiquetas en tus métricas y moverlas a atributos de recursos (consulta Mueve etiquetas de métricas a etiquetas de recursos) o configurar el total de forma manual. atributos de recursos 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 Crea la configuración de recopilador como un ConfigMap, se describe cómo usar la configuración. En esa sección, se supone que colocaste la configuración en un archivo llamado config.yaml.

El atributo project_id de recursos se puede configurar automáticamente cuando se ejecuta el recopilador con Credenciales predeterminadas de la aplicación. Si tu recopilador no tiene acceso a las credenciales predeterminadas de la aplicación, consulta Configura project_id.

Como alternativa, puedes configurar de forma manual los atributos de recursos que necesitas en una variable de entorno, OTEL_RESOURCE_ATTRIBUTES, con una lista separada por comas de pares clave-valor, por ejemplo:

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

Luego, usa el procesador del detector de recursos env para configurar los atributos de recursos:

processors:
  resourcedetection:
    detectors: [env]

Cambia los nombres de los atributos para evitar colisiones de atributos

Si tus métricas ya contienen etiquetas que entran en conflicto con los atributos de recursos necesarios (como location, cluster o namespace), cámbiales el nombre para evitar la colisión. La convención de Prometheus es agregar el prefijo exported_ al nombre de la etiqueta. Para agregar este prefijo, usa el procesador de transformación.

El siguiente archivo de configuración processors cambia el nombre de cualquier posible colisión y resuelve las claves en conflicto 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")

Mueve etiquetas de métricas a etiquetas de recursos

En algunos casos, tus métricas pueden informar de forma intencional etiquetas como namespace, ya que tu exportador supervisa varios espacios de nombres. Por ejemplo, cuando ejecutas el exportador kube-state-metrics.

En este caso, estas etiquetas se pueden mover a 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 recursos coincidentes.

Limita las solicitudes a la API y el uso de memoria

Otros dos procesadores, el procesador por lotes y el procesador del limitador de memoria, te permiten limitar el consumo de recursos de tu recopilador.

Procesamiento por lotes

El procesamiento de solicitudes por lotes te permite definir cuántos datos 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 mediante la siguiente configuración:

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

Límite de memoria

Recomendamos habilitar el procesador del límite de memoria para evitar que el recopilador falle en momentos de alta capacidad de procesamiento. Habilita el procesamiento mediante la siguiente configuración:

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

Configura el exportador googlemanagedprometheus

De forma predeterminada, el uso del exportador googlemanagedprometheus en GKE no requiere ninguna configuración adicional. En muchos casos de uso, solo necesitas habilitarlo con un bloque vacío en la sección exporters:

exporters:
  googlemanagedprometheus:

Sin embargo, el exportador proporciona algunas opciones de configuración opcionales. En las siguientes secciones, se describen las otras opciones de configuración.

Configura project_id

Para asociar tus series temporales a un proyecto de Google Cloud, el recurso supervisado prometheus_target debe tener configurado project_id.

Cuando se ejecuta OpenTelemetry en Google Cloud, el exportador del Servicio administrado para Prometheus configura este valor de forma predeterminada según las credenciales predeterminadas de la aplicación que encuentra. Si no hay credenciales disponibles o deseas anular el proyecto predeterminado, tienes dos opciones:

• Establece project en la configuración del exportador
• Agrega un atributo de recurso gcp.project.id a tus métricas.

Recomendamos enfáticamente usar el valor predeterminado (sin configurar) para project_id, en lugar de configurarlo de forma explícita, cuando sea posible.

Nota: Cuando cambies el project_id, la cuenta de servicio del recopilador debe tener el rol de IAM roles/monitoring.metricWriter para el proyecto de destino.

Establece project en la configuración del exportador

En el siguiente extracto de configuración, se envían métricas al servicio administrado para Prometheus en el proyecto MY_PROJECT de Google Cloud:

receivers:
  prometheus:
    config:
    ...

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

exporters:
  googlemanagedprometheus:
    project: MY_PROJECT

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

El único cambio de los ejemplos anteriores es la línea nueva project: MY_PROJECT. Esta configuración es útil si sabes que cada métrica que llega a través de este recopilador debe enviarse a MY_PROJECT.

Establece el atributo de recurso gcp.project.id

Puedes configurar la asociación del proyecto por métrica agregando un atributo de recurso gcp.project.id a tus métricas. Establece el valor del atributo en el nombre del proyecto con el que se debe asociar la métrica.

Por ejemplo, si tu métrica ya tiene una etiqueta project, esta etiqueta se puede mover a un atributo de recurso y se le puede cambiar el nombre a gcp.project.id mediante los procesadores en la configuración del recopilador, 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]

Configura las opciones del cliente

El exportador googlemanagedprometheus usa clientes de gRPC para el servicio administrado para Prometheus. Por lo tanto, hay parámetros de configuración opcionales disponibles para configurar el cliente de gRPC:

• compression: Habilita la compresión gzip para las solicitudes de gRPC, que es útil para minimizar las tarifas de transferencia de datos cuando se envían desde otras nubes hacia el servicio administrado para Prometheus (valores válidos: gzip).
• user_agent: Anula la cadena de usuario-agente enviada en las solicitudes a Cloud Monitoring; solo se aplica a las métricas. La configuración predeterminada es el número de versión y compilación de tu recopilador de OpenTelemetry, por ejemplo, opentelemetry-collector-contrib 0.92.0.
• endpoint: Establece el extremo al que se enviarán los datos de métrica.
• use_insecure: Si es verdadero, usa gRPC como el transporte de comunicación. Tiene efecto solo cuando el valor endpoint no es “”.
• grpc_pool_size: Configura el tamaño del grupo de conexiones en el cliente de gRPC.
• prefix: Configura el prefijo de métricas enviadas al servicio administrado para Prometheus. La configuración predeterminada es prometheus.googleapis.com. No cambies este prefijo. Esto hace que las métricas no se puedan consultar con PromQL en la IU de Cloud Monitoring.

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

Todas estas opciones de configuración se establecen en un bloque metric en 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.92.0
      endpoint: ""
      use_insecure: false
      grpc_pool_size: 1
      prefix: prometheus.googleapis.com

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

Próximos pasos

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

• En la página Administración de métricas de Cloud Monitoring, se proporciona información que puede ayudarte a controlar el importe que inviertes en las métricas cobrables sin afectar la observabilidad. En la página Administración de métricas, se informa la siguiente información:

  • Los volúmenes de transferencia para la facturación basada en bytes y de muestra, en todos los dominios de métricas y para las métricas individuales.
  • Datos sobre etiquetas y cardinalidad de métricas.
  • Uso de métricas en políticas de alertas y paneles personalizados.
  • Tasa de errores de escritura de métricas.
  Para obtener más información sobre la página Administración de métricas, consulta Ve y administrar el uso de métricas.