Usa Prometheus

Prometheus es una herramienta de supervisión que se usa a menudo con Kubernetes. Si configuras las operaciones de Kubernetes Engine e incluyes compatibilidad con Prometheus, las métricas que generan los servicios con el formato de exposición de Prometheus pueden exportarse desde el clúster y hacerse visibles como métricas externas en Cloud Monitoring.

En esta página, se describe cómo configurar y usar Prometheus con las operaciones de Kubernetes Engine. El código fuente para la integración es de acceso público.

Antes de comenzar

No puedes configurar clústeres con Logging y Monitoring heredados con Prometheus. Para obtener más información sobre Logging y Monitoring heredados, consulta las Guías prácticas de Logging y Monitoring heredados.

Esta página no contiene instrucciones para instalar un servidor de Prometheus o crear un clúster de GKE con las operaciones de Kubernetes Engine.

Antes de instalar el colector de Stackdriver, revisa cuidadosamente estos requisitos:

Instala el colector

Para implementar el colector de Stackdriver, sigue estos pasos:

  1. Identifica el objeto que se actualizará por su nombre y tipo de controlador. Solo se admiten los tipos de controlador deployment y statefulset.

  2. Configura las siguientes variables del entorno:

    • KUBE_NAMESPACE: Espacio de nombres para ejecutar la secuencia de comandos.
    • KUBE_CLUSTER: Parámetro del nombre del clúster del archivo adicional.
    • GCP_REGION: Parámetro de la región de Google Cloud del archivo adicional.
    • GCP_PROJECT: Parámetro del proyecto de Google Cloud del archivo adicional.
    • DATA_DIR: El directorio de datos del archivo adicional. Este es el directorio que aloja el volumen compartido en el que se escribe el servidor de Prometheus. En las siguientes instrucciones, esta variable se establece en el valor /data.
    • DATA_VOLUME: Nombre del volumen compartido en el DATA_DIR que contiene los datos de Prometheus. En las siguientes instrucciones, esta variable se configura como data-volume.
    • SIDECAR_IMAGE_TAG: Versión de la imagen de Docker para el archivo adicional de Prometheus. Puedes encontrar la actualización más reciente en Container Registry.
  3. Ejecuta la siguiente secuencia de comandos y proporciona los dos parámetros identificados en el paso inicial de este procedimiento:

    #!/bin/sh
    
    set -e
    set -u
    
    usage() {
      echo -e "Usage: $0 <deployment|statefulset> <name>\n"
    }
    
    if [  $# -le 1 ]; then
      usage
      exit 1
    fi
    
    # Override to use a different Docker image name for the sidecar.
    export SIDECAR_IMAGE_NAME=${SIDECAR_IMAGE_NAME:-'gcr.io/stackdriver-prometheus/stackdriver-prometheus-sidecar'}
    
    kubectl -n "${KUBE_NAMESPACE}" patch "$1" "$2" --type strategic --patch "
    spec:
      template:
        spec:
          containers:
          - name: sidecar
            image: ${SIDECAR_IMAGE_NAME}:${SIDECAR_IMAGE_TAG}
            imagePullPolicy: Always
            args:
            - \"--stackdriver.project-id=${GCP_PROJECT}\"
            - \"--prometheus.wal-directory=${DATA_DIR}/wal\"
            - \"--stackdriver.kubernetes.location=${GCP_REGION}\"
            - \"--stackdriver.kubernetes.cluster-name=${KUBE_CLUSTER}\"
            #- \"--stackdriver.generic.location=${GCP_REGION}\"
            #- \"--stackdriver.generic.namespace=${KUBE_CLUSTER}\"
            ports:
            - name: sidecar
              containerPort: 9091
            volumeMounts:
            - name: ${DATA_VOLUME}
              mountPath: ${DATA_DIR}
    "
    

Después de la ejecución exitosa de la secuencia de comandos, el colector de Stackdriver se agrega como archivo adicional a los pods del objeto identificado en el paso uno del procedimiento. Las dos líneas comentadas de la secuencia de comandos no son relevantes para la colección de datos de métricas de los clústeres de GKE. Sin embargo, estas dos líneas sí son relevantes cuando deseas propagar un MonitoredResource genérico.

Hay pasos adicionales que debes realizar para que los cambios de configuración sean permanentes. Estos pasos se describen en secciones posteriores.

Valida la instalación

Para validar la instalación del colector de Stackdriver, ejecuta el siguiente comando:

kubectl -n "${KUBE_NAMESPACE}" get <deployment|statefulset> <name> -o=go-template='{{$output := "stackdriver-prometheus-sidecar does not exists."}}{{range .spec.template.spec.containers}}{{if eq .name "stackdriver-prometheus-sidecar"}}{{$output = (print "stackdriver-prometheus-sidecar exists. Image: " .image)}}{{end}}{{end}}{{printf $output}}{{"\n"}}'
  • Una vez que el archivo adicional de Prometheus se haya instalado con éxito, el resultado de la secuencia de comandos enumerará la imagen que se usó desde Container Registry. En el siguiente ejemplo, la versión de la imagen es 0.4.3. En la instalación, la versión puede ser diferente:

    stackdriver-prometheus-sidecar exists. Image: gcr.io/stackdriver-prometheus/stackdriver-prometheus-sidecar:0.4.3
    
  • Si esto no sucede, en el resultado de la secuencia de comandos se muestra lo siguiente:

    stackdriver-prometheus-sidecar does not exist.
    

Para determinar si tu carga de trabajo está actualizada y disponible, ejecuta lo siguiente:

kubectl -n "${KUBE_NAMESPACE}" get <deployment|statefulset> <name>

Cambia la configuración de forma permanente

Después de verificar que el colector se haya instalado con éxito, actualiza la configuración de tu clúster para que los cambios sean permanentes:

  1. Configura el servidor de Prometheus para que escriba en un volumen compartido. En los siguientes pasos de ejemplo, se supone que DATA_DIR se configuró como /data, y DATA_VOLUME se configuró como data-volume:

    1. Asegúrate de que haya un volumen compartido en el pod de Prometheus:

      volumes:
        - name: data-volume
          emptyDir: {}
      
    2. Haz que Prometheus active el volumen debajo de /data:

      volumeMounts:
      - name: data-volume
        mountPath: /data
      
    3. Indica al servidor de Prometheus que escriba el volumen compartido en /data y agregue lo siguiente a su contenedor args:

      --storage.tsdb.path=/data
      
  2. Con las herramientas que usas para administrar la configuración de tus cargas de trabajo, vuelve a aplicar la configuración al clúster y, luego, incluye el colector de Stackdriver como archivo adicional en la nueva configuración:

    - name: sidecar
      image: gcr.io/stackdriver-prometheus/stackdriver-prometheus-sidecar:[SIDECAR_IMAGE_TAG]
      args:
      - "--stackdriver.project-id=[GCP_PROJECT]"
      - "--prometheus.wal-directory=/data/wal"
      - "--prometheus.api-address=[API_ADDRESS]"
      - "--stackdriver.kubernetes.location=[GCP_REGION]"
      - "--stackdriver.kubernetes.cluster-name=[KUBE_CLUSTER]"
      ports:
      - name: sidecar
        containerPort: 9091
      volumeMounts:
      - name: data-volume
        mountPath: /data
    

    En la expresión anterior, [API_ADDRESS] hace referencia a la dirección de la API de Prometheus, que suele ser http://127.0.0.1:9090.

Para obtener más detalles sobre la configuración del colector, consulta la documentación del archivo adicional de Stackdriver Prometheus.

Visualiza métricas

Prometheus está configurado para exportar métricas al paquete de operaciones de Google Cloud como métricas externas.

Para ver estas métricas, haz lo siguiente:

  1. En Cloud Console, selecciona Monitoring:

    Ir a Monitoring

  2. En el panel de navegación de Monitoring, haz clic en Explorador de métricas.

  3. En el menú Busca la métrica y el tipo de recurso (Find resource type and metric), haz lo siguiente:

    • Selecciona Contenedor de Kubernetes (Kubernetes Container) (k8s_container) para el Tipo de recurso (Resource Type).
    • En el campo Métrica (Metric), selecciona uno con el prefijo external/prometheus/. Por ejemplo, puedes seleccionar external/prometheus/go_memstats_alloc_bytes.

    En el siguiente ejemplo, se agregó un filtro para mostrar las métricas de un clúster específico. Filtrar por el nombre del clúster es útil cuando tienes varios clústeres en un mismo lugar de trabajo:

    Muestra de la métrica de Prometheus para un contenedor de Kubernetes.

Administra los costos de las métricas derivadas de Prometheus

Por lo general, Prometheus está configurado para recopilar todas las métricas que tu aplicación exporta y, de forma predeterminada, el colector de Stackdriver envía estas métricas a Cloud Monitoring. En esta colección, se incluyen las métricas que exportan las bibliotecas de las que depende tu aplicación. Por ejemplo, la biblioteca cliente de Prometheus exporta muchas métricas sobre el entorno de aplicaciones.

Puedes configurar filtros en el colector de Stackdriver para seleccionar qué métricas se transfieren a Cloud Monitoring. Por ejemplo, para importar solo las métricas generadas por kubernetes-pods y kubernetes-service-endpoints, agrega la siguiente declaración --include cuando inicies el stackdriver-prometheus-sidecar:

 --include={job=~"kubernetes-pods|kubernetes-service-endpoints"}

Para obtener más información, consulta la documentación del archivo adicional de Stackdriver Prometheus.

También puedes calcular cuánto contribuyen estas métricas a tu factura.

Problemas de integración de Prometheus

No se muestran datos en Cloud Monitoring.

Si no se muestran datos en Cloud Monitoring después de completar los pasos de instalación, busca los mensajes de error en los registros del recopilador.

Si los registros no contienen ningún mensaje de error obvio, activa el registro de depuración mediante el paso de la marca --log.level=debug al colector. Para que el cambio de registro se aplique debes reiniciar el colector. Después de reiniciarlo, busca los mensajes de error en los registros del colector.

Para verificar que los datos se envíen a Cloud Monitoring, puedes enviar las solicitudes a los archivos mediante el parámetro de línea de comandos --stackdriver.store-in-files-directory y, luego, inspeccionar los archivos de este directorio.

Permiso denegado

Si ves un error de permiso de la API de Monitoring, revisa los requisitos que se describen en Antes de comenzar. Asegúrate de que tus cuentas de servicio tengan el permiso adecuado. Si usa una identidad de carga de trabajo, asegúrese de crear una relación entre KSA y GSA.

Uso reglas de grabación y las métricas no aparecen en Cloud Monitoring.

Cuando uses funciones de grabación, si es posible, transfiere la métrica sin procesar a Cloud Monitoring y usa las funciones de Cloud Monitoring para agregar los datos cuando crees un gráfico o un panel.

Si la transferencia de la métrica sin procesar no es una opción, agrega una entrada static_metadata a la configuración del colector. Esta opción requiere que conserves las etiquetas job y instance. Por ejemplo, la configuración actual es válida:

  • Tu configuración del servidor de Prometheus es la siguiente:

    groups:
    - name: my-groups
      rules:
      - record: backlog_avg_10m
        expr: avg_over_time(backlog_k8s[10m])
      - record: backlog_k8s
        expr: sum(total_lag) by (app, job, instance)
    
  • La configuración del recopilador de Prometheus:

    static_metadata:
      - metric: backlog_avg_10m
        type: gauge
    

No se admiten reglas de grabación que cambien o quiten las etiquetas job o instance.

A mis métricas les faltan las etiquetas de Prometheus job y instance.

El recopilador de Stackdriver para Prometheus crea un MonitoredResource de Cloud Monitoring para tus objetos de Kubernetes a partir de etiquetas de Prometheus conocidas. Cuando cambias los descriptores de etiquetas, el colector no puede escribir las métricas en Monitoring.

Veo errores de “serie temporal duplicada” o de “escrituras desordenadas” en los registros.

Estos errores se producen cuando se escriben dos veces los datos de la métrica en la misma serie temporal. Ocurren cuando tus extremos de Prometheus usan la misma métrica dos veces desde un solo recurso supervisado de Cloud Monitoring.

Por ejemplo, un contenedor de Kubernetes puede enviar métricas de Prometheus a varios puertos. Dado que el recurso supervisado k8s_container de Monitoring no diferencia los recursos según el puerto, Monitoring detecta que estás escribiendo dos puntos en la misma serie temporal. Para evitar esta situación, agrega una etiqueta de métrica en Prometheus que diferencie las series temporales. Por ejemplo, puedes usar la etiqueta __meta_kubernetes_pod_annotation_prometheus_io_port, porque se mantiene constante en los reinicios de los contenedores.

Veo errores de “el tipo de métrica debe ser X, pero es Y” en los registros.

Estos errores se producen cuando se cambia el tipo de métrica de Prometheus por un descriptor de métrica existente. Las métricas de Cloud Monitoring se escriben estrictamente y no admiten el cambio de un tipo de métrica entre el indicador, el contador y otros.

Para cambiar el tipo de métrica, debes borrar los descriptores de métrica correspondientes y crear un descriptor nuevo. La eliminación de un descriptor de métrica hace que los datos de series temporales existentes queden inaccesibles.

Estoy seguro de que vi algunos tipos de métricas de Prometheus antes, pero ahora no los encuentro.

Prometheus está preconfigurado para exportar métricas a Cloud Monitoring como métricas externas. Cuando se exportan los datos, Monitoring crea el descriptor de métrica apropiado para la métrica externa. Si no se escriben datos de ese tipo de métrica durante, al menos, 24 meses, el descriptor de métricas está sujeto a eliminación.

No hay garantía de que los descriptores de métricas que no se usan se borren después de 24 meses, pero Monitoring se reserva el derecho de borrar cualquier descriptor de métricas de Prometheus que no se haya usado en los 24 meses anteriores.

Política de baja

La integración de Prometheus con Cloud Monitoring está sujeta a la política de baja de agentes.