{"id":37154222,"url":"https://github.com/jmcfarlane/pushgateway","last_synced_at":"2026-01-14T18:11:01.260Z","repository":{"id":30098765,"uuid":"33648499","full_name":"jmcfarlane/pushgateway","owner":"jmcfarlane","description":"push acceptor for ephemeral and batch jobs","archived":false,"fork":true,"pushed_at":"2015-04-09T17:38:17.000Z","size":162,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2024-06-21T11:49:48.844Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":"prometheus/pushgateway","license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jmcfarlane.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2015-04-09T04:32:24.000Z","updated_at":"2015-04-09T04:32:24.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/jmcfarlane/pushgateway","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/jmcfarlane/pushgateway","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jmcfarlane%2Fpushgateway","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jmcfarlane%2Fpushgateway/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jmcfarlane%2Fpushgateway/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jmcfarlane%2Fpushgateway/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jmcfarlane","download_url":"https://codeload.github.com/jmcfarlane/pushgateway/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jmcfarlane%2Fpushgateway/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28429814,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-14T16:38:47.836Z","status":"ssl_error","status_checked_at":"2026-01-14T16:34:59.695Z","response_time":107,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":[],"created_at":"2026-01-14T18:11:00.515Z","updated_at":"2026-01-14T18:11:01.248Z","avatar_url":"https://github.com/jmcfarlane.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Prometheus Pushgateway\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\nThe Pushgateway is explicitly not an aggregator, but rather a metrics\ncache. It does not have a statsd-like semantics. The metrics pushed\nare exactly the same as you would present for scraping in a\npermanently running program.\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 best\nused for service-level metrics.\n\n## Run it\n\nCompile the binary using the provided Makefile (type `make`). The\nbinary will be put into the `bin` directory.\n\nFor the most basic setup, just start the binary. To change the address\nto listen on, use the `-addr` flag. 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## Use it\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*Caveat: Note that in the text protocol, each line has to end with a\nline-feed character (aka 'LF' or '\\n'). Ending a line in other ways,\ne.g. with 'CR' aka '\\r', 'CRLF' aka '\\r\\n', or just the end of the\npacket, will result in a protocol error.*\n\nExamples:\n\n* Push a single sample:\n\n        echo \"some_metric 3.14\" | curl --data-binary @- http://pushgateway.example.org:8080/metrics/jobs/some_job\n\n  Since no type information has been provided, `some_metric` will be of type `untyped`.\n\n* Push something more complex:\n\n        cat \u003c\u003cEOF | curl --data-binary @- http://pushgateway.example.org:8080/metrics/jobs/some_job/instances/some_instance\n        # TYPE some_metric counter\n        some_metric{label=\"val1\"} 42\n        # This one even has a timestamp (but beware, see below).\n        some_metric{label=\"val2\"} 34 1398355504000\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 of an instance:\n\n        curl -X DELETE http://pushgateway.example.org:8080/metrics/jobs/some_job/instances/some_instance\n\n* Delete all metrics of a job:\n\n        curl -X DELETE http://pushgateway.example.org:8080/metrics/jobs/some_job\n\n### About timestamps\n\nIf you push metrics at time *t\u003csub\u003e1\u003c/sub\u003e*, you might be tempted to\nbelieve that Prometheus will scrape them with that same timestamp\n*t\u003csub\u003e1\u003c/sub\u003e*. Instead, what Prometheus attaches as a timestamp is\nthe time when it scrapes the push gateway. 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 push gateway. The push gateway 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\nYou can still force Prometheus to attach a different timestamp by\nusing the optional timestamp field in the exchange format. However,\nthere are very few use cases where that would make\nsense. (Essentially, if you push more often than every 5min, you\ncould attach the time of pushing as a timestamp.) \n\n## API\n\nAll pushes are done via HTTP. The interface is REST-like.\n\n### URL\n\nThe default port the push gateway is listening to is 8080. The path looks like\n\n    /metrics/jobs/\u003cJOBNAME\u003e[/instances/\u003cINSTANCENAME\u003e]\n\n`\u003cJOBNAME\u003e` is used as the value of the `job` label, and `\u003cINSTANCE\u003e`\nas the value of the `instance` label. The instance part of the URL is\noptional. If it is missing, the IP number of the pushing host is used\nas the value for the 'instance' label instead.\n\nIf those labels are already set in the body of the request (as regular\nlabels, e.g. `name{job=\"foo\",instance=\"bar\"} 42`), _the values of\nthose labels will be overwritten with values determined as described\nabove!_ (This behavior might be changed in the future if a valid\nuse-case can be shown.)\n\n### `POST` method\n\n`POST` is used to add metrics to previously pushed metrics. Note that\nonly previously pushed metrics with a different metric name, job label\nor instance label are preserved. Each `POST` will completely replace\nexisting metrics with the same metric name, job label, and instance\nlabel as the metrics pushed, even if the existing metrics had a\ndifferent label set otherwise.\n\nThe response code upon success is always 202 (even if that same metric has\nnever been pushed before, i.e. there is no feedback to the client if\nthe push has replaced a metric or created a new one).\n\nThe body of the request contains the metrics to push either as delimited binary protocol\nbuffers or in the simple flat text format (both in version 0.0.4, see the\n[data exposition format specification](https://docs.google.com/document/d/1ZjyKiKxZV83VI9ZKAXRGKaUKK2BIWCT7oiGBKDBpjEY/edit?usp=sharing). Discrimination between the two variants is done via content-type\nheader. (In case of an unknown content-type, the text format is tried as a fall-back.)\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\nA successfully finished request means that the pushed metrics are\nqueued for an update of the storage. Scraping the push gateway may\nstill yield the old sample value for that metric (or nothing at all if\nthis is the first time that metric is pushed) until the queued update\nis processed. Neither is there a guarantee that the metric is\npersisted to disk. (A server crash may cause data loss. Or the push\ngateway is configured to not persist to disk at all.)\n\n### `PUT` method\n\n`PUT` works exactly as `POST` with the important distinction that\n_all_ metrics with the same job label and instance label are deleted\nbefore pushing any of the newly submitted metrics.\n\n### `DELETE` method\n\n`DELETE` is used to delete metrics from the push gateway. The request\nmust not contain any content. If both a job and an instance are\nspecified in the URL, all metrics matching that job and instance are\ndeleted. If only a job is specified, all metrics matching that job are\ndeleted. The response code upon success is always 202. The delete\nrequest is merely queued at the 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 non-existing metrics is a no-op and will not result in an\nerror.\n\n## Development\n\nThe normal binary embeds the files in `resources`. For development\npurposes, it is handy to have a running binary use those files\ndirectly (so that you can see the effect of changes immediately). To\nswitch to direct usage, type `make bindata-debug` just before\ncompiling the binary. Switch back to \"normal\" mode by typing `make\nbindata-embed`. (Just `make` after a resource has changed will result\nin the same.)\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","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjmcfarlane%2Fpushgateway","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjmcfarlane%2Fpushgateway","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjmcfarlane%2Fpushgateway/lists"}