Dieser Beitrag erklärt, wie die Abfrage-, Discovery- und Metadaten-Endpunkte auf der früheren Ingest- und Abfragearbeit aufbauen, um diese API-Oberfläche zu formen. In Begleitbeiträgen werden einzelne Aspekte näher beleuchtet:

• Native PromQL-Unterstützung in ES|QL beschreibt, wie PromQL-Abfragen in ES|QL-Ausführungspläne übersetzt werden.

• Prometheus-Metriken mit Remote Write an Elasticsearch versenden behandelt die Einrichtung der Ingestion.

• So funktioniert die Prometheus Remote Write Ingestion in Elasticsearch behandelt die internen Abläufe von Remote Write.

Dieses Projekt läuft noch. In den folgenden Abschnitten wird aufgeführt, was derzeit unterstützt wird und welche Teile sich noch in der Entwicklung befinden.

Die API-Oberfläche

Heute fällt die Prometheus-kompatible API-Oberfläche in drei Gruppen.

Abfrage-Endpoints

Die Abfrage-Endpoints ermöglichen Prometheus-kompatiblen Clients die Auswertung von PromQL-Ausdrücken:

• GET /_prometheus/api/v1/query_range wertet einen PromQL-Ausdruck über ein Zeitfenster aus (Matrix-Ergebnisse).

• GET /_prometheus/api/v1/query wertet zu einem einzelnen Zeitpunkt aus (Vektor-Ergebnisse). Derzeit als Kurzbereichsabfrage implementiert, die die letzte Stichprobe zurückgibt.

Aktuell wird nur GET als Abfrage-Endpoint unterstützt. Einige Clients verwenden standardmäßig POST, so dass Sie sie möglicherweise auf GET umstellen müssen. Die Prometheus POST-Konvention verwendet application/x-www-form-urlencoded-Bodies, die von der HTTP-Schicht von Elasticsearch als CSRF-Schutzmaßnahme abgelehnt werden, bevor die Anfrage überhaupt den Handler erreicht.

Den vollständigen PromQL-Abdeckungsstatus finden Sie im Begleitbeitrag zu PromQL in ES|QL.

Metadaten-Endpoints

Die Metadaten-Endpoints liefern die Discovery-Informationen, die Kunden für Autovervollständigung, Variablen-Dropdowns und das Durchsuchen von Metriken benötigen.

Die Endpunkte für Serien, Labels und Labelwerte akzeptieren alle match[]-Selektoren und einen Zeitbereich (start/end). Der Parameter match[] nimmt einen Prometheus-Serienselektor wie http_requests_total{job="api"} entgegen und beschränkt die Reaktion auf passende Zeitreihen. Dadurch bleiben die Reaktionen auf Clustern mit einer großen Anzahl von Metriken schnell und relevant. Zum Beispiel:

Die erste gibt alle Serien für http_requests_total zurück, wobei job="api" gilt, zusammen mit ihren vollständigen Label-Sets. Die zweite gibt nur die Label-Namen zurück, die in der http_requests_total-Serie existieren. Die dritte gibt nur die instance Werte zurück, die in übereinstimmenden Reihen vorkommen.

GET /_prometheus/api/v1/metadata ist anders: Pro Metrik werden nur Typ und Einheit zurückgegeben, optional gefiltert nach Namen über einen metric-Parameter.

match[]-Selektoren oder ein Zeitbereich werden nicht akzeptiert. In Prometheus werden Metadaten von aktiven Scrape-Zielen gesammelt (die Zeilen HELP, TYPE und UNIT, die sie anzeigen), sodass die Reaktion keinen Datenscan beinhaltet. Elasticsearch verfügt über keinen dedizierten Metadatenspeicher dieser Art, daher ermittelt die aktuelle Implementierung Metrik-Metadaten, indem sie Zeitreihendaten der letzten 24 Stunden durchsucht. Dadurch bleibt die Abfrage schnell, ohne dass ein vollständiger Indexscan erforderlich ist. Diese 24-Stunden-Rückschau ist derzeit fest vorgegeben: Die Prometheus-Metadaten-API stellt keine start- oder end-Parameter zur Verfügung, die Elasticsearch verwenden könnte, um sie für den Nutzer anpassbar zu machen.

Wie die Metadaten-Endpunkte im Hintergrund funktionieren, einschließlich der Befehle TS_INFO und METRICS_INFO, auf denen sie basieren, wird im Folgenden erläutert.

Index-Vorfilterung

Alle Abfrage- und Metadaten-Endpoints akzeptieren ein optionales {index}-Pfadsegment nach /_prometheus/:

Dies schränkt ein, gegen welche Elasticsearch-Indizes die Abfrage ausgeführt wird, bevor mit der Auswertung des Ausdrucks begonnen wird. In Clustern mit vielen Datenströmen, die sich über Teams oder Umgebungen erstrecken, verhindert dies das Durchsuchen irrelevanter Indizes und kann die Latenz bei Abfragen erheblich verringern. Sie können pro Indexmuster separate Datenquellen konfigurieren, um Teams gezielten Zugriff auf ihre eigenen Metriken zu gewähren.

Eine Anmerkung zum Remote Write

Für die Ingestion stellt Elasticsearch auch den standardmäßigen Prometheus Remote Write-Endpoint bereit:

• POST /_prometheus/api/v1/write nimmt Zeitreihen über das Prometheus Remote Write v1-Protokoll auf. v2 wird noch nicht unterstützt.

Remote Write schreibt in die bestehenden Zeitreihendatenströme (TSDS) von Elasticsearch und nicht in eine separate, Prometheus-spezifische Speicherschicht. Prometheus-Labels werden zu TSDS-Dimensionen, und Metriknamen werden zu Feldern im Index-Mapping. Der Beitrag zur Architektur von Remote Write behandelt das vollständige Mapping im Detail, einschließlich der Ableitung von Metriktypen und der Speicherung von Labels mit einem labels.-Präfix.

So funktionierts

Im Hintergrund funktionieren alle Endpoints auf die gleiche Weise: Sie parsen die eingehenden HTTP-Parameter, erstellen einen ES|QL-Abfrageplan, führen ihn für Zeitreihendatenströme aus und konvertieren das spaltenorientierte Ergebnis zurück in das von Prometheus-Clients erwartete JSON-Format.

TS_INFO und METRICS_INFO

Die Metadaten-Endppoints müssen Fragen beantworten wie „Welche Labels existieren?“ oder „Welche Metriktypen sind definiert?“, und das über potenziell Millionen von Zeitreihen hinweg, ohne jeden einzelnen Datenpunkt zu prüfen.

Intern beantworten die Prometheus-Metadaten-Endpoints diese Fragen, indem sie ES|QL-Pläne um zwei neue Verarbeitungsbefehle erstellen: METRICS_INFO und TS_INFO. Sie müssen diese Befehle nicht direkt verwenden, um die Prometheus-API zu nutzen, doch sie bilden die Kernausführungsprimitive hinter den Metadatenantworten. Beide funktionieren, indem sie nur ein Dokument pro Zeitreihe aufrufen, um dessen Metadaten zu extrahieren, anstatt alle Stichproben zu scannen. Das bedeutet, dass sich ihre Kosten proportional zur Anzahl der einzelnen Zeitreihen und nicht zur Anzahl der Datenpunkte verhalten.

METRICS_INFO gibt eine Zeile pro eindeutiger Metrik mit ihrem Namen, Typ, Einheit und zugehörigen Dimensionsfeldern zurück. TS_INFO ist detaillierter: eine Zeile pro Kombination aus Metrik und Zeitreihe, einschließlich der tatsächlichen Dimensionswerte als JSON-Objekt.

Ein eigener Blogbeitrag zu TS_INFO und METRICS_INFO folgt in Kürze. Er behandelt das zweiphasige Ausführungsmodell, wie sie skaliert werden und wie sie direkt in ES|QL-Abfragen außerhalb der Prometheus-API verwendet werden können.

So werden sie von den Metadaten-Endpoints verwendet

Jeder Metadaten-Endpoint konstruiert einen ES|QL-Plan mit einem dieser Befehle im Kern.

/api/v1/labels und /api/v1/series verwenden TS_INFO, da sie detaillierte Daten pro Zeitreihe benötigen (welche Labels existieren, welche Dimensionswerte jede Reihe identifizieren). /api/v1/metadata und /api/v1/label/__name__/values verwenden METRICS_INFO, da sie nur Informationen pro Metrik benötigen (Metriknamen, Typen, Einheiten).

/api/v1/label/{name}/values Für reguläre Labels (alles außer __name__) wird keiner der beiden Befehle verwendet. Reguläre Labels wie job oder instance sind tatsächliche Dimensionsfelder im Index, sodass der Endpoint sie direkt mit einer Gruppenaggregation abfragen kann. Wenn match[] Selektoren bereitgestellt werden, werden sie in eine WHERE-Klausel übersetzt, die die Zeitreihen filtert, bevor die Aggregation ausgeführt wird.

Das __name__-Label erfordert eine andere Strategie, da es nicht immer als Dimensionsfeld vorhanden ist. Prometheus Remote Write speichert labels.__name__, aber Metriken, die über andere Pfade (OpenTelemetry, die Bulk-API) aufgenommen werden, enthalten es nicht. Der metrische Name ist im Feldnamen selbst kodiert (z. B. metrics.http_requests_total). Sie könnten sich die Index-Mappings ansehen, um die Feldnamen aufzulisten, aber Mappings allein geben keinen Aufschluss darüber, welche Metrik welche Dimensionen aufweist, und sie lassen sich nicht nach Labelwerten aus einem match[]-Selektor filtern. METRICS_INFO kann beides: Es zählt Metriknamen über Indizes auf, während es Upstream-Filter WHERE berücksichtigt.

In allen Fällen übernimmt die API-Ebene die Rückübersetzung in die Prometheus-Konventionen: indem sie die Speicherpräfixe labels. und metrics. entfernt und __name__ für Nicht-Prometheus-Metriken ergänzt, denen ein solches Präfix fehlt.

Fazit

Das Ergebnis: Jeder Prometheus-kompatible Client kann Elasticsearch-Metriken über bereits verstehende Endpunkte abfragen und erkunden. Remote Write-Metriken, OpenTelemetry-Metriken und Metriken, die über andere Pfade indiziert werden, werden alle über dieselbe API angezeigt, die von denselben TSDS-Indizes unterstützt wird.

Alle hier erwähnten Prometheus-APIs sind heute als technische Vorschau in Elasticsearch Serverless verfügbar. Für selbstverwaltete Cluster und Elastic Cloud Hosted Deployments, verfügbar als technische Vorschau in Elasticsearch 9.4, mit Ausnahme von GET /_prometheus/api/v1/metadata. Um lokal zu experimentieren, verwenden Sie start-local.