Pushgateway
1.10.0
Das Prometheus Pushgateway dient dazu, es flüchtigen und Batch-Jobs zu ermöglichen, ihre Metriken an Prometheus weiterzugeben. Da diese Art von Jobs möglicherweise nicht lange genug existieren, um gelöscht zu werden, können sie ihre Metriken stattdessen an ein Pushgateway übertragen. Das Pushgateway stellt diese Metriken dann Prometheus zur Verfügung.
Erstens ist das Pushgateway nicht in der Lage, Prometheus in ein Push-basiertes Überwachungssystem zu verwandeln. Eine allgemeine Beschreibung der Anwendungsfälle für das Pushgateway finden Sie unter Wann ist das Pushgateway zu verwenden?
Das Pushgateway ist ausdrücklich kein Aggregator oder verteilter Zähler , sondern ein Metrik-Cache. Es verfügt nicht über eine statsd-ähnliche Semantik. Die übertragenen Metriken sind genau die gleichen, die Sie beim Scraping in einem permanent laufenden Programm anzeigen würden. Wenn Sie eine verteilte Zählung benötigen, können Sie entweder den aktuellen statsd in Kombination mit dem Prometheus statsd-Exporter verwenden oder einen Blick auf das prom-aggregation-gateway werfen. Mit mehr gesammelter Erfahrung könnte das Prometheus-Projekt eines Tages möglicherweise eine native Lösung bereitstellen, getrennt vom Pushgateway oder möglicherweise sogar als Teil davon.
Für Metriken auf Maschinenebene ist der Textdatei-Kollektor des Node-Exporters normalerweise besser geeignet. Das Pushgateway ist für Service-Level-Metriken gedacht.
Das Pushgateway ist kein Event-Store . Während Sie Prometheus als Datenquelle für Grafana-Annotationen verwenden können, muss die Verfolgung von Release-Ereignissen mithilfe eines Frameworks zur Ereignisprotokollierung erfolgen.
Vor einiger Zeit haben wir beschlossen, kein „Timeout“ oder TTL für gepushte Metriken zu implementieren, da sich fast alle vorgeschlagenen Anwendungsfälle als Anti-Patterns herausstellten, von denen wir dringend abraten. Eine neuere Diskussion können Sie auf der Mailingliste prometheus-developers verfolgen.
Laden Sie Binärversionen für Ihre Plattform von der Release-Seite herunter und entpacken Sie den Tarball.
Wenn Sie sich aus den Quellen kompilieren möchten, benötigen Sie ein funktionierendes Go-Setup. Verwenden Sie dann das bereitgestellte Makefile (geben Sie make ein).
Für die einfachste Einrichtung starten Sie einfach die Binärdatei. Um die abzuhörende Adresse zu ändern, verwenden Sie das Flag --web.listen-address (z. B. „0.0.0.0:9091“ oder „:9091“). Standardmäßig behält Pushgateway keine Metriken bei. Mit dem Flag --persistence.file können Sie jedoch eine Datei angeben, in der die gepushten Metriken beibehalten werden (so dass sie Neustarts des Pushgateways überdauern).
Sie können das Pushgateway mithilfe des Docker-Images prom/pushgateway bereitstellen.
Zum Beispiel:
docker pull prom/pushgateway
docker run -d -p 9091:9091 prom/pushgateway Das Pushgateway muss mithilfe einer der üblichen Methoden als Ziel für Prometheus konfiguriert werden. Sie sollten jedoch immer honor_labels: true in der Scrape-Konfiguration setzen (eine detaillierte Erklärung finden Sie unten).
Prometheus-Clientbibliotheken sollten über eine Funktion verfügen, um die registrierten Metriken an ein Pushgateway zu übertragen. Normalerweise stellt ein Prometheus-Client passiv Metriken für das Scraping durch einen Prometheus-Server bereit. Eine Client-Bibliothek, die Pushing unterstützt, verfügt über eine Push-Funktion, die vom Client-Code aufgerufen werden muss. Anschließend werden die Metriken mithilfe der unten beschriebenen API aktiv an ein Pushgateway übertragen.
Mit dem Prometheus-Textprotokoll ist das Pushen von Metriken so einfach, dass keine separate CLI bereitgestellt wird. Verwenden Sie einfach ein Befehlszeilen-HTTP-Tool wie curl . Ihre bevorzugte Skriptsprache verfügt höchstwahrscheinlich über einige integrierte HTTP-Funktionen, die Sie auch hier nutzen können.
Beachten Sie, dass im Textprotokoll jede Zeile mit einem Zeilenvorschubzeichen (auch bekannt als „LF“ oder „n“) enden muss. Das Beenden einer Zeile auf andere Weise, z. B. mit „CR“, auch bekannt als „r“, „CRLF“, auch bekannt als „rn“, oder nur mit dem Ende des Pakets, führt zu einem Protokollfehler.
Gepushte Metriken werden in Gruppen verwaltet, die durch einen Gruppierungsschlüssel mit einer beliebigen Anzahl von Labels identifiziert werden, wobei das erste Label das job sein muss. Die Gruppen können bequem über die Weboberfläche eingesehen werden.
Informationen zu den Auswirkungen von Sonderzeichen in Beschriftungswerten finden Sie im Abschnitt „URL“ weiter unten.
Beispiele:
Schieben Sie ein einzelnes Beispiel in die durch {job="some_job"} identifizierte Gruppe:
echo "some_metric 3.14" | curl --data-binary @- http://pushgateway.example.org:9091/metrics/job/some_job
Da keine Typinformationen bereitgestellt wurden, wird some_metric vom Typ untyped sein.
Schieben Sie etwas Komplexeres in die durch {job="some_job",instance="some_instance"} identifizierte Gruppe:
cat <Beachten Sie, wie Typinformationen und Hilfezeichenfolgen bereitgestellt werden. Diese Zeilen sind optional, werden jedoch für komplexere Aufgaben dringend empfohlen.
Löschen Sie alle Metriken in der Gruppe, die durch {job="some_job",instance="some_instance"} identifiziert wird:
curl -X DELETE http://pushgateway.example.org:9091/metrics/job/some_job/instance/some_instance
Löschen Sie alle Metriken in der Gruppe, die durch {job="some_job"} identifiziert wird (beachten Sie, dass dies keine Metriken in der Gruppe {job="some_job",instance="some_instance"} aus dem vorherigen Beispiel einschließt, selbst wenn diese Metriken das haben gleiche Jobbezeichnung):
curl -X DELETE http://pushgateway.example.org:9091/metrics/job/some_job
Löschen Sie alle Metriken in allen Gruppen (erfordert die Aktivierung der Admin-API über das Befehlszeilen-Flag --web.enable-admin-api ):
curl -X PUT http://pushgateway.example.org:9091/api/v1/admin/wipe
Der Prometheus-Server fügt jeder gescrapten Metrik ein job -Label und ein instance -Label hinzu. Der Wert des job ergibt sich aus der Scrape-Konfiguration. Wenn Sie Pushgateway als Scrape-Ziel für Ihren Prometheus-Server konfigurieren, werden Sie wahrscheinlich einen Jobnamen wie pushgateway wählen. Der Wert der instance wird automatisch auf den Host und Port des gescrapten Ziels gesetzt. Daher haben alle vom Pushgateway erfassten Metriken den Host und den Port des Pushgateways als instance und eine job wie pushgateway . Der Konflikt mit den job und instance , die Sie möglicherweise an die an das Pushgateway übertragenen Metriken angehängt haben, wird durch Umbenennen dieser Bezeichnungen in exported_job und exported_instance gelöst.
Dieses Verhalten ist jedoch beim Scraping eines Pushgateways normalerweise unerwünscht. Im Allgemeinen möchten Sie die job und instance der an das Pushgateway übertragenen Metriken beibehalten. Deshalb müssen Sie in der Scrape-Konfiguration für das Pushgateway honor_labels: true setzen. Es ermöglicht das gewünschte Verhalten. Weitere Informationen finden Sie in der Dokumentation.
Damit bleibt uns der Fall, dass die an das Pushgateway übertragenen Metriken keine instance aufweisen. Dieser Fall kommt recht häufig vor, da sich die gepushten Metriken häufig auf einer Serviceebene befinden und sich daher nicht auf eine bestimmte Instanz beziehen. Selbst mit honor_labels: true fügt der Prometheus-Server ein instance hinzu, wenn zunächst kein instance festgelegt wurde. Wenn daher eine Metrik ohne Instanzbezeichnung (und ohne Instanzbezeichnung im Gruppierungsschlüssel, siehe unten) an das Pushgateway übertragen wird, exportiert das Pushgateway sie mit einer leeren Instanzbezeichnung ( {instance=""} ), was äquivalent ist dazu, überhaupt keine instance zu haben, verhindert aber, dass der Server eine anfügt.
Das Pushgateway stellt alle gepushten Metriken zusammen mit seinen eigenen Metriken über denselben /metrics Endpunkt bereit. (Einzelheiten finden Sie im Abschnitt über verfügbar gemachte Metriken.) Daher müssen alle Metriken miteinander konsistent sein: Metriken mit demselben Namen müssen denselben Typ haben, auch wenn sie in verschiedene Gruppen verschoben werden, und es dürfen keine Duplikate vorhanden sein , also Metriken mit demselben Namen und genau denselben Labelpaaren. Pushs, die zu Inkonsistenzen führen würden, werden mit dem Statuscode 400 abgelehnt.
Inkonsistente Hilfezeichenfolgen werden jedoch toleriert. Das Pushgateway wählt eine erfolgreiche Hilfezeichenfolge aus und protokolliert diese auf der Informationsebene.
Hinweis zu älteren Versionen: Die Hilfezeichenfolge der push_time_seconds Metrik von Pushgateway hat sich in Version 0.10.0 geändert. Durch die Verwendung einer Persistenzdatei können Metriken, die an ein Pushgateway einer früheren Version übertragen werden, in ein Pushgateway der Version 0.10.0 oder höher gelangen. In diesem Fall wird die oben genannte Protokollmeldung angezeigt. Sobald jede zuvor gepushte Gruppe gelöscht wurde oder einen neuen Push erhalten hat, verschwindet die Protokollmeldung.
Die Konsistenzprüfung, die während eines Pushs durchgeführt wird, ist die gleiche, die ohnehin bei einem Scrape stattfindet. In häufigen Anwendungsfällen kommt es häufiger zu Scrapes als zu Pushes. Daher ist der Leistungsaufwand der Push-Time-Prüfung nicht relevant. Wenn jedoch eine große Menge an Metriken auf dem Pushgateway mit häufigen Pushs kombiniert wird, kann die Push-Dauer unerschwinglich lang werden. In diesem Fall könnten Sie die Verwendung des Befehlszeilen-Flags --push.disable-consistency-check in Betracht ziehen, das die Kosten für die Konsistenzprüfung während eines Pushs spart, aber das Pushen inkonsistenter Metriken ermöglicht. Die Prüfung wird weiterhin während eines Scrapings durchgeführt, sodass alle Scrapingversuche fehlschlagen, solange inkonsistente Metriken auf dem Pushgateway gespeichert sind. Das Setzen des Flags birgt daher das Risiko, dass das Pushgateway durch einen einzigen inkonsistenten Push deaktiviert wird.
Wenn Sie Metriken zum Zeitpunkt t 1 pushen, könnten Sie versucht sein zu glauben, dass Prometheus sie mit demselben Zeitstempel t 1 streichen wird. Was Prometheus stattdessen als Zeitstempel anfügt, ist die Zeit, zu der es das Pushgateway kratzt. Warum so?
Im Weltbild von Prometheus kann eine Metrik jederzeit abgekratzt werden. Eine Metrik, die nicht abgekratzt werden kann, existiert im Grunde nicht mehr. Prometheus ist einigermaßen tolerant, aber wenn es innerhalb von 5 Minuten keine Proben für eine Metrik erhalten kann, verhält es sich so, als ob diese Metrik nicht mehr existierte. Dies zu verhindern, ist tatsächlich einer der Gründe, ein Pushgateway zu verwenden. Das Pushgateway macht die Kennzahlen Ihres kurzlebigen Jobs jederzeit löschbar. Das Anhängen der Push-Zeit als Zeitstempel würde diesen Zweck zunichte machen, da Ihre Metrik 5 Minuten nach dem letzten Push für Prometheus so veraltet aussieht, als ob sie überhaupt nicht mehr gelöscht werden könnte. (Prometheus kennt nur einen Zeitstempel pro Probe, es gibt keine Möglichkeit, einen „Zeitpunkt des Pushens“ und einen „Zeitpunkt des Scrapings“ zu unterscheiden.)
Da es keine Anwendungsfälle gibt, in denen es sinnvoll wäre, einen anderen Zeitstempel anzuhängen, und viele Benutzer versuchen, dies fälschlicherweise zu tun (obwohl dies von keiner Client-Bibliothek unterstützt wird), lehnt das Pushgateway alle Pushs mit Zeitstempeln ab.
Wenn Sie der Meinung sind, dass Sie einen Zeitstempel übertragen müssen, lesen Sie bitte Wann Sie das Pushgateway verwenden sollten.
Um die Warnung vor fehlgeschlagenen oder kürzlich nicht ausgeführten Pushern zu erleichtern, fügt das Pushgateway jeder Gruppe die Metriken push_time_seconds und push_failure_time_seconds mit dem Unix-Zeitstempel des letzten erfolgreichen und fehlgeschlagenen POST / PUT hinzu. Dadurch werden alle gepushten Metriken mit diesem Namen überschrieben. Ein Wert von Null für eine der beiden Metriken bedeutet, dass die Gruppe noch nie einen erfolgreichen oder fehlgeschlagenen POST / PUT gesehen hat.
Alle Pushs erfolgen über HTTP. Die Schnittstelle ist vage REST-ähnlich.
Der Standardport, den das Pushgateway überwacht, ist 9091. Der Pfad sieht folgendermaßen aus:
/metrics/job/{//}
job verwendet, gefolgt von einer beliebigen Anzahl anderer Bezeichnungspaare (die möglicherweise eine instance enthalten oder nicht). Der durch den URL-Pfad definierte Etikettensatz wird als Gruppierungsschlüssel verwendet. Alle bereits im Hauptteil der Anfrage festgelegten Labels (als reguläre Labels, z. B. name{job="foo"} 42 ) werden überschrieben, damit sie mit den durch den URL-Pfad definierten Labels übereinstimmen!
Wenn job oder Labelnamen das Suffix @base64 hinzugefügt wird, wird der folgende Jobname oder Labelwert als Base64-codierte Zeichenfolge gemäß RFC 4648 interpretiert, wobei das URL- und Dateinamen-sichere Alphabet verwendet wird. (Auffüllen ist optional, aber ein einzelnes = ist erforderlich, um einen leeren Labelwert zu kodieren.) Dies ist die einzige Möglichkeit, die folgenden Fälle zu behandeln:
/ enthält, da das einfache (oder sogar URI-codierte) / andernfalls als Pfadtrennzeichen interpretiert würde.// oder nachfolgende / verschwinden würde, wenn der Pfad durch den HTTP-Routercode bereinigt wird. Beachten Sie, dass ein leerer job ungültig ist. Leere Etikettenwerte sind gültig, aber selten nützlich. Um sie mit Base64 zu kodieren, müssen Sie mindestens ein Füllzeichen = verwenden, um ein // oder ein nachgestelltes / zu vermeiden.Für andere Sonderzeichen funktioniert auch die übliche URI-Komponentenkodierung, aber base64 ist möglicherweise praktischer.
Im Idealfall übernehmen Client-Bibliotheken die Suffixierung und Kodierung.
Beispiele:
Um den Gruppierungsschlüssel job="directory_cleaner",path="/var/tmp" zu verwenden, funktioniert der folgende Pfad nicht :
/metrics/job/directory_cleaner/path//var/tmp
Verwenden Sie stattdessen die URL-sichere Base64-Codierung für den Label-Wert und kennzeichnen Sie ihn, indem Sie dem Label-Namen @base64 anhängen:
/metrics/job/directory_cleaner/path@base64/L3Zhci90bXA
Wenn Sie keine Clientbibliothek verwenden, die die Kodierung für Sie übernimmt, können Sie Kodierungstools verwenden. Es gibt beispielsweise ein Befehlszeilentool base64url (Debian-Paket basez ), das Sie mit curl kombinieren können, um es folgendermaßen von der Befehlszeile aus zu pushen:
echo 'some_metric{foo="bar"} 3.14' | curl --data-binary @- http://pushgateway.example.org:9091/metrics/job/directory_cleaner/path@base64/$(echo -n '/var/tmp' | base64url)
Um einen Gruppierungsschlüssel zu verwenden, der einen leeren Labelwert wie job="example",first_label="",second_label="foobar" enthält, funktioniert der folgende Pfad nicht :
/metrics/job/example/first_label//second_label/foobar
Verwenden Sie stattdessen den folgenden Pfad einschließlich des Füllzeichens = :
/metrics/job/example/first_label@base64/=/second_label/foobar
Der Gruppierungsschlüssel job="titan",name="Προμηθεύς" kann „traditionell“ mit URI-Kodierung dargestellt werden:
/metrics/job/titan/name/%CE%A0%CF%81%CE%BF%CE%BC%CE%B7%CE%B8%CE%B5%CF%8D%CF%82
Oder Sie können die kompaktere Base64-Kodierung verwenden:
/metrics/job/titan/name@base64/zqDPgc6_zrzOt864zrXPjc-C
Neuere Versionen der Prometheus-Expositionsformate (Text und Protobuf) unterstützen den vollständigen UTF-8-Zeichensatz in Metrik- und Labelnamen. Das Pushgateway akzeptiert Sonderzeichen in Namen nur, wenn das Kommandozeilen-Flag --push.enable-utf8-names gesetzt ist. Um Sonderzeichen in Labelnamen zuzulassen, die Teil des URL-Pfads sind, aktiviert das Flag auch einen bestimmten Kodierungsmechanismus. Dies ähnelt der oben beschriebenen Base64-Codierung für Labelwerte , funktioniert jedoch aus technischen und historischen Gründen im Detail anders. Nach wie vor sollten sich Client-Bibliotheken in der Regel um die Kodierung kümmern. Es funktioniert wie folgt:
U__ ._1F60A_ .__ .U__ beginnt, müssen diese Zeichen ebenfalls codiert werden, was zu U___55_____ führt. (Das ist U__ + _55_ (für U ) + __ + __ ).U__ beginnt, aber ungültige Sequenzen enthält (z. B. U__in_xxx_valid ), bleibt unverändert. Das Label "foo.bar"="baz" würde beispielsweise wie folgt codiert werden:
/metrics/job/example/U__foo_2e_bar/baz
Diese Kodierung ist mit der Base64-Kodierung für Etikettenwerte kompatibel:
/metrics/job/example/U__foo_2e_bar@base64/YmF6
Beachten Sie, dass es bei dieser Methode einen unwahrscheinlichen Randfall gibt, der nicht richtig behandelt wird: Ein Pusher, der den Codierungsmechanismus nicht kennt, verwendet möglicherweise einen Labelnamen, der auch eine gültige codierte Version eines anderen Labelnamens ist. Wenn ein Pusher beispielsweise beabsichtigt, den Labelnamen U__foo_2e_bar zu verwenden, ihn aber nicht als U___55_____foo__2e__bar kodiert, dekodiert das Pushgateway U__foo_2e_bar in foo.bar . Dies ist der Hauptgrund, warum die Dekodierung über das Flag --push.enable-utf8-names aktiviert wird.
PUT Methode PUT wird verwendet, um eine Gruppe von Metriken zu pushen. Alle Metriken mit dem in der URL angegebenen Gruppierungsschlüssel werden durch die mit PUT gepushten Metriken ersetzt.
Der Hauptteil der Anforderung enthält die zu übertragenden Metriken entweder als getrennte binäre Protokollpuffer oder im einfachen Flat-Text-Format (beide in Version 0.0.4, siehe Spezifikation zum Datenbereitstellungsformat). Die Unterscheidung zwischen den beiden Varianten erfolgt über den Content-Type Header. (Verwenden Sie den Wert application/vnd.google.protobuf; proto=io.prometheus.client.MetricFamily; encoding=delimited für Protokollpuffer, andernfalls wird das Textformat als Fallback versucht.)
Der Antwortcode bei Erfolg ist entweder 200, 202 oder 400. Eine 200-Antwort impliziert einen erfolgreichen Push, bei dem entweder eine vorhandene Gruppe von Metriken ersetzt oder eine neue erstellt wird. Eine 400-Antwort kann auftreten, wenn die Anfrage fehlerhaft ist oder wenn die übertragenen Metriken nicht mit den an andere Gruppen übertragenen Metriken übereinstimmen oder mit den Metriken des Pushgateways selbst kollidieren. Im Hauptteil der Antwort wird eine Erklärung zurückgegeben und auf Fehlerebene protokolliert. Ein 202 kann nur auftreten, wenn das Flag --push.disable-consistency-check gesetzt ist. In diesem Fall werden gepushte Metriken lediglich in die Warteschlange gestellt und nicht auf Konsistenz überprüft. Inkonsistenzen führen jedoch, wie oben beschrieben, zu fehlgeschlagenen Scrapes.
In seltenen Fällen kann es vorkommen, dass das Pushgateway bereits über einen inkonsistenten Satz an Metriken verfügt. In diesem Fall werden auch neue Pushs als inkonsistent abgelehnt, selbst wenn der Schuldige Metriken sind, die zuvor gepusht wurden. Löschen Sie die beleidigenden Kennzahlen, um aus dieser Situation herauszukommen.
Wenn Sie das Protobuf-Format verwenden, senden Sie keine doppelten MetricFamily-Protonachrichten (d. h. mehr als eine mit demselben Namen) auf einmal, da diese sich gegenseitig überschreiben.
Beachten Sie, dass das Pushgateway keine starke Garantie dafür bietet, dass die gepushten Metriken auf der Festplatte gespeichert bleiben. (Ein Serverabsturz kann zu Datenverlust führen. Oder das Pushgateway ist so konfiguriert, dass es überhaupt nicht auf der Festplatte gespeichert wird.)
Eine PUT Anfrage mit einem leeren Textkörper löscht effektiv alle Metriken mit dem angegebenen Gruppierungsschlüssel. Im Gegensatz zur unten beschriebenen DELETE Anfrage werden jedoch die push_time_seconds -Metriken aktualisiert.
POST Methode POST funktioniert genau wie die PUT -Methode, jedoch werden nur Metriken mit demselben Namen wie die neu übertragenen Metriken ersetzt (darunter diejenigen mit demselben Gruppierungsschlüssel).
Eine POST Anfrage mit einem leeren Textkörper aktualisiert lediglich die push_time_seconds -Metriken, ändert jedoch keine der zuvor gepushten Metriken.
DELETE -Methode Mit DELETE werden Metriken aus dem Pushgateway gelöscht. Die Anfrage darf keinen Inhalt enthalten. Alle Metriken mit dem in der URL angegebenen Gruppierungsschlüssel werden gelöscht.
Der Antwortcode bei Erfolg ist immer 202. Die Löschanforderung wird in diesem Moment lediglich in die Warteschlange gestellt. Es gibt keine Garantie dafür, dass die Anfrage tatsächlich ausgeführt wird oder dass das Ergebnis in die Persistenzschicht gelangt (z. B. im Falle eines Serverabsturzes). Allerdings ist die Reihenfolge von PUT / POST und DELETE -Anfrage garantiert, d. h. wenn Sie erfolgreich eine DELETE -Anfrage gesendet haben und dann eine PUT senden, ist garantiert, dass die DELETE zuerst verarbeitet wird (und umgekehrt).
Das Löschen eines Gruppierungsschlüssels ohne Metriken ist ein No-Op und führt nicht zu einem Fehler.
Der Hauptteil einer POST- oder PUT-Anfrage kann gzip- oder snappy-komprimiert sein. Fügen Sie dazu einen Header Content-Encoding: gzip oder Content-Encoding: snappy hinzu.
Beispiele:
echo " some_metric 3.14 " | gzip | curl -H ' Content-Encoding: gzip ' --data-binary @- http://pushgateway.example.org:9091/metrics/job/some_job
echo " some_metric 3.14 " | snzip | curl -H ' Content-Encoding: snappy ' --data-binary @- http://pushgateway.example.org:9091/metrics/job/some_job Die Admin-API bietet administrativen Zugriff auf das Pushgateway und muss durch Setzen des Flags --web.enable-admin-api explizit aktiviert werden.
Der Standardport, den das Pushgateway überwacht, ist 9091. Der Pfad sieht wie folgt aus:
/api//admin/
| HTTP_METHOD | API_VERSION | HANDLER | BESCHREIBUNG |
|---|---|---|---|
| SETZEN | v1 | wischen | Löscht alle Metriken sicher vom Pushgateway. |
Um beispielsweise alle Metriken vom Pushgateway zu löschen:
curl -X PUT http://pushgateway.example.org:9091/api/v1/admin/wipe
Die Abfrage-API ermöglicht den Zugriff auf gepushte Metriken sowie Build- und Laufzeitinformationen.
/api//
| HTTP_METHOD | API_VERSION | HANDLER | BESCHREIBUNG |
|---|---|---|---|
| ERHALTEN | v1 | Status | Gibt Build-Informationen, Befehlszeilen-Flags und die Startzeit im JSON-Format zurück. |
| ERHALTEN | v1 | Metriken | Gibt die gepushten Metrikfamilien im JSON-Format zurück. |
Zum Beispiel :
curl -X GET http://pushgateway.example.org:9091/api/v1/status | jq
{
"status": "success",
"data": {
"build_information": {
"branch": "master",
"buildDate": "20200310-20:14:39",
"buildUser": "[email protected]",
"goVersion": "go1.13.6",
"revision": "eba0ec4100873d23666bcf4b8b1d44617d6430c4",
"version": "1.1.0"
},
"flags": {
"log.format": "logfmt",
"log.level": "info",
"persistence.file": "",
"persistence.interval": "5m0s",
"push.disable-consistency-check": "false",
"web.enable-admin-api": "false",
"web.enable-lifecycle": "false",
"web.external-url": "",
"web.listen-address": ":9091",
"web.route-prefix": "",
"web.telemetry-path": "/metrics"
},
"start_time": "2020-03-11T01:44:49.9189758+05:30"
}
}
curl -X GET http://pushgateway.example.org:9091/api/v1/metrics | jq
{
"status": "success",
"data": [
{
"labels": {
"job": "batch"
},
"last_push_successful": true,
"my_job_duration_seconds": {
"time_stamp": "2020-03-11T02:02:27.716605811+05:30",
"type": "GAUGE",
"help": "Duration of my batch job in seconds",
"metrics": [
{
"labels": {
"instance": "",
"job": "batch"
},
"value": "0.2721322309989773"
}
]
},
"push_failure_time_seconds": {
"time_stamp": "2020-03-11T02:02:27.716605811+05:30",
"type": "GAUGE",
"help": "Last Unix time when changing this group in the Pushgateway failed.",
"metrics": [
{
"labels": {
"instance": "",
"job": "batch"
},
"value": "0"
}
]
},
"push_time_seconds": {
"time_stamp": "2020-03-11T02:02:27.716605811+05:30",
"type": "GAUGE",
"help": "Last Unix time when changing this group in the Pushgateway succeeded.",
"metrics": [
{
"labels": {
"instance": "",
"job": "batch"
},
"value": "1.5838723477166057e+09"
}
]
}
}
]
}
Das Pushgateway bietet eine Reihe von Verwaltungs-APIs, um die Automatisierung und Integration zu erleichtern.
| HTTP_METHOD | WEG | BESCHREIBUNG |
|---|---|---|
| ERHALTEN | /-/gesund | Gibt 200 zurück, wenn das Pushgateway fehlerfrei ist. |
| ERHALTEN | /-/bereit | Gibt 200 zurück, wenn das Pushgateway bereit ist, Datenverkehr zu verarbeiten. |
--web.enable-lifecycle aktiviert werden.| HTTP_METHOD | WEG | BESCHREIBUNG |
|---|---|---|
| SETZEN | /-/aufhören | Löst ein ordnungsgemäßes Herunterfahren von Pushgateway aus. |
Alternativ kann ein ordnungsgemäßes Herunterfahren durch Senden eines SIGTERM an den Pushgateway-Prozess ausgelöst werden.
Das Pushgateway stellt die folgenden Metriken über den konfigurierten --web.telemetry-path (Standard: /metrics ) bereit:
push_time_seconds und push_failure_time_seconds , wie oben erläutert.process_...go_...promhttp_metric_handler_requests_... # HELP pushgateway_build_info A metric with a constant '1' value labeled by version, revision, branch, and goversion from which pushgateway was built.
# TYPE pushgateway_build_info gauge
pushgateway_build_info{branch="master",goversion="go1.10.2",revision="8f88ccb0343fc3382f6b93a9d258797dcb15f770",version="0.5.2"} 1
# HELP pushgateway_http_push_duration_seconds HTTP request duration for pushes to the Pushgateway.
# TYPE pushgateway_http_push_duration_seconds summary
pushgateway_http_push_duration_seconds{method="post",quantile="0.1"} 0.000116755
pushgateway_http_push_duration_seconds{method="post",quantile="0.5"} 0.000192608
pushgateway_http_push_duration_seconds{method="post",quantile="0.9"} 0.000327593
pushgateway_http_push_duration_seconds_sum{method="post"} 0.001622878
pushgateway_http_push_duration_seconds_count{method="post"} 8
# HELP pushgateway_http_push_size_bytes HTTP request size for pushes to the Pushgateway.
# TYPE pushgateway_http_push_size_bytes summary
pushgateway_http_push_size_bytes{method="post",quantile="0.1"} 166
pushgateway_http_push_size_bytes{method="post",quantile="0.5"} 182
pushgateway_http_push_size_bytes{method="post",quantile="0.9"} 196
pushgateway_http_push_size_bytes_sum{method="post"} 1450
pushgateway_http_push_size_bytes_count{method="post"} 8
# HELP pushgateway_http_requests_total Total HTTP requests processed by the Pushgateway, excluding scrapes.
# TYPE pushgateway_http_requests_total counter
pushgateway_http_requests_total{code="200",handler="static",method="get"} 5
pushgateway_http_requests_total{code="200",handler="status",method="get"} 8
pushgateway_http_requests_total{code="202",handler="delete",method="delete"} 1
pushgateway_http_requests_total{code="202",handler="push",method="post"} 6
pushgateway_http_requests_total{code="400",handler="push",method="post"} 2
Im Allgemeinen ist es eine gute Idee, darauf aufmerksam zu machen, dass push_time_seconds viel weiter zurückliegt als erwartet. Dadurch werden sowohl fehlgeschlagene Vorstöße als auch vollständig heruntergefahrene Vorstöße erfasst.
Um fehlgeschlagene Pushvorgänge viel früher zu erkennen, geben Sie eine Warnung bei push_failure_time_seconds > push_time_seconds aus.
Pushs können auch fehlschlagen, weil sie fehlerhaft sind. In diesem Fall erreichen sie nie eine Metrikgruppe und legen daher keine push_failure_time_seconds -Metriken fest. Diese Pushs werden weiterhin als pushgateway_http_requests_total{code="400",handler="push"} gezählt. Sie können über die rate dieser Metrik benachrichtigen, müssen jedoch die Protokolle überprüfen, um den störenden Pusher zu identifizieren.
Das Pushgateway unterstützt TLS und Basisauthentifizierung. Dies ermöglicht eine bessere Kontrolle der verschiedenen HTTP-Endpunkte.
Um TLS und/oder Basisauthentifizierung zu verwenden, müssen Sie eine Konfigurationsdatei mit dem Parameter --web.config.file übergeben. Das Format der Datei ist im Exporter-Toolkit-Repository beschrieben.
Beachten Sie, dass sich die TLS- und Basisauthentifizierungseinstellungen auf alle HTTP-Endpunkte auswirken: /metrics für Scraping, die API zum Pushen von Metriken über /metrics/..., die Admin-API über /api/... und die Web-Benutzeroberfläche.
Die normale Binärdatei bettet die Webdateien in das resources ein. Für Entwicklungszwecke ist es praktisch, wenn eine laufende Binärdatei diese Dateien direkt verwendet (damit Sie die Auswirkungen von Änderungen sofort sehen können). Um zur direkten Verwendung zu wechseln, fügen Sie -tags dev zum flags Eintrag in .promu.yml hinzu und make build . Wechseln Sie zurück in den „normalen“ Modus, indem Sie die Änderungen an .promu.yml rückgängig machen und make assets eingeben.
Relevante Stilrichtlinien sind die Go Code Review Comments und der Abschnitt „Formatierung und Stil“ von Peter Bourgons Go: Best Practices for Production Environments.
