Cet article explique comment les endpoints de requête, de découverte et de métadonnées s’appuient sur les travaux d’ingestion et de requête antérieurs pour former cette surface API. Les articles connexes vont plus loin sur les éléments spécifiques :

• La prise en charge native de PromQL dans ES|QL couvre la manière dont les requêtes PromQL sont traduites en plans d’exécution ES|QL.

• Transférer des métriques Prometheus à Elasticsearch avec Remote Write couvre la configuration de l’ingestion.

• Comment fonctionne l'ingestion d'écriture à distance de Prometheus dans Elasticsearch couvre les aspects internes de l'écriture à distance.

Ce travail est encore en cours. Les sections ci-dessous indiquent ce qui est actuellement pris en charge et quelles parties évoluent encore.

La surface de l'API

Aujourd’hui, les interfaces API compatibles avec Prometheus se répartissent en trois catégories.

Endpoints de requête

Les endpoints de requête permettent aux clients compatibles avec Prometheus d’évaluer les expressions PromQL :

• GET /_prometheus/api/v1/query_range évalue une expression PromQL sur une fenêtre de temps (résultats matriciels).

• GET /_prometheus/api/v1/query évalue à un instant donné (résultats vectoriels). Actuellement implémenté en tant que requête à courte portée qui renvoie le dernier échantillon.

Seul GET est pris en charge pour les endpoints de requête actuellement. Certains clients utilisent par défaut la méthode POST. Vous devrez peut-être les configurer pour utiliser la méthode GET. La convention Prometheus POST utilise des corps application/x-www-form-urlencoded, que la couche HTTP d’Elasticsearch rejette comme protection CSRF avant que la requête n’atteigne le gestionnaire.

Pour connaître l’état complet de la couverture de PromQL, consultez l’article connexe sur PromQL dans ES|QL.

Points de terminaison des métadonnées

Les endpoints de métadonnées fournissent les informations de découverte dont les clients ont besoin pour l’autocomplétion, les listes déroulantes de variables et la navigation dans les métriques.

Les endpoints des séries, des étiquettes et des valeurs d’étiquette acceptent tous les sélecteurs match[] et une plage de temps (start/end). Le paramètre match[] prend un sélecteur de série Prometheus comme http_requests_total{job="api"} et limite la réponse aux séries temporelles qui correspondent. Les réponses restent ainsi rapides et pertinentes sur les clusters comportant un grand nombre de métriques. Par exemple :

La première renvoie toutes les séries pour http_requests_total où job="api", avec leurs ensembles d’étiquettes complets. La seconde renvoie uniquement les noms des étiquettes qui existent sur les séries http_requests_total. Le troisième renvoie uniquement les valeurs de instance qui apparaissent sur les séries correspondantes.

GET /_prometheus/api/v1/metadata est différent : il retourne le type et l’unité pour chaque métrique, éventuellement filtrés par nom via un paramètre metric.

Il n’accepte pas les sélecteurs match[] ni aucune plage horaire. Dans Prometheus, les métadonnées sont collectées à partir de cibles de scrape actives (les lignes HELP, TYPE et UNIT qu’elles exposent). La réponse n’implique donc pas de scan des données. Elasticsearch ne dispose pas d’un dépôt dédié de métadonnées comme celui-ci, donc l’implémentation actuelle découvre les métadonnées des métriques en visitant les données temporelles des dernières 24 heures. Cela permet de maintenir la rapidité de la requête sans nécessiter un balayage complet de l’index. Cette analyse en 24 heures est aujourd’hui corrigée : l’API de métadonnées Prometheus ne divulgue pas les paramètres start ni end qu’Elasticsearch pourrait utiliser pour la rendre ajustable par l’utilisateur.

Le fonctionnement des endpoints des métadonnées, y compris les commandes TS_INFO et METRICS_INFO qui les alimentent, est expliqué ci-dessous.

Index de pré-filtrage

Tous les endpoints de requête et de métadonnées acceptent un segment de chemin {index} optionnel après /_prometheus/ :

Il limite les index Elasticsearch sur lesquels la requête est en exécution avant le début de toute évaluation d’expression. Sur les clusters comportant de nombreux flux de données entre équipes ou environnements, cela évite de scanner des index non pertinents et peut réduire de manière significative la latence des requêtes. Vous pouvez configurer des sources de données distinctes par modèle d’indexation afin de fournir aux équipes un accès limité à leurs propres métriques.

Remarque sur Remote Write

Pour l’ingestion, Elasticsearch expose également l’endpoint standard Prometheus Remote Write :

• POST /_prometheus/api/v1/write ingère des séries temporelles via le protocole Prometheus Remote Write v1. v2 n’est pas encore pris en charge.

Remote Write écrit dans les flux de données temporelles existants d’Elasticsearch (TSDS), et non dans une couche de stockage spécifique à Prometheus. Les étiquettes Prometheus deviennent des dimensions TSDS, et les noms des métriques deviennent des champs dans le mapping des index. L’article sur l’architecture de l’écriture à distance couvre le mapping complet en détail, notamment comment les types de métriques sont déduits et comment les étiquettes sont stockées avec un préfixe labels..

Fonctionnement

En interne, tous les endpoints fonctionnent de la même manière : ils analysent les paramètres HTTP entrants, construisent un plan de requête ES|QL, l’exécutent sur des flux de données temporelles et convertissent le résultat en colonnes au format JSON attendu par les clients Prometheus.

TS_INFO et METRICS_INFO

Les endpoints des métadonnées doivent répondre à des questions telles que « quelles étiquettes existent ? » ou « quels types de métriques sont définis ? » sur des millions de séries temporelles, sans analyser chaque point de données.

En interne, les endpoints de métadonnées Prometheus répondent à ces questions en construisant des plans ES|QL autour de deux nouvelles commandes de traitement : METRICS_INFO et TS_INFO. Vous n’avez pas besoin d’utiliser ces commandes directement pour utiliser l’API Prometheus, mais elles constituent les primitives d’exécution fondamentales qui sous-tendent les réponses aux métadonnées. Toutes deux fonctionnent en ne visitant qu’un seul document par série temporelle pour extraire ses métadonnées, plutôt que de parcourir tous les échantillons. Cela signifie que leur coût évolue avec le nombre de séries temporelles distinctes, et non en fonction du nombre de points de données.

METRICS_INFO renvoie une ligne par métrique distincte avec son nom, son type, son unité et ses champs de dimension associés. TS_INFO est plus granulaire : une ligne par combinaison (métrique, série temporelle), incluant les valeurs réelles des dimensions en tant qu'objet JSON.

Un article de blog dédié à TS_INFO et METRICS_INFO sera bientôt publié, abordant le modèle d’exécution en deux phases, la façon dont ils s’adaptent et la façon de les utiliser directement dans les requêtes ES|QL au-delà de l’API Prometheus.

Comment les points de terminaison des métadonnées les utilisent

Chaque endpoint des métadonnées construit un plan ES|QL avec l’une de ces commandes à son noyau.

/api/v1/labels et /api/v1/series utilisent TS_INFO, car ils ont besoin de détails par série temporelle (quelles étiquettes existent, quelles valeurs de dimension identifient chaque série). /api/v1/metadata et /api/v1/label/__name__/values utilisent METRICS_INFO, car ils n’ont besoin que d’informations métriques (noms, types et unités métriques).

/api/v1/label/{name}/values pour les étiquettes ordinaires (autres que __name__), n’utilisez aucune des deux commandes. Les étiquettes régulières comme job ou instance sont de véritables champs de dimensions dans l’index, de sorte que l’endpoint peut les interroger directement avec une agrégation group-by. Lorsque des sélecteurs match[] sont fournis, ils sont traduits en une clause WHERE qui filtre la série temporelle avant l’exécution de l’agrégation.

Le label __name__ nécessite une stratégie différente car il n’est pas toujours présent sous forme de champ de dimension. Prometheus Remote Write stocke labels.__name__, mais les mesures ingérées par d’autres voies (OpenTelemetry, l’API Bulk) ne les contiennent pas. Le nom de la métrique est encodé dans le nom même du champ (par exemple, metrics.http_requests_total). Vous pourriez consulter les correspondances d’index pour énumérer les noms des champs, mais les correspondances seules ne vous indiquent pas quelle métrique a quelles dimensions, et elles ne peuvent pas être filtrées par les valeurs d’étiquettes d’un sélecteur match[]. METRICS_INFO peut faire les deux : il énumère les noms des métriques dans les index tout en respectant les filtres WHERE en amont.

Dans tous les cas, la couche API gère la conversion vers les conventions Prometheus : elle supprime les préfixes de stockage labels. et metrics., et synthétise __name__ pour les métriques non-Prometheus qui en sont dépourvues.

Conclusion

Résultat : tout client compatible avec Prometheus peut interroger et explorer les métriques Elasticsearch par le biais d’endpoints qu’il comprend déjà. Les mesures d’écriture à distance, les mesures OpenTelemetry et les mesures indexées par d’autres chemins sont toutes affichées avec la même API et les mêmes index TSDS.

Toutes les API Prometheus mentionnées ici sont désormais disponibles en préversion technique dans Elasticsearch Serverless. Pour les clusters autogérés et les déploiements hébergés par Elastic Cloud Hosted, disponibles en préversion technique dans Elasticsearch 9.4, à l’exception de GET /_prometheus/api/v1/metadata. Pour expérimenter localement, utilisez start-local.