Esta publicación explica cómo los endpoints de búsqueda, descubrimiento y metadatos se basan en el trabajo anterior de ingesta y búsqueda para formar esa superficie de API. Las publicaciones complementarias profundizan en las piezas individuales:

• La compatibilidad nativa con PromQL en ES|QL explica cómo se traducen las consultas PromQL en planes de ejecución de ES|QL.

• Envía métricas de Prometheus a Elasticsearch con Remote Write cubre la configuración de ingesta.

• El artículo “Cómo funciona la ingesta de escritura remota de Prometheus en Elasticsearch” explica los detalles internos de la escritura remota.

Esto aún está en desarrollo. En las secciones siguientes se indica qué es lo que ya está disponible y qué partes aún están en desarrollo.

La superficie de la API

Hoy en día, la interfaz de programación de aplicaciones (API) compatible con Prometheus se divide en tres grupos.

Endpoints de consulta

Los endpoints de consulta permiten a los clientes compatibles con Prometheus evaluar expresiones PromQL:

• GET /_prometheus/api/v1/query_range evalúa una expresión PromQL en un intervalo de tiempo (resultados en forma de matriz).

• GET /_prometheus/api/v1/query evalúa en un solo punto en el tiempo (resultados vectoriales). Actualmente implementado como una búsqueda de alcance corto que devuelve la última muestra.

Hoy en día, solo GET es compatible con los puntos de consulta. Algunos clientes usan POST de forma predeterminada, así que es posible que tengas que configurarlos para que usen GET. La convención POST de Prometheus emplea application/x-www-form-urlencoded cuerpos, que la capa HTTP de Elasticsearch rechaza como salvaguarda CSRF antes de que la solicitud llegue al controlador.

Para ver el estado completo de la cobertura de PromQL, consulta la publicación complementaria sobre PromQL en ES|QL.

Endpoints de metadatos

Los endpoints de metadatos proporcionan la información de descubrimiento que los clientes necesitan para el autocompletado, los desplegables de variables y la navegación de métricas.

La serie, las etiquetas y los puntos finales de valores de etiqueta aceptan selectores match[] y un rango de tiempo (start/end). El parámetro match[] toma un selector de serie de Prometheus como http_requests_total{job="api"} y restringe la respuesta a series temporales que coinciden. Esto garantiza que las respuestas sean rápidas y pertinentes en clústeres con una gran cantidad de métricas. Por ejemplo:

La primera devuelve todas las series para http_requests_total donde job="api", con sus conjuntos de etiquetas completos. La segunda devuelve solo los nombres de las etiquetas que existen en las series de http_requests_total. El tercero solo devuelve los valores de instance que aparecen en las series coincidentes.

GET /_prometheus/api/v1/metadata es diferente: devuelve el tipo y la unidad para cada métrica, opcionalmente filtrados por nombre mediante un parámetro metric.

No acepta match[] selectores ni un intervalo de tiempo. En Prometheus, los metadatos se recogen de objetivos activos de extracción (las líneas HELP, TYPE y UNIT que exponen), por lo que la respuesta no implica un escaneo de datos. Elasticsearch no tiene un almacén de metadatos dedicado como ese, por lo que la implementación actual descubre metadatos de métricas visitando datos temporales de las últimas 24 horas. Esto mantiene la consulta rápida sin requerir un escaneo completo del índice. Ese retroceso de 24 horas está corregido hoy: la API de metadatos de Prometheus no expone los parámetros start o end que Elasticsearch podría usar para que sean ajustables por el usuario.

Cómo funcionan los endpoints de metadatos de forma interna, incluidos los comandos TS_INFO y METRICS_INFO que los potencian, se explica a continuación.

Pre-filtrado de índices

Todos los endpoints de consulta y metadato aceptan un segmento de ruta {index} opcional después de /_prometheus/:

Esto limita los índices de Elasticsearch contra los que se ejecuta la consulta antes de que comience la evaluación de cualquier expresión. En clústeres con muchos flujos de datos entre equipos o entornos, esto evita escanear índices no relacionados y puede reducir en gran medida la latencia de las consultas. Puedes configurar fuentes de datos independientes por patrón de índice para dar a los equipos acceso limitado a sus propias métricas.

Una nota sobre Remote Write

Para la ingesta, Elasticsearch también expone el endpoint estándar de escritura remota de Prometheus:

• POST /_prometheus/api/v1/write ingiere series temporales a través del protocolo Prometheus Remote Write v1. v2 aún no es compatible.

La escritura remota escribe en los flujos de datos temporales existentes (TSDS) de Elasticsearch, no en una capa de almacenamiento específica de Prometheus separada. Las etiquetas de Prometheus se convierten en dimensiones de TSDS, y los nombres de las métricas se convierten en campos en el mapeo del índice. La publicación de arquitectura de escritura remota abarca todo el mapeo en detalle, incluso explica cómo se infieren los tipos de métricas y cómo se almacenan las etiquetas con un prefijo labels..

Cómo funciona

Detrás de escena, todos los endpoints funcionan de la misma manera: parsean los parámetros HTTP entrantes, construyen un plan de consulta ES|QL, lo ejecutan contra los flujos de datos de series temporales y convierten el resultado columnar de vuelta al formato JSON que esperan los clientes de Prometheus.

TS_INFO y METRICS_INFO

Los endpoints de metadatos deben responder preguntas como "¿qué etiquetas existen?" o "¿qué tipos de métricas están definidos?" a través de lo que podrían ser millones de series temporales, sin tener que analizar cada punto de datos.

A nivel interno, los endpoints de metadatos de Prometheus responden a esas preguntas construyendo planes de ES|QL basados en dos nuevos comandos de procesamiento: METRICS_INFO y TS_INFO. No es necesario usar estos comandos directamente para usar la API de Prometheus, pero son las primitivas de ejecución del núcleo detrás de las respuestas de metadatos. Ambos funcionan visitando solo un documento por serie temporal para extraer su metadato, en vez de escanear todas las muestras. Esto significa que su costo varía en función de la cantidad de series temporales distintas, no de la cantidad de puntos de datos.

METRICS_INFO devuelve una fila por cada métrica distinta, con su nombre, tipo, unidad y los campos de dimensión asociados. TS_INFO es más granular: una fila por combinación (métrica, serie temporal), incluyendo los valores de dimensión reales como un objeto JSON.

Muy pronto llegará una publicación de blog especial sobre TS_INFO y METRICS_INFO que cubrirá el modelo de ejecución en dos fases, cómo escalan y cómo usarlos directamente en consultas de ES|QL por fuera de la API de Prometheus.

Cómo los endpoints de metadatos los emplean

Cada endpoint de metadatos construye un ES|QL plan con uno de estos comandos como núcleo.

/api/v1/labels y /api/v1/series usan TS_INFO, ya que necesitan detalles por serie temporal (qué etiquetas existen, qué valores de dimensión identifican cada serie). /api/v1/metadata y /api/v1/label/__name__/values usan METRICS_INFO, ya que solo necesitan información por métrica (nombres de métricas, tipos, unidades).

/api/v1/label/{name}/values para etiquetas normales (cualquier otra cosa que no sea __name__), no se usa ninguno de los dos comandos. Algunas etiquetas regulares como job o instance son campos dimensionales reales en el índice, por lo que el endpoint puede consultarlos directamente mediante una agregación según grupo. Cuando se proporcionan selectores match[], se traducen en una cláusula WHERE que filtra la serie temporal antes de que se ejecute la agregación.

La etiqueta __name__ necesita una estrategia diferente porque no siempre está presente como un campo dimensional. Prometheus Remote Write sí almacena labels.__name__, pero las métricas ingeridas por otros caminos (OpenTelemetry, la API de bulk) no la tienen. El nombre de la métrica está codificado en el propio nombre del campo (por ejemplo, metrics.http_requests_total). Podrías consultar las asignaciones de índices para enumerar los nombres de los campos, pero las asignaciones por sí solas no te dicen qué métrica tiene qué dimensiones, y no se pueden filtrar por valores de etiquetas de un selector match[]. METRICS_INFO puede hacer ambas cosas: enumera los nombres de las métricas en los índices mientras respeta los filtros WHERE upstream.

En todos los casos, la capa API gestiona la traducción de vuelta a las convenciones de Prometheus: eliminando los prefijos de almacenamiento labels. y metrics. y sintetizando __name__ para métricas no Prometheus que carecen de ellas.

En conclusión

El resultado: cualquier cliente compatible con Prometheus puede buscar y explorar métricas de Elasticsearch a través de endpoints que ya entiende. Las métricas de Remote Write así como las de OpenTelemetry y las métricas indexadas a través de otras rutas aparecen todas a través de la misma API, respaldadas por los mismos índices TSDS.

Todas las API de Prometheus que se mencionan aquí ya están disponibles como versión preliminar técnica en Elasticsearch Serverless. Para clústeres autogestionados y despliegues alojados de Elastic Cloud Hosted, disponibles como vista previa técnica en Elasticsearch 9.4, con la excepción de GET /_prometheus/api/v1/metadata. Para probarlo a nivel local, usa start-local.