{"id":13440982,"url":"https://github.com/prometheus/pushgateway","last_synced_at":"2025-05-13T15:05:08.637Z","repository":{"id":13651530,"uuid":"16345015","full_name":"prometheus/pushgateway","owner":"prometheus","description":"Push acceptor for ephemeral and batch jobs.","archived":false,"fork":false,"pushed_at":"2025-04-22T10:43:29.000Z","size":11972,"stargazers_count":3135,"open_issues_count":6,"forks_count":480,"subscribers_count":60,"default_branch":"master","last_synced_at":"2025-04-22T11:37:16.876Z","etag":null,"topics":["hacktoberfest"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/prometheus.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2014-01-29T13:09:53.000Z","updated_at":"2025-04-22T10:43:33.000Z","dependencies_parsed_at":"2023-10-20T22:40:00.766Z","dependency_job_id":"d2fb91b5-6db1-45e2-8ea9-50dd209ff6c9","html_url":"https://github.com/prometheus/pushgateway","commit_stats":{"total_commits":437,"total_committers":74,"mean_commits":5.905405405405405,"dds":0.8146453089244852,"last_synced_commit":"bee2b3d52d449c5d062e2fc3197316014c70e3a5"},"previous_names":["prometheus/exporter"],"tags_count":34,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/prometheus%2Fpushgateway","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/prometheus%2Fpushgateway/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/prometheus%2Fpushgateway/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/prometheus%2Fpushgateway/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/prometheus","download_url":"https://codeload.github.com/prometheus/pushgateway/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250479615,"owners_count":21437395,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["hacktoberfest"],"created_at":"2024-07-31T03:01:28.518Z","updated_at":"2025-05-05T18:26:04.174Z","avatar_url":"https://github.com/prometheus.png","language":"Go","readme":"# Prometheus Pushgateway\n\n[![CircleCI](https://circleci.com/gh/prometheus/pushgateway/tree/master.svg?style=shield)][circleci]\n[![Docker Repository on Quay](https://quay.io/repository/prometheus/pushgateway/status)][quay]\n[![Docker Pulls](https://img.shields.io/docker/pulls/prom/pushgateway.svg?maxAge=604800)][hub]\n\nThe Prometheus Pushgateway exists to allow ephemeral and batch jobs to\nexpose their metrics to Prometheus. Since these kinds of jobs may not\nexist long enough to be scraped, they can instead push their metrics\nto a Pushgateway. The Pushgateway then exposes these metrics to\nPrometheus.\n\n## Non-goals\n\nFirst of all, the Pushgateway is not capable of turning Prometheus into a\npush-based monitoring system. For a general description of use cases for the\nPushgateway, please read [When To Use The\nPushgateway](https://prometheus.io/docs/practices/pushing/).\n\nThe Pushgateway is explicitly not an _aggregator or distributed counter_ but\nrather a metrics cache. It does not have\n[statsd](https://github.com/etsy/statsd)-like semantics. The metrics pushed are\nexactly the same as you would present for scraping in a permanently running\nprogram. If you need distributed counting, you could either use the actual\nstatsd in combination with the [Prometheus statsd\nexporter](https://github.com/prometheus/statsd_exporter), or have a look at the\n[prom-aggregation-gateway](https://github.com/zapier/prom-aggregation-gateway). With more\nexperience gathered, the Prometheus project might one day be able to provide a\nnative solution, separate from or possibly even as part of the Pushgateway.\n\nFor machine-level metrics, the\n[textfile](https://github.com/prometheus/node_exporter/blob/master/README.md#textfile-collector)\ncollector of the Node exporter is usually more appropriate. The Pushgateway is\nintended for service-level metrics.\n\nThe Pushgateway is not an _event store_. While you can use Prometheus as a data\nsource for\n[Grafana annotations](http://docs.grafana.org/reference/annotations/), tracking\nsomething like release events has to happen with some event-logging framework.\n\nA while ago, we\n[decided to not implement a “timeout” or TTL for pushed metrics](https://github.com/prometheus/pushgateway/issues/19)\nbecause almost all proposed use cases turned out to be anti-patterns we\nstrongly discourage. You can follow a more recent discussion on the\n[prometheus-developers mailing list](https://groups.google.com/forum/#!topic/prometheus-developers/9IyUxRvhY7w).\n\n## Run it\n\nDownload binary releases for your platform from the\n[release page](https://github.com/prometheus/pushgateway/releases) and unpack\nthe tarball.\n\nIf you want to compile yourself from the sources, you need a working Go\nsetup. Then use the provided Makefile (type `make`).\n\nFor the most basic setup, just start the binary. To change the address\nto listen on, use the `--web.listen-address` flag (e.g. \"0.0.0.0:9091\" or \":9091\").\nBy default, Pushgateway does not persist metrics. However, the `--persistence.file` flag\nallows you to specify a file in which the pushed metrics will be\npersisted (so that they survive restarts of the Pushgateway).\n\n### Using Docker\n\nYou can deploy the Pushgateway using the [prom/pushgateway](https://hub.docker.com/r/prom/pushgateway) Docker image.\n\nFor example:\n\n```bash\ndocker pull prom/pushgateway\n\ndocker run -d -p 9091:9091 prom/pushgateway\n```\n\n## Use it\n\n### Configure the Pushgateway as a target to scrape\n\nThe Pushgateway has to be configured as a target to scrape by Prometheus, using\none of the usual methods. _However, you should always set `honor_labels: true`\nin the scrape config_ (see [below](#about-the-job-and-instance-labels) for a\ndetailed explanation).\n\n### Libraries\n\nPrometheus client libraries should have a feature to push the\nregistered metrics to a Pushgateway. Usually, a Prometheus client\npassively presents metric for scraping by a Prometheus server. A\nclient library that supports pushing has a push function, which needs\nto be called by the client code. It will then actively push the\nmetrics to a Pushgateway, using the API described below.\n\n### Command line\n\nUsing the Prometheus text protocol, pushing metrics is so easy that no\nseparate CLI is provided. Simply use a command-line HTTP tool like\n`curl`. Your favorite scripting language has most likely some built-in\nHTTP capabilities you can leverage here as well.\n\n*Note that in the text protocol, each line has to end with a line-feed\ncharacter (aka 'LF' or '\\n'). Ending a line in other ways, e.g. with 'CR' aka\n'\\r', 'CRLF' aka '\\r\\n', or just the end of the packet, will result in a\nprotocol error.*\n\nPushed metrics are managed in groups, identified by a grouping key of any\nnumber of labels, of which the first must be the `job` label. The groups are\neasy to inspect via the web interface.\n\n*For implications of special characters in label values see the [URL\nsection](#url) below.*\n\nExamples:\n\n* Push a single sample into the group identified by `{job=\"some_job\"}`:\n\n        echo \"some_metric 3.14\" | curl --data-binary @- http://pushgateway.example.org:9091/metrics/job/some_job\n\n  Since no type information has been provided, `some_metric` will be of type `untyped`.\n\n* Push something more complex into the group identified by `{job=\"some_job\",instance=\"some_instance\"}`:\n\n        cat \u003c\u003cEOF | curl --data-binary @- http://pushgateway.example.org:9091/metrics/job/some_job/instance/some_instance\n        # TYPE some_metric counter\n        some_metric{label=\"val1\"} 42\n        # TYPE another_metric gauge\n        # HELP another_metric Just an example.\n        another_metric 2398.283\n        EOF\n\n  Note how type information and help strings are provided. Those lines\n  are optional, but strongly encouraged for anything more complex.\n\n* Delete all metrics in the group identified by\n  `{job=\"some_job\",instance=\"some_instance\"}`:\n\n        curl -X DELETE http://pushgateway.example.org:9091/metrics/job/some_job/instance/some_instance\n\n* Delete all metrics in the group identified by `{job=\"some_job\"}` (note that\n  this does not include metrics in the\n  `{job=\"some_job\",instance=\"some_instance\"}` group from the previous example,\n  even if those metrics have the same job label):\n\n        curl -X DELETE http://pushgateway.example.org:9091/metrics/job/some_job\n        \n* Delete all metrics in all groups (requires to enable the admin API via the command line flag `--web.enable-admin-api`):\n\n        curl -X PUT http://pushgateway.example.org:9091/api/v1/admin/wipe\n\n#### Note for MS Windows users\n\nMS Windows users can send HTTP requests to the Pushgateway using Powershell. \n\nExample:\n\n         Invoke-WebRequest -Uri http://localhost:9091/metrics/job/MyJob -Method POST -Body \"Some_Metric 3.14`n\"\n\nDouble quotes should be used to enclose the metric text, and the back tick (`) character should come before the line ending character (n) at the end.\n\n### About the job and instance labels\n\nThe Prometheus server will attach a `job` label and an `instance` label to each\nscraped metric. The value of the `job` label comes from the scrape\nconfiguration. When you configure the Pushgateway as a scrape target for your\nPrometheus server, you will probably pick a job name like `pushgateway`. The\nvalue of the `instance` label is automatically set to the host and port of the\ntarget scraped. Hence, all the metrics scraped from the Pushgateway will have\nthe host and port of the Pushgateway as the `instance` label and a `job` label\nlike `pushgateway`. The conflict with the `job` and `instance` labels you might\nhave attached to the metrics pushed to the Pushgateway is solved by renaming\nthose labels to `exported_job` and `exported_instance`.\n\nHowever, this behavior is usually undesired when scraping a\nPushgateway. Generally, you would like to retain the `job` and `instance`\nlabels of the metrics pushed to the Pushgateway. That's why you have to set\n`honor_labels: true` in the scrape config for the Pushgateway. It enables the\ndesired behavior. See the\n[documentation](https://prometheus.io/docs/operating/configuration/#scrape_config)\nfor details.\n\nThis leaves us with the case where the metrics pushed to the Pushgateway do not\nfeature an `instance` label. This case is quite common as the pushed metrics\nare often on a service level and therefore not related to a particular\ninstance. Even with `honor_labels: true`, the Prometheus server will attach an\n`instance` label if no `instance` label has been set in the first\nplace. Therefore, if a metric is pushed to the Pushgateway without an instance\nlabel (and without instance label in the grouping key, see below), the\nPushgateway will export it with an empty instance label (`{instance=\"\"}`),\nwhich is equivalent to having no `instance` label at all but prevents the\nserver from attaching one.\n\n### About metric inconsistencies\n\nThe Pushgateway exposes all pushed metrics together with its own metrics via\nthe same `/metrics` endpoint. (See the section about [exposed\nmetrics](#exposed-metrics) for details.) Therefore, all the metrics have to be\nconsistent with each other: Metrics of the same name must have\nthe same type, even if they are pushed to different groups, and there must be\nno duplicates, i.e. metrics with the same name and the exact same label\npairs. Pushes that would lead to inconsistencies are rejected with status\ncode 400.\n\nInconsistent help strings are tolerated, though. The Pushgateway will pick a\nwinning help string and log about it at info level.\n\n_Legacy note: The help string of Pushgateway's own `push_time_seconds` metric\nhas changed in v0.10.0. By using a persistence file, metrics pushed to a\nPushgateway of an earlier version can make it into a Pushgateway of v0.10.0 or\nlater. In this case, the above mentioned log message will show up. Once each\npreviously pushed group has been deleted or received a new push, the log\nmessage will disappear._\n\nThe consistency check performed during a push is the same as it happens anyway\nduring a scrape. In common use cases, scrapes happen more often than\npushes. Therefore, the performance cost of the push-time check isn't\nrelevant. However, if a large amount of metrics on the Pushgateway is combined\nwith frequent pushes, the push duration might become prohibitively long. In\nthis case, you might consider using the command line flag\n`--push.disable-consistency-check`, which saves the cost of the consistency\ncheck during a push but allows pushing inconsistent metrics. The check will\nstill happen during a scrape, thereby failing all scrapes for as long as\ninconsistent metrics are stored on the Pushgateway. Setting the flag therefore\nputs you at risk to disable the Pushgateway by a single inconsistent push.\n\n### About timestamps\n\nIf you push metrics at time *t*\u003csub\u003e1\u003c/sub\u003e, you might be tempted to believe\nthat Prometheus will scrape them with that same timestamp\n*t*\u003csub\u003e1\u003c/sub\u003e. Instead, what Prometheus attaches as a timestamp is the time\nwhen it scrapes the Pushgateway. Why so?\n\nIn the world view of Prometheus, a metric can be scraped at any\ntime. A metric that cannot be scraped has basically ceased to\nexist. Prometheus is somewhat tolerant, but if it cannot get any\nsamples for a metric in 5min, it will behave as if that metric does\nnot exist anymore. Preventing that is actually one of the reasons to\nuse a Pushgateway. The Pushgateway will make the metrics of your\nephemeral job scrapable at any time. Attaching the time of pushing as\na timestamp would defeat that purpose because 5min after the last\npush, your metric will look as stale to Prometheus as if it could not\nbe scraped at all anymore. (Prometheus knows only one timestamp per\nsample, there is no way to distinguish a 'time of pushing' and a 'time\nof scraping'.)\n\nAs there aren't any use cases where it would make sense to attach a\ndifferent timestamp, and many users attempting to incorrectly do so (despite no\nclient library supporting this), the Pushgateway rejects any pushes with\ntimestamps.\n\nIf you think you need to push a timestamp, please see [When To Use The\nPushgateway](https://prometheus.io/docs/practices/pushing/).\n\nIn order to make it easier to alert on failed pushers or those that have not\nrun recently, the Pushgateway will add in the metrics `push_time_seconds` and\n`push_failure_time_seconds` with the Unix timestamp of the last successful and\nfailed `POST`/`PUT` to each group. This will override any pushed metric by that\nname. A value of zero for either metric implies that the group has never seen a\nsuccessful or failed `POST`/`PUT`.\n\n## API\n\nAll pushes are done via HTTP. The interface is vaguely REST-like.\n\n### URL\n\nThe default port the Pushgateway is listening to is 9091. The path looks like\n\n    /metrics/job/\u003cJOB_NAME\u003e{/\u003cLABEL_NAME\u003e/\u003cLABEL_VALUE\u003e}\n\n`\u003cJOB_NAME\u003e` is used as the value of the `job` label, followed by any\nnumber of other label pairs (which might or might not include an\n`instance` label). The label set defined by the URL path is used as a\ngrouping key. Any of those labels already set in the body of the\nrequest (as regular labels, e.g. `name{job=\"foo\"} 42`)\n_will be overwritten to match the labels defined by the URL path!_\n\nIf `job` or any label name is suffixed with `@base64`, the following job name\nor label value is interpreted as a base64 encoded string according to [RFC\n4648, using the URL and filename safe\nalphabet](https://tools.ietf.org/html/rfc4648#section-5). (Padding is optional,\nbut a single `=` is required to encode an empty label value.) This is the only\nway to handle the following cases:\n\n* A job name or a label value that contains a `/`, because the plain (or even\n  URI-encoded) `/` would otherwise be interpreted as a path separator.\n* An empty label value, because the resulting `//` or trailing `/` would\n  disappear when the path is sanitized by the HTTP router code. Note that an\n  empty `job` name is invalid. Empty label values are valid but rarely\n  useful. To encode them with base64, you have to use at least one `=` padding\n  character to avoid a `//` or a trailing `/`.\n\nFor other special characters, the usual URI component encoding works, too, but\nthe base64 might be more convenient.\n\nIdeally, client libraries take care of the suffixing and encoding.\n\nExamples:\n\n* To use the grouping key `job=\"directory_cleaner\",path=\"/var/tmp\"`, the\n  following path will _not_ work:\n\n      /metrics/job/directory_cleaner/path//var/tmp\n      \n  Instead, use the base64 URL-safe encoding for the label value and mark it by\n  suffixing the label name with `@base64`:\n  \n      /metrics/job/directory_cleaner/path@base64/L3Zhci90bXA\n      \n  If you are not using a client library that handles the encoding for you, you\n  can use encoding tools. For example, there is a command line tool `base64url`\n  (Debian package `basez`), which you could combine with `curl` to push from\n  the command line in the following way:\n  \n      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)\n\n* To use a grouping key containing an empty label value such as\n  `job=\"example\",first_label=\"\",second_label=\"foobar\"`, the following path will\n  _not_ work:\n  \n       /metrics/job/example/first_label//second_label/foobar\n\n  Instead, use the following path including the `=` padding character:\n  \n      /metrics/job/example/first_label@base64/=/second_label/foobar\n\n* The grouping key `job=\"titan\",name=\"Προμηθεύς\"` can be represented\n  “traditionally” with URI encoding:\n  \n      /metrics/job/titan/name/%CE%A0%CF%81%CE%BF%CE%BC%CE%B7%CE%B8%CE%B5%CF%8D%CF%82\n      \n  Or you can use the more compact base64 encoding:\n  \n      /metrics/job/titan/name@base64/zqDPgc6_zrzOt864zrXPjc-C\n\n### UTF-8 support for metric and label names\n\nNewer versions of the Prometheus exposition formats (text and protobuf)\nsupport the full UTF-8 character set in metric and label names. The\nPushgateway only accepts special characters in names if the command line\nflag `--push.enable-utf8-names` is set.\nTo allow special characters in label names that are part of the URL path, the flag also enables a\n[specific encoding mechanism](https://github.com/prometheus/proposals/blob/main/proposals/2023-08-21-utf8.md#text-escaping). This is similar to the base64 encoding for label _values_ described above,\nbut works differently in detail for technical and historical reasons. As before, client libraries\nshould usually take care of the encoding. It works as follows:\n\n* A label name containing encoded characters starts with `U__`.\n* All non-standard characters (i.e. characters other than letters, numbers, and underscores) are encoded as underscores surrounding their Unicode value, like `_1F60A_`.\n* All pre-existing underscores are encoded as a double-underscore: `__`.\n* If a label name starts with `U__` already, these characters have to be encoded as well, resulting in `U___55_____`. (That's `U__` + `_55_` (for `U`) + `__` + `__`).\n* A label name starting with `U__` in it's encoded form, but containing invalid sequences (e.g. `U__in_xxx_valid`) is left unchanged.\n\nFor example, the label `\"foo.bar\"=\"baz\"` would be encoded like: \n  \n    /metrics/job/example/U__foo_2e_bar/baz\n\nThis encoding is compatible with the base64 encoding for label values:\n\n    /metrics/job/example/U__foo_2e_bar@base64/YmF6\n\nNote that this method has an unlikely edge case that is not handled properly: \nA pusher unaware of the encoding mechanism might use a label name that is \nalso a valid encoded version of another label name. \nE.g. if a pusher intends to use the label name `U__foo_2e_bar`, but doesn't \nencode it as `U___55_____foo__2e__bar`, the Pushgateway will decode \n`U__foo_2e_bar` to `foo.bar`. This is the main reason why the decoding is \nopt-in via the `--push.enable-utf8-names` flag.\n\n### `PUT` method\n\n`PUT` is used to push a group of metrics. All metrics with the\ngrouping key specified in the URL are replaced by the metrics pushed\nwith `PUT`.\n\nThe body of the request contains the metrics to push either as delimited binary\nprotocol buffers or in the simple flat text format (both in version 0.0.4, see\nthe\n[data exposition format specification](https://docs.google.com/document/d/1ZjyKiKxZV83VI9ZKAXRGKaUKK2BIWCT7oiGBKDBpjEY/edit?usp=sharing)).\nDiscrimination between the two variants is done via the `Content-Type`\nheader. (Use the value `application/vnd.google.protobuf;\nproto=io.prometheus.client.MetricFamily; encoding=delimited` for protocol\nbuffers, otherwise the text format is tried as a fall-back.)\n\nThe response code upon success is either 200, 202, or 400. A 200 response\nimplies a successful push, either replacing an existing group of metrics or\ncreating a new one. A 400 response can happen if the request is malformed or if\nthe pushed metrics are inconsistent with metrics pushed to other groups or\ncollide with metrics of the Pushgateway itself. An explanation is returned in\nthe body of the response and logged on error level. A 202 can only occur if the\n`--push.disable-consistency-check` flag is set. In this case, pushed metrics\nare just queued and not checked for consistency. Inconsistencies will lead to\nfailed scrapes, however, as described [above](#about-metric-inconsistencies).\n\nIn rare cases, it is possible that the Pushgateway ends up with an inconsistent\nset of metrics already pushed. In that case, new pushes are also rejected as\ninconsistent even if the culprit is metrics that were pushed earlier. Delete\nthe offending metrics to get out of that situation.\n\n_If using the protobuf format, do not send duplicate MetricFamily\nproto messages (i.e. more than one with the same name) in one push, as\nthey will overwrite each other._\n\nNote that the Pushgateway doesn't provide any strong guarantees that the pushed\nmetrics are persisted to disk. (A server crash may cause data loss. Or the\nPushgateway is configured to not persist to disk at all.)\n\nA `PUT` request with an empty body effectively deletes all metrics with the\nspecified grouping key. However, in contrast to the\n[`DELETE` request](#delete-method) described below, it does update the\n`push_time_seconds` metrics.\n\n### `POST` method\n\n`POST` works exactly like the `PUT` method but only metrics with the\nsame name as the newly pushed metrics are replaced (among those with\nthe same grouping key).\n\nA `POST` request with an empty body merely updates the `push_time_seconds`\nmetrics but does not change any of the previously pushed metrics.\n\n### `DELETE` method\n\n`DELETE` is used to delete metrics from the Pushgateway. The request\nmust not contain any content. All metrics with the grouping key\nspecified in the URL are deleted.\n\nThe response code upon success is always 202. The delete\nrequest is merely queued at that moment. There is no guarantee that the\nrequest will actually be executed or that the result will make it to\nthe persistence layer (e.g. in case of a server crash). However, the\norder of `PUT`/`POST` and `DELETE` request is guaranteed, i.e. if you\nhave successfully sent a `DELETE` request and then send a `PUT`, it is\nguaranteed that the `DELETE` will be processed first (and vice versa).\n\nDeleting a grouping key without metrics is a no-op and will not result\nin an error.\n\n### Request compression\n\nThe body of a POST or PUT request may be gzip- or snappy-compressed. Add a\nheader `Content-Encoding: gzip` or `Content-Encoding: snappy` to do so.\n\nExamples:\n\n```bash\necho \"some_metric 3.14\" | gzip | curl -H 'Content-Encoding: gzip' --data-binary @- http://pushgateway.example.org:9091/metrics/job/some_job\necho \"some_metric 3.14\" | snzip | curl -H 'Content-Encoding: snappy' --data-binary @- http://pushgateway.example.org:9091/metrics/job/some_job\n```\n\n## Admin API\n\nThe Admin API provides administrative access to the Pushgateway, and must be\nexplicitly enabled by setting `--web.enable-admin-api` flag.\n\n### URL\n\nThe default port the Pushgateway is listening to is 9091. The path looks like:\n\n    /api/\u003cAPI_VERSION\u003e/admin/\u003cHANDLER\u003e\n    \n * Available endpoints:\n \n| HTTP_METHOD| API_VERSION |  HANDLER | DESCRIPTION |\n| :-------: |:-------------:| :-----:| :----- |\n| PUT     | v1 | wipe |  Safely deletes all metrics from the Pushgateway. |\n\n\n* For example to wipe all metrics from the Pushgateway:\n\n        curl -X PUT http://pushgateway.example.org:9091/api/v1/admin/wipe\n\n## Query API\n\nThe query API allows accessing pushed metrics and build and runtime information.\n\n### URL\n\n    /api/\u003cAPI_VERSION\u003e/\u003cHANDLER\u003e\n    \n * Available endpoints:\n \n| HTTP_METHOD| API_VERSION |  HANDLER | DESCRIPTION |\n| :-------: |:-------------:| :-----:| :----- |\n| GET     | v1 | status |  Returns build information, command line flags, and the start time in JSON format. |\n| GET     | v1 | metrics |  Returns the pushed metric families in JSON format. |\n\n\n* For example :\n\n        curl -X GET http://pushgateway.example.org:9091/api/v1/status | jq\n        \n        {\n          \"status\": \"success\",\n          \"data\": {\n            \"build_information\": {\n              \"branch\": \"master\",\n              \"buildDate\": \"20200310-20:14:39\",\n              \"buildUser\": \"flipbyte@localhost.localdomain\",\n              \"goVersion\": \"go1.13.6\",\n              \"revision\": \"eba0ec4100873d23666bcf4b8b1d44617d6430c4\",\n              \"version\": \"1.1.0\"\n            },\n            \"flags\": {\n              \"log.format\": \"logfmt\",\n              \"log.level\": \"info\",\n              \"persistence.file\": \"\",\n              \"persistence.interval\": \"5m0s\",\n              \"push.disable-consistency-check\": \"false\",\n              \"web.enable-admin-api\": \"false\",\n              \"web.enable-lifecycle\": \"false\",\n              \"web.external-url\": \"\",\n              \"web.listen-address\": \":9091\",\n              \"web.route-prefix\": \"\",\n              \"web.telemetry-path\": \"/metrics\"\n            },\n            \"start_time\": \"2020-03-11T01:44:49.9189758+05:30\"\n          }\n        }\n        \n        curl -X GET http://pushgateway.example.org:9091/api/v1/metrics | jq\n        \n        {\n          \"status\": \"success\",\n          \"data\": [\n            {\n              \"labels\": {\n                \"job\": \"batch\"\n              },\n              \"last_push_successful\": true,\n              \"my_job_duration_seconds\": {\n                \"time_stamp\": \"2020-03-11T02:02:27.716605811+05:30\",\n                \"type\": \"GAUGE\",\n                \"help\": \"Duration of my batch job in seconds\",\n                \"metrics\": [\n                  {\n                    \"labels\": {\n                      \"instance\": \"\",\n                      \"job\": \"batch\"\n                    },\n                    \"value\": \"0.2721322309989773\"\n                  }\n                ]\n              },\n              \"push_failure_time_seconds\": {\n                \"time_stamp\": \"2020-03-11T02:02:27.716605811+05:30\",\n                \"type\": \"GAUGE\",\n                \"help\": \"Last Unix time when changing this group in the Pushgateway failed.\",\n                \"metrics\": [\n                  {\n                    \"labels\": {\n                      \"instance\": \"\",\n                      \"job\": \"batch\"\n                    },\n                    \"value\": \"0\"\n                  }\n                ]\n              },\n              \"push_time_seconds\": {\n                \"time_stamp\": \"2020-03-11T02:02:27.716605811+05:30\",\n                \"type\": \"GAUGE\",\n                \"help\": \"Last Unix time when changing this group in the Pushgateway succeeded.\",\n                \"metrics\": [\n                  {\n                    \"labels\": {\n                      \"instance\": \"\",\n                      \"job\": \"batch\"\n                    },\n                    \"value\": \"1.5838723477166057e+09\"\n                  }\n                ]\n              }\n            }\n          ]\n        }\n        \n## Management API\n\nThe Pushgateway provides a set of management API to ease automation and integrations.\n\n* Available endpoints:\n \n| HTTP_METHOD |  PATH | DESCRIPTION |\n| :-------: | :-----| :----- |\n| GET    | /-/healthy |  Returns 200 whenever the Pushgateway is healthy. |\n| GET    | /-/ready |  Returns 200 whenever the Pushgateway is ready to serve traffic. |\n\n* The following endpoint is disabled by default and can be enabled via the `--web.enable-lifecycle` flag.\n\n| HTTP_METHOD |  PATH | DESCRIPTION |\n| :-------: | :-----| :----- |\n| PUT    | /-/quit |  Triggers a graceful shutdown of Pushgateway. |\n\nAlternatively, a graceful shutdown can be triggered by sending a `SIGTERM` to the Pushgateway process.\n\n## Exposed metrics\n\nThe Pushgateway exposes the following metrics via the configured\n`--web.telemetry-path` (default: `/metrics`):\n- The pushed metrics.\n- For each pushed group, a metric `push_time_seconds` and\n  `push_failure_time_seconds` as explained above.\n- The usual metrics provided by the [Prometheus Go client library](https://github.com/prometheus/client_golang), i.e.:\n  - `process_...`\n  - `go_...`\n  - `promhttp_metric_handler_requests_...`\n- A number of metrics specific to the Pushgateway, as documented by the example\n  scrape below.\n\n```\n# HELP pushgateway_build_info A metric with a constant '1' value labeled by version, revision, branch, and goversion from which pushgateway was built.\n# TYPE pushgateway_build_info gauge\npushgateway_build_info{branch=\"master\",goversion=\"go1.10.2\",revision=\"8f88ccb0343fc3382f6b93a9d258797dcb15f770\",version=\"0.5.2\"} 1\n# HELP pushgateway_http_push_duration_seconds HTTP request duration for pushes to the Pushgateway.\n# TYPE pushgateway_http_push_duration_seconds summary\npushgateway_http_push_duration_seconds{method=\"post\",quantile=\"0.1\"} 0.000116755\npushgateway_http_push_duration_seconds{method=\"post\",quantile=\"0.5\"} 0.000192608\npushgateway_http_push_duration_seconds{method=\"post\",quantile=\"0.9\"} 0.000327593\npushgateway_http_push_duration_seconds_sum{method=\"post\"} 0.001622878\npushgateway_http_push_duration_seconds_count{method=\"post\"} 8\n# HELP pushgateway_http_push_size_bytes HTTP request size for pushes to the Pushgateway.\n# TYPE pushgateway_http_push_size_bytes summary\npushgateway_http_push_size_bytes{method=\"post\",quantile=\"0.1\"} 166\npushgateway_http_push_size_bytes{method=\"post\",quantile=\"0.5\"} 182\npushgateway_http_push_size_bytes{method=\"post\",quantile=\"0.9\"} 196\npushgateway_http_push_size_bytes_sum{method=\"post\"} 1450\npushgateway_http_push_size_bytes_count{method=\"post\"} 8\n# HELP pushgateway_http_requests_total Total HTTP requests processed by the Pushgateway, excluding scrapes.\n# TYPE pushgateway_http_requests_total counter\npushgateway_http_requests_total{code=\"200\",handler=\"static\",method=\"get\"} 5\npushgateway_http_requests_total{code=\"200\",handler=\"status\",method=\"get\"} 8\npushgateway_http_requests_total{code=\"202\",handler=\"delete\",method=\"delete\"} 1\npushgateway_http_requests_total{code=\"202\",handler=\"push\",method=\"post\"} 6\npushgateway_http_requests_total{code=\"400\",handler=\"push\",method=\"post\"} 2\n\n```\n\n### Alerting on failed pushes\n\nIt is in general a good idea to alert on `push_time_seconds` being much farther\nbehind than expected. This will catch both failed pushes as well as pushers\nbeing down completely.\n\nTo detect failed pushes much earlier, alert on `push_failure_time_seconds \u003e\npush_time_seconds`.\n\nPushes can also fail because they are malformed. In this case, they never reach\nany metric group and therefore won't set any `push_failure_time_seconds`\nmetrics. Those pushes are still counted as\n`pushgateway_http_requests_total{code=\"400\",handler=\"push\"}`. You can alert on\nthe `rate` of this metric, but you have to inspect the logs to identify the\noffending pusher.\n\n## TLS and basic authentication\n\nThe Pushgateway supports TLS and basic authentication. This enables better\ncontrol of the various HTTP endpoints.\n\nTo use TLS and/or basic authentication, you need to pass a configuration file\nusing the `--web.config.file` parameter. The format of the file is described\n[in the exporter-toolkit repository](https://github.com/prometheus/exporter-toolkit/blob/master/docs/web-configuration.md).\n\nNote that the TLS and basic authentication settings affect all HTTP endpoints:\n/metrics for scraping, the API to push metrics via /metrics/..., the admin API\nvia /api/..., and the web UI.\n\n## Development\n\nThe normal binary embeds the web files in the `resources` directory.\nFor development purposes, it is handy to have a running binary use\nthose files directly (so that you can see the effect of changes immediately).\nTo switch to direct usage, add `-tags dev` to the `flags` entry in\n`.promu.yml`, and then `make build`. Switch back to \"normal\" mode by\nreverting the changes to `.promu.yml` and typing `make assets`.\n\n##  Contributing\n\nRelevant style guidelines are the [Go Code Review\nComments](https://code.google.com/p/go-wiki/wiki/CodeReviewComments)\nand the _Formatting and style_ section of Peter Bourgon's [Go:\nBest Practices for Production\nEnvironments](http://peter.bourgon.org/go-in-production/#formatting-and-style).\n\n[hub]: https://hub.docker.com/r/prom/pushgateway/\n[circleci]: https://circleci.com/gh/prometheus/pushgateway\n[quay]: https://quay.io/repository/prometheus/pushgateway\n","funding_links":[],"categories":["HarmonyOS","Performance","Go","JavaScript","Technologies we used in the Microservices"],"sub_categories":["Windows Manager","Monitoring"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fprometheus%2Fpushgateway","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fprometheus%2Fpushgateway","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fprometheus%2Fpushgateway/lists"}