PromQL verwenden

Verwenden Sie die Prometheus Query Language (PromQL), um Zeitreihen-Metrikdaten für Prometheus auszuwählen und zu aggregieren.

Weitere Informationen zu PromQLfinden Sie in der Open-Source-Dokumentation.

Eine PromQL-Abfrage erstellen

Erstellen Sie eine PromQL-Abfrage für eine Metrik in einem vorhandenen Dashboard.

Klicken Sie im Überwachungsdashboardauf Dashboard öffnen für Ihre Serviceinstanz.
Wählen Sie aus Dashboards das Dashboard aus, das die Metriken enthält, die Sie abfragen möchten.
Klicken Sie für eine Anzeige im Dashboard auf das Symbol Bearbeiten.
Wählen Sie den PromQL-Abfragetyp aus.
Geben Sie im Abfrageformular Daten zur Anzeige ein, z. B. den Namen der Abfrage und der Zeitreihe.
Geben Sie Ihre PromQL-Abfrage ein, wie z. B. avg(avg_over_time(host_cpu_used_percent[$__interval])) by(kubernetes_cluster_name). Geben Sie die folgenden Felder in Ihrer Abfrage an:
- Metrik: Geben Sie die Metrik an, die Sie abfragen möchten, z. B. host_cpu_used_percent. Hinweis: Die generierten Werte in der Tabelle sind die aktuellste Metrik.
- Zeitbereich: Geben Sie einen Zeitbereich oder ein Zeitintervall an, z. B. 5m. Um den Zeitbereich zu verwenden, der in der Benutzeroberfläche ausgewählt ist, geben Sie $__range an. Um das Zeitintervall zu verwenden, das auf dem Zeitbereich basiert, der in der Benutzeroberfläche ausgewählt ist, geben Sie $__interval an. Die Variablen $__range und $__interval in dieser Abfrage werden automatisch aktualisiert, wenn der Zeitbereich in der Benutzeroberfläche geändert wird. Weitere Informationen finden Sie unter Anwenden von Dashboard-Bereichen auf PromQL-Abfragen.
- Segmentierung: Wählen Sie einen Wert zur Segmentierung der aggregierten PromQL-Daten, z. B. kubernetes_cluster_name.
Klicken Sie auf Abfrage ausführen.
Optimieren Sie die Ergebnisse, indem Sie zusätzliche Optionen konfigurieren, wie z. B. die Einheiten, in denen die Daten zurückgegeben werden, und die Art, wie die Daten angezeigt werden.

Dashboard-Geltungsbereiche anwenden

Um ein Panel, das aus einer PromQL-Abfrage erstellt wurde, in den ScopeGeltungsbereich zu nehmen, müssen Sie eine Geltungsbereichsvariable innerhalb der Abfrage verwenden.

Für zeitbasierte Geltungsbereiche gibt es zwei vordefinierte Variablen, die Sie in der Abfrage angeben können. Diese Variablen werden automatisch aktualisiert, wenn der Zeitbereich für die gestrichelte Linie in der Benutzeroberfläche geändert wird.

$__range: Stellt den Zeitrahmen dar, der in der Dashboard-Benutzeroberfläche ausgewählt ist. Sie könnten diese Variable z. B. verwenden, um einen Durchschnitt für den ausgewählten Zeitrahmen zu berechnen.
$__interval: Stellt das Intervall dar, das auf dem Zeitbereich basiert, der in der Dashboard-Benutzeroberfläche ausgewählt ist. Sie können diese Variable z. B. verwenden, um den Zeitbereich für verschiedene Operationen anzupassen, wie z. B. die Rate oder den Durchschnitt über die Zeit.

Angenommen, Sie verwenden die folgende Abfrage, um die CPU-Auslastung in Prozent für alle Hosts zurückzugeben:

avg_over_time(host_cpu_used_percent[$__interval])

Diese Abfrage verwendet die Variable $__interval, die die Daten auf das dynamische Zeitintervall basierend auf dem Zeitbereich, der in der Dashboard-Benutzeroberfläche ausgewählt ist, ausdehnt.

Sie können auch Ihre eigenen Variablen in der Abfrage angeben, um die Ausgabe zu erweitern. Um beispielsweise die vorherige Abfrage auf eine bestimmte Bezeichnung wie hostname zu begrenzen, müssen Sie zuerst eine Bereichsvariable auf Dashboardebene definieren. Dann können Sie diese Variable in der Abfrage angeben:

avg_over_time(host_cpu_used_percent{host_name=$hostname}[$__interval])

Kennsätze verwenden

Wenn Sie PromQL-Abfragen ausführen, werden die Daten mit einem minimalen Satz von Kennsätzen zurückgegeben. Um weitere Kennlsätze, z. B. einen Clusternamen, hinzuzufügen, verwenden Sie eine Vektorvergleichsoperation.

Prometheus gibt Informationsmetriken zurück, die den Wert 1 mit mehreren Bezeichnungen aufweisen. Die Verknüpfung der Bezeichnungen einer Informationsmetrik mit einer andersartigen Metrik kann nützliche Erkenntnisse liefern, z. B. den Wert einer Metrik in einer Anwendung. Sie können eine Vektorabgleichsoperation verwenden, die einer SQL-Join ähnelt, um die Informationskennsätze zu Ihren metrischen Daten hinzuzufügen.

Beispiel: Filtern einer Anwendungsmetrik nach Clustern

In diesem Beispiel wird eine Metrik, die von einer Anwendung zurückgegeben wird, nach Clustern gefiltert. Die PromQL aggregiert einen Wert dieser Metrik für einen Cluster, indem sie nur einen Cluster im Geltungsbereich ausgewählt hat.

sum (myapp_metric * on (container_id) kube_pod_container_info{cluster=$cluster})

Diese Abfrage:

Filtert die Informationsmetrik kube_pod_container_info nur für einen bestimmten Cluster ($cluster, der als Dashboard-Variable festgelegt wird) basierend auf dem cluster-Kennsatz und für eine bestimmte Zeitreihe.
Passt die Nicht-Informationsmetrik myapp_metric an die gefilterte Informationsmetrik kube_pod_container_info an, wenn der Kennsatz container_id den gleichen Wert hat. Die Werte werden multipliziert, aber da die Informationsmetrik einen Wert von 1 hat, bleibt das Ergebnis unverändert. Der Cluster-Kennsatz wird zu den resultierenden Daten hinzugefügt.
Aggregiert die Zeitreihe des Wertes myapp_metric mithilfe der Funktion sum und gibt das Ergebnis zurück.

Beispiel: Filtern der durchschnittlich genutzten CPU nach Konto und Region

In diesem Beispiel wird die durchschnittliche CPU-Auslastung (Prozent) für ein bestimmtes IBM Cloud-Konto und eine bestimmte Region berechnet.

avg by(region,account_id) (host_cpu_used_percent * on (host_mac) group_left(region,account_id) sysdig_cloud_provider_info{account_id=~$account, region=~$region})

Diese Abfrage:

Filtert die Informationsmetrik sysdig_cloud_provider_info nur für eine bestimmte Region ($region) und ein bestimmtes Konto ($account), die als Dashboard-Variablen basierend auf den Kennsätzen region und account_id festgelegt sind.
Passt die Nicht-Informationsmetrik host_cpu_used_percent an die gefilterte Informationsmetrik sysdig_cloud_provider_info an, wenn der Kennsatz host_mac den gleichen Wert hat. Die Werte werden multipliziert, aber da die Informationsmetrik einen Wert von 1 hat, bleibt das Ergebnis unverändert. Die Regions- und die Kontokennsätze werden zu den resultierenden Daten hinzugefügt.
Berechnet den Durchschnitt der neuen Metriken nach Konto und Region.

cURL-Beispiel zum Extrahieren der letzten Metrik

Um den neuesten Wert einer Metrik zu erhalten, geben Sie nur den Namen der Metrik an. Es wird der letzte Wert zurückgegeben, der vor maximal 5 Minuten generiert wurde.

Zum Beispiel, um den letzten Wert von host_cpu_used_percent zu erhalten:

curl <SYSDIG_REST_API_ENDPOINT>/prometheus/api/v1/query?query=sysdig_host_cpu_used_percent -H "Authorization: $AUTH_TOKEN" -H "IBMInstanceID: $GUID" -H "SysdigTeamID: $TEAM_ID" -H "content-type: application/json"

<SYSDIG_REST_API_ENDPOINT> gibt den Endpunkt an, den der REST-API-Aufruf zum Ziel hat. Weitere Informationen finden Sie unter Monitoring-REST-API-Endpunkte. Der öffentliche Endpunkt für eine Instanz, die in der Region 'us-south' verfügbar ist, ist beispielsweise folgender: https://us-south.monitoring.cloud.ibm.com/api
Sie können mehrere Header übergeben, indem Sie -H verwenden.

Authorization und IBMInstanceID sind Header, die für die Authentifizierung erforderlich sind.

Der Header SysdigTeamID ist optional. Wenn Sie diesen Header angeben, begrenzen Sie die Anforderung auf die Daten und Ressourcen, die für das angegebene Team verfügbar sind.

Informationen zum Abrufen eines Autorisierungstokens (AUTH_TOKEN) und der GUID finden Sie unter Header für IAM-Tokens.

Alle Dashboards unterstützen die vollständige PromQL-API. Weitere Informationen zu den möglichen Möglichkeiten mit PromQLfinden Sie in der Dokumentation zuPrometheus.