Consulta y visualiza métricas

Después de recopilar métricas de tus cargas de trabajo implementadas en Google Distributed Cloud (GDC) aislado, puedes comenzar a analizarlas. Para analizar las métricas, puedes visualizarlas y filtrarlas en paneles informativos de Grafana o acceder a ellas directamente desde Cortex con la herramienta curl para automatización y secuencias de comandos flexibles.

En esta página, se proporcionan instrucciones detalladas para consultar y visualizar tus métricas con la interfaz de usuario de Grafana y la herramienta de curl para el extremo de Cortex con el objetivo de obtener estadísticas sobre el rendimiento de tus cargas de trabajo.

Puedes acceder a tus métricas con uno de los siguientes dos métodos:

  • Paneles de Grafana: Explora tendencias y detecta anomalías con visualizaciones intuitivas de métricas clave, como el uso de CPU, el consumo de almacenamiento y la actividad de red. Grafana proporciona una interfaz fácil de usar para filtrar y analizar los datos de tus cargas de trabajo en paneles.
  • Extremo de Cortex: Para casos de uso más avanzados, consulta la instancia de Cortex de tu proyecto directamente con la herramienta curl en una línea de comandos. Cortex almacena las métricas de Prometheus de tu proyecto y proporciona un extremo HTTP para el acceso programático. Este acceso te permite exportar datos, automatizar tareas y compilar integraciones personalizadas.

Antes de comenzar

Para obtener los permisos que necesitas para consultar y visualizar métricas en los paneles de Grafana, pídele a tu administrador de la organización de IAM o al administrador del proyecto de IAM que te otorgue uno de los roles predefinidos de visualizador de Grafana de la organización o de visualizador de Grafana del proyecto. Según el nivel de acceso y los permisos que necesites, puedes obtener roles de Grafana en una organización o un proyecto.

Como alternativa, para obtener los permisos que necesitas para consultar métricas desde el extremo de Cortex, pídele al administrador de proyectos de IAM que te otorgue el rol de visualizador de Prometheus de Cortex del proyecto en el espacio de nombres de tu proyecto.

En la siguiente tabla, se resumen los requisitos de Role para los roles de PA y AO.

Personificación Objeto Clúster Rol Espacio de nombres Grupo/usuario Configuración
PA grafana org-admin project-grafana-viewer platform-obs Grupo 1
PA cortex org-admin project-cortex-prometheus-viewer platform-obs Grupo 2
PA grafana org-admin project-grafana-viewer platform-obs Usuario 3
PA cortex org-admin project-cortex-prometheus-viewer platform-obs Usuario 4
AO grafana org-admin project-grafana-viewer PROJECT_NAMESPACE Grupo 1
AO cortex org-admin project-cortex-prometheus-viewer PROJECT_NAMESPACE Grupo 2
AO grafana org-admin project-grafana-viewer PROJECT_NAMESPACE Usuario 3
AO cortex org-admin project-cortex-prometheus-viewer PROJECT_NAMESPACE Usuario 4

Reemplaza las siguientes variables de forma adecuada:

Variable Descripción
KUBECONFIG Necesitarás el kubeconfig del clúster específico que contiene el NAMESPACE en el que se aplicará este RoleBinding.
RULE_NAME Es el nombre único de este recurso RoleBinding dentro del espacio de nombres. Por ejemplo, io-root-cortex-prometheus-viewer
NAMESPACE Es el espacio de nombres de Kubernetes en el que se creará y aplicará este RoleBinding. Busca la columna Namespace en la tabla anterior.
EMAIL_ADDRESS Es el identificador del usuario al que se le otorga el rol. Suele ser una dirección de correo electrónico. Por ejemplo, infrastructure-operator@example.com.
ROLE Es el nombre del Role que contiene los permisos que deseas otorgar al usuario. Busca los roles disponibles en la tabla anterior.
GROUP_NAME Es el nombre del Group al que pertenece el usuario de PA o AO. Por ejemplo, pa-group
ZONE Nombre de la zona

Config. 1

Esta configuración otorga permisos a un grupo de usuarios para acceder a Grafana de PA/AO en el clúster de org. Después de establecer esta configuración, consulta la sección Paneles de Grafana de este documento para ver las métricas en Grafana.

  • Comando de kubectl

    Este es el formato genérico del comando:

    kubectl --kubeconfig `KUBECONFIG` create rolebinding `RULE_NAME` -n platform-obs --group=`GROUP_NAME` --role=project-grafana-viewer

    Ejemplo:

    kubectl --kubeconfig <path-to-kubeconfig> create rolebinding project-grafana-viewers-binding --role=project-grafana-viewer --group=my-team --namespace=platform-obs

  • Ruta de acceso del archivo IAC

    /infrastructure/zonal/zones/`ZONE`/org-admin/rolebindings/`GROUP_NAME`/<YAML_FILE>

  • Archivo YAML

    apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: RULE_NAME
  namespace: platform-obs
subjects:
- kind: Group
  name: GROUP_NAME
  apiGroup: rbac.authorization.k8s.io
roleRef:
  kind: Role
  name: project-grafana-viewer
  apiGroup: rbac.authorization.k8s.io

Config. 2

Esta configuración otorga permisos a un grupo de usuarios para que puedan acceder de forma programática a las métricas de PA/AO en el clúster de org. Después de establecer esta configuración, consulta la sección extremo de Cortex de este documento para consultar las métricas de forma programática.

  • Comando de kubectl

    Este es el formato genérico del comando:

    kubectl --kubeconfig `KUBECONFIG` create rolebinding `RULE_NAME` -n platform-obs --group=`GROUP_NAME` --role=project-cortex-prometheus-viewer

    Ejemplo:

    kubectl --kubeconfig <path-to-kubeconfig> create rolebinding project-cortex-prometheus-viewer-binding --role=project-cortex-prometheus-viewer --group=my-team --namespace=platform-obs

  • Ruta de acceso del archivo IAC

    /infrastructure/zonal/zones/`ZONE`/org-admin/rolebindings/`GROUP_NAME`/<YAML_FILE>

  • Archivo YAML

    apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: RULE_NAME
  namespace: platform-obs
subjects:
- kind: Group
  name: GROUP_NAME
  apiGroup: rbac.authorization.k8s.io
roleRef:
  kind: Role
  name: project-cortex-prometheus-viewer
  apiGroup: rbac.authorization.k8s.io

Configuración 3

Esta configuración otorga permisos a un usuario para acceder a PA/AO Grafana en el clúster org. Después de establecer esta configuración, consulta la sección Paneles de Grafana de este documento para ver las métricas en Grafana.

  • Comando de kubectl

    Este es el formato genérico del comando:

    kubectl --kubeconfig `KUBECONFIG` create rolebinding `RULE_NAME` -n platform-obs --user=`EMAIL_ADDRESS` --role=project-grafana-viewer

    Ejemplo:

    kubectl --kubeconfig <path-to-kubeconfig> create rolebinding project-grafana-viewers-binding --role=project-grafana-viewer --user=my-email@example.com --namespace=platform-obs

  • Ruta de acceso del archivo IAC

    /infrastructure/zonal/zones/`ZONE`/org-admin/rolebindings/`EMAIL_ADDRESS`/<YAML_FILE>

  • Archivo YAML

    apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: RULE_NAME
  namespace: platform-obs
subjects:
- kind: User
  name: EMAIL_ADDRESS
  apiGroup: rbac.authorization.k8s.io
roleRef:
  kind: Role
  name: project-grafana-viewer
  apiGroup: rbac.authorization.k8s.io

Configuración 4

Esta configuración otorga permisos a un usuario para que pueda acceder de forma programática a las métricas de PA/AO en el clúster de org. Después de establecer esta configuración, consulta la sección extremo de Cortex de este documento para consultar las métricas de forma programática.

  • Comando de kubectl

    Este es el formato genérico del comando:

    kubectl --kubeconfig `KUBECONFIG` create rolebinding `RULE_NAME` -n platform-obs --user=`EMAIL_ADDRESS` --role=project-cortex-prometheus-viewer

    Ejemplo:

    kubectl --kubeconfig <path-to-kubeconfig> create rolebinding project-cortex-prometheus-viewer-binding --role=project-cortex-prometheus-viewer --user=my-email@example.com --namespace=platform-obs

  • Ruta de acceso del archivo IAC

    /infrastructure/zonal/zones/`ZONE`/org-admin/rolebindings/`EMAIL_ADDRESS`/<YAML_FILE>

  • Archivo YAML

    apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: RULE_NAME
  namespace: platform-obs
subjects:
- kind: User
  name: EMAIL_ADDRESS
  apiGroup: rbac.authorization.k8s.io
roleRef:
  kind: Role
  name: project-cortex-prometheus-viewer
  apiGroup: rbac.authorization.k8s.io

Para obtener más información sobre estos roles, consulta Prepara los permisos de IAM.

Obtén y filtra tus métricas

Selecciona uno de los siguientes métodos para compilar consultas, visualizar tendencias y filtrar métricas de las cargas de trabajo de tu proyecto:

Paneles de Grafana

En esta sección, se describe cómo acceder a tus métricas con los paneles de Grafana.

Identifica tu extremo de Grafana

La siguiente URL es el extremo de la instancia de Grafana de tu proyecto:

  https://GDC_URL/PROJECT_NAMESPACE/grafana

Reemplaza lo siguiente:

  • GDC_URL: Es la URL de tu organización en GDC.

  • PROJECT_NAMESPACE: Es el espacio de nombres de tu proyecto.

    Por ejemplo, el extremo de Grafana para el proyecto platform-obs en la organización org-1 es https://org-1/platform-obs/grafana.

Visualiza métricas en la interfaz de usuario de Grafana

Recupera métricas en la interfaz de usuario de Grafana:

  1. En la consola de GDC, selecciona tu proyecto.
  2. En el menú de navegación, selecciona Operaciones > Monitoring.

  3. Haz clic en Ver todo en Grafana.

    Se abrirá una página nueva con tu extremo de Grafana y se mostrará la interfaz de usuario.

  4. En la interfaz de usuario, haz clic en Explorar Explorar en el menú de navegación para abrir la página Explorar.

  5. En el menú de la barra Explorar, selecciona una fuente de datos para recuperar las métricas, según tu tipo de universo:

    • Universos de una sola zona: Selecciona prometheus para mostrar las métricas de la zona única de tu universo.

    • Universos multizona: Grafana puede conectarse a diferentes zonas y mostrar datos entre zonas. Selecciona Métricas ZONE_NAME para mostrar las métricas de cualquier zona de tu universo, sin importar la zona en la que hayas accedido.

      Además, para tener visualizaciones de datos de varias zonas en un solo panel y agregar varias zonas a tu consulta, selecciona Mixto como fuente de datos.

  6. Ingresa una consulta para buscar métricas con expresiones de PromQL (lenguaje de consulta de Prometheus). Puedes realizar este paso de cualquiera de las siguientes maneras:

    • Selecciona una métrica y una etiqueta para tu consulta en los menús Métrica y Filtros de etiquetas. Haz clic en add Agregar para agregar más etiquetas a tu consulta. Luego, haz clic en Ejecutar consulta.
    • Ingresa tu consulta directamente en el campo de texto Métricas y presiona Mayúsculas + Intro para ejecutarla.

    En la página, se muestran las métricas que coinciden con tu consulta.

    La opción de Prometheus está seleccionada en la página Explorar para obtener métricas.

    Figura 1. Opción de menú para consultar métricas desde la interfaz de usuario de Grafana.

    En la figura 1, la opción prometheus muestra la interfaz que te permite crear consultas desde Grafana para recuperar métricas.

    Para ver ejemplos de valores de etiquetas que puedes usar para consultar métricas, consulta Consultas y etiquetas de ejemplo.

Extremo de Cortex: zona única

En esta sección, se describe cómo acceder a tus métricas con Cortex.

Identifica tu extremo de Cortex

La siguiente URL es el extremo de la instancia de Cortex de tu proyecto:

  https://GDC_URL/PROJECT_NAMESPACE/cortex/prometheus/

Reemplaza lo siguiente:

  • GDC_URL: Es la URL de tu organización en GDC.

  • PROJECT_NAMESPACE: Es el espacio de nombres de tu proyecto.

    Por ejemplo, el extremo de Cortex para el proyecto platform-obs en la organización org-1 es https://org-1/platform-obs/cortex/prometheus/.

Autentica la solicitud de curl

  1. Descarga e instala la CLI de gdcloud.

  2. Configura la propiedad gdcloud core/organization_console_url:

    gdcloud config set core/organization_console_url
https://GDC_URL

  3. Accede con el proveedor de identidad configurado:

    gdcloud auth login

  4. Usa tu nombre de usuario y contraseña para autenticarte y acceder.

    Cuando el acceso se realice correctamente, podrás usar el encabezado de autorización en tu solicitud curl a través del comando gdcloud auth print-identity-token. Para obtener más información, consulta gdcloud auth.

Llama al extremo de Cortex

Completa los siguientes pasos para llegar al extremo de Cortex con la herramienta curl:

  1. Autentica la solicitud curl.

  2. Usa curl para llamar al extremo de Cortex y extender la URL con el formato de API de HTTP de consulta para consultar métricas.

    El siguiente es un ejemplo de una solicitud curl:

    curl https://GDC_URL/PROJECT_NAME/cortex/prometheus/api/v1/query?query=my_metric{cluster="my-cluster"}&time=2015-07-01T20:10:51.781Z \
-H "Authorization: Bearer $(gdcloud auth print-identity-token \
--audiences=https://GDC_URL)"

    Obtendrás el resultado después del comando. La respuesta de la API está en formato JSON.

Extremo de Cortex: multizona

En esta sección, se describe cómo acceder a tus métricas con Cortex.

Identifica tu extremo de Cortex

La siguiente URL es el extremo de la instancia de Cortex de tu proyecto para la consulta multizona:

  https://GDC_URL/PROJECT_NAMESPACE/cortex/metrics

Reemplaza lo siguiente:

  • GDC_URL: Es la URL de tu organización en GDC.

    • Ejemplo para org-1, zone1: console.org-1.zone1.google.gdch.test
    • Reemplaza la organización y la zona de tu aplicación.

  • PROJECT_NAMESPACE: Es el espacio de nombres de tu proyecto.

    Por ejemplo, el extremo de Cortex para el proyecto project-1 en la organización org-1 es https://console.org-1.zone1.google.gdch.test/project-1/cortex/metrics..

Autentica la solicitud de curl

  1. Descarga e instala la CLI de gdcloud.

  2. Configura la propiedad gdcloud core/organization_console_url:

    gdcloud config set core/organization_console_url
https://GDC_URL

  3. Accede con el proveedor de identidad configurado:

    gdcloud auth login

  4. Usa tu nombre de usuario y contraseña para autenticarte y acceder.

    Cuando el acceso se realice correctamente, podrás usar el encabezado de autorización en tu solicitud curl a través del comando gdcloud auth print-identity-token. Para obtener más información, consulta gdcloud auth.

Llama al extremo de Cortex

Completa los siguientes pasos para llegar al extremo de Cortex con la herramienta curl:

  1. Autentica la solicitud curl.
  2. Usa curl para llamar al extremo de Cortex y extender la URL con el formato de API de HTTP de consulta para consultar métricas.

  3. Además de los parámetros de consulta de URL de Prometheus, incluye el parámetro de ubicación para proporcionar una lista de zonas para las que se debe realizar la consulta. - location={string}: Es una lista de zonas separadas por |. - Si no se proporciona, la consulta se ejecutará en todas las zonas disponibles.

    El siguiente es un ejemplo de una solicitud curl POST:

     curl POST \
 https://GDC_URL/PROJECT_NAME/cortex/metrics/api/v1/query_range" \
-H 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'query=pod_cpu_usage_total' \
--data-urlencode 'start=2025-07-21T16:00:00Z' \
--data-urlencode 'end=2025-07-21T16:15:00Z' \
--data-urlencode 'step=60s' \
--data-urlencode 'location=zone1|zone2' \
-H "Authorization: Bearer $(gdcloud auth print-identity-token \
--audiences=https://GDC_URL)"

    El siguiente es un ejemplo de una solicitud curl GET:

     curl -X GET \
 https://GDC_URL/PROJECT_NAME/cortex/metrics/api/v1/query_range?query=pod_cpu_usage_total&start=2025-07-21T16:00:00Z&end=2025-07-21T16:15:00Z&step=1s&location=zone1|zone2" \
-H "Authorization: Bearer $(gdcloud auth print-identity-token \
--audiences=https://GDC_URL)"

    Obtendrás el resultado después del comando. La respuesta de la API está en formato JSON.

Consultas y etiquetas de muestra

Puedes consultar las métricas con el nombre de la métrica y los pares clave-valor para las etiquetas. Una consulta de PromQL tiene la siguiente sintaxis:

metric_name{label_one="value", label_two="value"}

Las etiquetas te permiten diferenciar las características de una métrica. De esta manera, los autores de contenedores hacen que sus cargas de trabajo generen métricas y agreguen etiquetas para filtrar esas métricas.

Por ejemplo, puedes tener una métrica api_http_requests_total para contar la cantidad de solicitudes HTTP recibidas. Luego, puedes agregar una etiqueta request_method a esta métrica, que toma un valor POST, GET o PUT. Por lo tanto, crearás tres flujos de métricas para cada tipo de solicitud que puedas recibir. En este caso, para encontrar la cantidad de solicitudes HTTP GET, ejecuta la siguiente consulta:

api_http_requests_total{request_method="GET"}

Consulta Nombres de métricas y etiquetas para obtener más información sobre las métricas y las etiquetas.

A continuación, se muestran algunas de las etiquetas predeterminadas que agrega el recurso personalizado MonitoringTarget. Puedes usar estas etiquetas predeterminadas para consultar métricas:

  • _gdch_service: Es el nombre corto del servicio.
  • cluster: el nombre del clúster
  • container_name: Es el nombre del contenedor dentro de un Pod.
  • namespace_name: Es el espacio de nombres de tu proyecto.
  • pod_name: Es el prefijo del nombre del Pod.

En la siguiente tabla, se describen las etiquetas que Prometheus agrega de forma automática:

Etiquetas predeterminadas
Etiqueta de métrica Descripción
job Es el nombre interno del trabajo de extracción que se usa para recopilar la métrica. Los trabajos creados por el recurso personalizado MonitoringTarget tienen un nombre con el siguiente patrón:

obs-system/OBS_SHADOW_PROJECT_NAME/MONITORINGTARGET_NAME.MONITORINGTARGET_NAMESPACE/I/J

I y J son números únicos que se determinan de forma interna para evitar conflictos de nombres.
instance El $IP:$PORT del servicio extraído. Si un recurso de carga de trabajo tiene varias réplicas, usa este campo para diferenciarlas.

En la siguiente muestra de código, se indica el uso de pares clave-valor para las etiquetas con el objetivo de consultar diferentes métricas y ver el uso de CPU recopilado en un clúster de Kubernetes:

pod_cpu_usage_total{cluster="CLUSTER_NAME"}

Usa la herramienta de reetiquetado de métricas para agregar etiquetas que no se expusieron inicialmente en los contenedores descartados y cambiar el nombre de las métricas producidas. Debes configurar el recurso personalizado MonitoringTarget para agregar etiquetas a las métricas que recopila. Especifica esas etiquetas en el campo metricsRelabelings del recurso personalizado. Para obtener más información, consulta Métricas de etiquetas.

A continuación, se muestra un ejemplo de una respuesta recibida de un extremo de métricas de Cortex:

          {
    "zone1": {
      "status": "success",
      "data": {
        "resultType": "matrix",
        "result": [
          {
            "metric": {
              "__name__": "pod_cpu_usage_total",
              "_gdch_project": "project-1",
              "cluster": "root-admin",
              "container_name": "otel-collector",
              "exported_instance": "localhost:2112",
              "exported_job": "workload-0",
              "ha_cluster": "root-admin-shard1",
              "instance": "172.192.1.74:3113",
              "job": "metrics-server-exporter.mon-system",
              "namespace": "mon-system",
              "namespace_name": "mon-system",
              "pod": "cortex-0",
              "pod_name": "metrics-server-exporter-695c9f848b-swzgq",
              "zone_id": "zone1"
            },
            "values": [
              [
                1753261200,
                "2.258621991"
              ],
              [
                1753261800,
                "1.029301454"
              ]
            ]
          }
        ]
      }
    },
    "zone2": {
      "status": "success",
      "data": {
        "resultType": "matrix",
        "result": [
          {
            "metric": {
              "__name__": "pod_cpu_usage_total",
              "_gdch_project": "project-1",
              "cluster": "root-admin",
              "container_name": "otel-collector",
              "exported_instance": "localhost:2112",
              "exported_job": "workload-0",
              "ha_cluster": "root-admin-shard1",
              "instance": "172.196.3.208:3113",
              "job": "metrics-server-exporter.mon-system",
              "namespace": "mon-system",
              "namespace_name": "mon-system",
              "pod": "cortex-0",
              "pod_name": "metrics-server-exporter-695c9f848b-kchfv",
              "zone_id": "zone2"
            },
            "values": [
              [
                1753261200,
                "1.814027424"
              ],
              [
                1753261800,
                "2.7767060260000003"
              ]
            ]
          }
        ]
      }
    }
  }

Consulta la API de HTTP

Descripción general del formato

Las respuestas de la API tienen un formato coherente en JSON. Las solicitudes exitosas siempre recibirán un código de estado 2xx.

En el caso de las solicitudes no válidas, los controladores de la API devolverán un objeto de error JSON junto con uno de los siguientes códigos de estado HTTP:

  • 400 Solicitud incorrecta: Si faltan parámetros esenciales o se proporcionan de forma incorrecta.
  • 503 Servicio no disponible: Si las consultas superan su límite de tiempo o se anulan.

Todos los datos que se recopilaron correctamente se incluirán en el campo "data" de la respuesta.

El formato de la respuesta JSON es el siguiente:

{
  "status": "success" | "error",
  "data": <data>,

  // Only set if status is "error". The data field may still hold
  // additional data.
  "errorType": "<string>",
  "error": "<string>",

  // Only set if there were warnings while executing the request.
  // There will still be data in the data field.
  "warnings": ["<string>"],
  // Only set if there were info-level annotations while executing the request.
  "infos": ["<string>"]
}

Consultas instantáneas

El siguiente extremo evalúa una consulta instantánea en un solo momento:

GET /api/v1/query
POST /api/v1/query

Los siguientes parámetros de consulta de URL están disponibles para las consultas de expresión de Prometheus:

  • query=<string>: Es la cadena de consulta de la expresión de Prometheus.
  • time=<rfc3339 | unix_timestamp>: Es una marca de tiempo de evaluación opcional, especificada como una cadena RFC 3339 o una marca de tiempo de Unix. Si se omite, se usa la hora actual del servidor.
  • timeout=<duration>: Es un tiempo de espera de evaluación opcional. El valor predeterminado es el valor de la marca query.timeout y está limitado por este.
  • limit=<number>: Es una cantidad máxima opcional de series que se mostrarán. Esto trunca las series para matrices y vectores, pero no afecta a los escalares ni a las cadenas. Un valor de 0 inhabilita este límite.
  • lookback_delta=<number>: Es un parámetro opcional para anular el período de visualización específicamente para esta consulta.

Si se omite el parámetro de hora, se usa la hora actual del servidor.

Para consultas más grandes que podrían superar los límites de caracteres de la URL, puedes enviar estos parámetros con el método POST. Asegúrate de que el cuerpo de la solicitud esté codificado en formato URL y de que el encabezado Content-Type esté configurado como application/x-www-form-urlencoded.

La sección de datos del resultado de la consulta tiene el siguiente formato:

{
  "resultType": "matrix" | "vector" | "scalar" | "string",
  "result": <value>
}

<value> hace referencia a los datos del resultado de la consulta, que tiene diferentes formatos según el resultType.

En el siguiente ejemplo, se evalúa la expresión up en el momento 2015-07-01T20:10:51.781Z:

curl 'http://localhost:9090/api/v1/query?query=up&time=2015-07-01T20:10:51.781Z'

{
   "status" : "success",
   "data" : {
      "resultType" : "vector",
      "result" : [
         {
            "metric" : {
               "__name__" : "up",
               "job" : "prometheus",
               "instance" : "localhost:9090"
            },
            "value": [ 1435781451.781, "1" ]
         },
         {
            "metric" : {
               "__name__" : "up",
               "job" : "node",
               "instance" : "localhost:9100"
            },
            "value" : [ 1435781451.781, "0" ]
         }
      ]
   }
}

Consultas por rango

El siguiente extremo evalúa una consulta de expresión en un intervalo de tiempo:

GET /api/v1/query_range
POST /api/v1/query_range

Los siguientes parámetros de consulta de URL están disponibles para las consultas de expresión de Prometheus:

  • query=<string>: Es la cadena de consulta de la expresión de Prometheus.
  • start=<rfc3339 | unix_timestamp>: Es la marca de tiempo de inicio, inclusiva.
  • end=<rfc3339 | unix_timestamp>: Es la marca de tiempo de finalización, inclusive.
  • step=<duration | float>: Es el ancho del paso de resolución de la consulta en formato de duración o número de segundos de punto flotante.
  • timeout=<duration>: Es un tiempo de espera de evaluación opcional. El valor predeterminado es el valor de la marca query.timeout y está limitado por este.
  • limit=<number>: Es una cantidad máxima opcional de series que se mostrarán. Esto trunca las series para matrices y vectores, pero no afecta a los escalares ni a las cadenas. Un valor de 0 inhabilita este límite.
  • lookback_delta=<number>: Es un parámetro opcional para anular el período de visualización específicamente para esta consulta.

Para consultas más grandes que podrían superar los límites de caracteres de la URL, puedes enviar estos parámetros con el método POST. Asegúrate de que el cuerpo de la solicitud esté codificado en formato URL y de que el encabezado Content-Type esté configurado como application/x-www-form-urlencoded.

La sección de datos del resultado de la consulta tiene el siguiente formato:

{
  "resultType": "matrix",
  "result": <value>
}

En el siguiente ejemplo, se evalúa la expresión up en un rango de 30 segundos con una resolución de consulta de 15 segundos.

curl 'http://localhost:9090/api/v1/query_range?query=up&start=2015-07-01T20:10:30.781Z&end=2015-07-01T20:11:00.781Z&step=15s'

{
   "status" : "success",
   "data" : {
      "resultType" : "matrix",
      "result" : [
         {
            "metric" : {
               "__name__" : "up",
               "job" : "prometheus",
               "instance" : "localhost:9090"
            },
            "values" : [
               [ 1435781430.781, "1" ],
               [ 1435781445.781, "1" ],
               [ 1435781460.781, "1" ]
            ]
         },
         {
            "metric" : {
               "__name__" : "up",
               "job" : "node",
               "instance" : "localhost:9091"
            },
            "values" : [
               [ 1435781430.781, "0" ],
               [ 1435781445.781, "0" ],
               [ 1435781460.781, "1" ]
            ]
         }
      ]
   }
}

Nombres de métricas y etiquetas

Lineamientos para asignar nombres a las métricas

Cuando definas los nombres de las métricas, ten en cuenta los siguientes principios:

  • Un nombre de métrica DEBERÍA incluir un prefijo de aplicación de una sola palabra, al que las bibliotecas cliente a veces se refieren como un "espacio de nombres". Este prefijo identifica el dominio al que pertenece la métrica. En el caso de las métricas específicas de la aplicación, se suele usar el nombre de la aplicación como prefijo.

    Ejemplos:

    • prometheus_notifications_total (específico del servidor de Prometheus)
    • process_cpu_seconds_total (exportada por muchas bibliotecas cliente)
    • http_request_duration_seconds (para todas las solicitudes HTTP)

  • El nombre de una métrica DEBE representar una sola unidad (p.ej., evita mezclar segundos con milisegundos o segundos con bytes).

  • Un nombre de métrica DEBERÍA usar unidades base (p.ej., segundos, bytes, metros) en lugar de unidades derivadas (p.ej., milisegundos, megabytes, kilómetros).

  • El nombre de una métrica DEBERÍA incluir un sufijo de unidad en plural. Para los recuentos acumulados, se debe usar el sufijo "total" además del sufijo de unidad, si corresponde.

    Ejemplos:

    • http_request_duration_seconds
    • node_memory_usage_bytes
    • http_requests_total (para un recuento acumulativo sin unidades)
    • process_cpu_seconds_total (para un recuento acumulativo con unidad)
    • foobar_build_info (para una pseudométrica que proporciona metadatos sobre el objeto binario en ejecución)

  • Un nombre de métrica PUEDE ordenar sus componentes para facilitar la agrupación conveniente cuando se ordena lexicográficamente, siempre que se sigan todas las demás reglas. Las métricas relacionadas suelen tener componentes de nombre comunes que se colocan primero para garantizar que se ordenen juntas.

    Ejemplos:

    • prometheus_tsdb_head_truncations_closed_total
    • prometheus_tsdb_head_truncations_established_total
    • prometheus_tsdb_head_truncations_failed_total
    • prometheus_tsdb_head_truncations_total

  • Un nombre de métrica DEBERÍA representar de manera coherente la misma "cosa que se mide" lógica en todas las dimensiones de las etiquetas.

    Ejemplos:

    • duración de la solicitud
    • bytes de transferencia de datos
    • Uso instantáneo de recursos como un porcentaje

Lineamientos para asignar nombres a las etiquetas

Cuando midas algo, usa etiquetas para distinguir sus características. Por ejemplo:

  • Para el total de solicitudes HTTP a la API (api_http_requests_total), diferencia por tipo de operación, por ejemplo, create, update, delete (tipos de solicitud: operation="create|update|delete").
  • Para la duración de la solicitud a la API en segundos (api_request_duration_seconds), diferencia por etapa de la solicitud, por ejemplo, extract, transform, load (etapas de la solicitud: stage="extract|transform|load").

Evita incluir nombres de etiquetas en el nombre de la métrica, ya que esto genera redundancia y puede causar confusión si esas etiquetas se agregan más adelante.