Usa Prometheus

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

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

Antes de comenzar

No puedes configurar clústeres con Stackdriver heredado mediante Prometheus. Para obtener más información sobre Stackdriver heredado, consulta las Guías prácticas de Stackdriver heredado.

En esta página no se brindan instrucciones para instalar un servidor de Prometheus ni para crear un clúster de GKE con Stackdriver Kubernetes Engine Monitoring.

Antes de instalar el colector, revisa con cuidado 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 a Monitoring como métricas externas.

Para ver estas métricas, haz lo siguiente:

  1. En Cloud Console, selecciona Monitoring:

    Ir a Monitoring

  2. Haz lo siguiente:

    • Si el Explorador de métricas (Metrics Explorer) aparece en el panel de navegación, haz clic en Explorador de métricas (Metrics Explorer).

    • De lo contrario, selecciona Recursos y, luego, 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 Stackdriver. 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 Stackdriver. 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 Stackdriver Monitoring.

Si no aparece ningún dato en Stackdriver Monitoring después de realizar los pasos de instalación, busca los mensajes de error en los registros del colector.

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 Stackdriver Monitoring, puedes enviar las solicitudes a los archivos con el parámetro de línea de comandos --stackdriver.store-in-files-directory y, luego, inspeccionar los archivos de este directorio.

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

Cuando uses funciones de grabación, si es posible, transfiere la métrica sin procesar a Stackdriver Monitoring y usa las funciones de Stackdriver 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 colector de Stackdriver Prometheus es la siguiente:

    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 colector de Stackdriver Prometheus genera un Recurso supervisado de Stackdriver Monitoring para tus objetos de Kubernetes a partir de las 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 Stackdriver 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 Stackdriver Monitoring están rigurosamente escritas y no admiten cambiar el tipo de métrica entre indicadores, contadores 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 Stackdriver 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, 6 semanas, el descriptor de métricas está sujeto a eliminación.

No hay garantía de que los descriptores de métricas sin uso se borren después de 6 semanas, pero Monitoring se reserva el derecho de borrar cualquier descriptor de métrica de Prometheus que no se haya usado durante las últimas 6 semanas.

Política de baja

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