{"action":"created","comment":{"url":"https://api.github.com/repos/prometheus/pushgateway/pulls/comments/32115711","id":32115711,"diff_hunk":"@@ -108,42 +129,74 @@ could attach the time of pushing as a timestamp.)\n \n ## API\n \n-All pushes are done via HTTP. The interface is REST-like.\n+All pushes are done via HTTP. The interface is vaguely REST-like.\n \n ### URL\n \n The default port the push gateway is listening to is 8080. The path looks like\n \n+    /metrics/job/<JOBNAME>{/<LABEL_NAME>/<LABEL_VALUE>}\n+\n+`<JOBNAME>` is used as the value of the `job` label, followed by any\n+number 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\n+grouping key. Any of those labels already set in the body of the\n+request (as regular labels, e.g. `name{job=\"foo\"} 42`)\n+_will be overwritten to match the labels defined by the URL path!_\n+\n+Note that `/` cannot be used as part of a label value or the job name,\n+even if escaped as `%2F`. (The decoding happens before the path\n+routing kicks in, cf. the Go documentation of\n+[`URL.Path`](http://golang.org/pkg/net/url/#URL).)\n+\n+### Deprecated URL\n+\n+There is a _deprecated_ version of the URL path, using `jobs` instead\n+of `job`:\n+\n     /metrics/jobs/<JOBNAME>[/instances/<INSTANCENAME>]\n \n-`<JOBNAME>` is used as the value of the `job` label, and `<INSTANCE>`\n-as the value of the `instance` label. The instance part of the URL is\n-optional. If it is missing, the IP number of the pushing host is used\n-as the value for the 'instance' label instead.\n+If this version of the URL path is used _with_ the `instances` part,\n+it is equivalent to the URL path above with an `instance` label, i.e.\n \n-If those labels are already set in the body of the request (as regular\n-labels, e.g. `name{job=\"foo\",instance=\"bar\"} 42`), _the values of\n-those labels will be overwritten with values determined as described\n-above!_ (This behavior might be changed in the future if a valid\n-use-case can be shown.)\n+    /metrics/jobs/foo/instances/bar\n \n-### `POST` method\n+is equivalent to\n+\n+    /metrics/job/foo/instance/bar\n+\n+(Note the missing pluralizations.)\n+\n+However, if the `instances` part is missing, the Pushgateway will\n+automatically use the IP number of the pushing host as the 'instance'\n+label, and grouping happens by 'job' and 'instance' labels.\n \n-`POST` is used to add metrics to previously pushed metrics. Note that\n-only previously pushed metrics with a different metric name, job label\n-or instance label are preserved. Each `POST` will completely replace\n-existing metrics with the same metric name, job label, and instance\n-label as the metrics pushed, even if the existing metrics had a\n-different label set otherwise.\n+Example: Pushing metrics from host 1.2.3.4 using the deprecated URL path\n \n-The response code upon success is always 202 (even if that same metric has\n-never been pushed before, i.e. there is no feedback to the client if\n-the push has replaced a metric or created a new one).\n+    /metrics/jobs/foo\n \n-The body of the request contains the metrics to push either as delimited binary protocol\n-buffers 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\n-header. (In case of an unknown content-type, the text format is tried as a fall-back.)\n+is equivalent to pushing using the URL path\n+\n+    /metrics/job/foo/instance/1.2.3.4\n+\n+### `PUT` method\n+\n+`PUT` is used to push a group of metrics. All metrics with the\n+grouping key specified in the URL are replaced by the metrics pushed\n+with `PUT`.\n+\n+The body of the request contains the metrics to push either as\n+delimited binary protocol buffers or in the simple flat text format\n+(both in version 0.0.4, see the\n+[data exposition format specification](https://docs.google.com/document/d/1ZjyKiKxZV83VI9ZKAXRGKaUKK2BIWCT7oiGBKDBpjEY/edit?usp=sharing)).\n+Discrimination between the two variants is done via the content-type\n+header. (In case of an unknown content-type, the text format is tried","path":"README.md","position":159,"original_position":159,"commit_id":"dcfda5f4afbef83eda66a869ba7a7f32086bc58f","original_commit_id":"dcfda5f4afbef83eda66a869ba7a7f32086bc58f","user":{"login":"beorn7","id":5609886,"avatar_url":"https://avatars.githubusercontent.com/u/5609886?v=3","gravatar_id":"","url":"https://api.github.com/users/beorn7","html_url":"https://github.com/beorn7","followers_url":"https://api.github.com/users/beorn7/followers","following_url":"https://api.github.com/users/beorn7/following{/other_user}","gists_url":"https://api.github.com/users/beorn7/gists{/gist_id}","starred_url":"https://api.github.com/users/beorn7/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/beorn7/subscriptions","organizations_url":"https://api.github.com/users/beorn7/orgs","repos_url":"https://api.github.com/users/beorn7/repos","events_url":"https://api.github.com/users/beorn7/events{/privacy}","received_events_url":"https://api.github.com/users/beorn7/received_events","type":"User","site_admin":false},"body":"One could argue that should be \"content type\"... but I reworded it to refer to the header name, too.","created_at":"2015-06-10T13:19:55Z","updated_at":"2015-06-10T13:19:55Z","html_url":"https://github.com/prometheus/pushgateway/pull/44#discussion_r32115711","pull_request_url":"https://api.github.com/repos/prometheus/pushgateway/pulls/44","_links":{"self":{"href":"https://api.github.com/repos/prometheus/pushgateway/pulls/comments/32115711"},"html":{"href":"https://github.com/prometheus/pushgateway/pull/44#discussion_r32115711"},"pull_request":{"href":"https://api.github.com/repos/prometheus/pushgateway/pulls/44"}}},"pull_request":{"url":"https://api.github.com/repos/prometheus/pushgateway/pulls/44","id":37273848,"html_url":"https://github.com/prometheus/pushgateway/pull/44","diff_url":"https://github.com/prometheus/pushgateway/pull/44.diff","patch_url":"https://github.com/prometheus/pushgateway/pull/44.patch","issue_url":"https://api.github.com/repos/prometheus/pushgateway/issues/44","number":44,"state":"open","locked":false,"title":"Implement arbitrary grouping","user":{"login":"beorn7","id":5609886,"avatar_url":"https://avatars.githubusercontent.com/u/5609886?v=3","gravatar_id":"","url":"https://api.github.com/users/beorn7","html_url":"https://github.com/beorn7","followers_url":"https://api.github.com/users/beorn7/followers","following_url":"https://api.github.com/users/beorn7/following{/other_user}","gists_url":"https://api.github.com/users/beorn7/gists{/gist_id}","starred_url":"https://api.github.com/users/beorn7/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/beorn7/subscriptions","organizations_url":"https://api.github.com/users/beorn7/orgs","repos_url":"https://api.github.com/users/beorn7/repos","events_url":"https://api.github.com/users/beorn7/events{/privacy}","received_events_url":"https://api.github.com/users/beorn7/received_events","type":"User","site_admin":false},"body":"This fixes https://github.com/prometheus/pushgateway/issues/18 and https://github.com/prometheus/pushgateway/issues/32 .\r\n\r\n@brian-brazil @juliusv @fabxc ","created_at":"2015-06-09T16:41:07Z","updated_at":"2015-06-10T13:19:55Z","closed_at":null,"merged_at":null,"merge_commit_sha":"2dce11de82f6e422c7aff55ea6aaa1064c6a111f","assignee":null,"milestone":null,"commits_url":"https://api.github.com/repos/prometheus/pushgateway/pulls/44/commits","review_comments_url":"https://api.github.com/repos/prometheus/pushgateway/pulls/44/comments","review_comment_url":"https://api.github.com/repos/prometheus/pushgateway/pulls/comments{/number}","comments_url":"https://api.github.com/repos/prometheus/pushgateway/issues/44/comments","statuses_url":"https://api.github.com/repos/prometheus/pushgateway/statuses/dcfda5f4afbef83eda66a869ba7a7f32086bc58f","head":{"label":"prometheus:beorn7/grouping","ref":"beorn7/grouping","sha":"dcfda5f4afbef83eda66a869ba7a7f32086bc58f","user":{"login":"prometheus","id":3380462,"avatar_url":"https://avatars.githubusercontent.com/u/3380462?v=3","gravatar_id":"","url":"https://api.github.com/users/prometheus","html_url":"https://github.com/prometheus","followers_url":"https://api.github.com/users/prometheus/followers","following_url":"https://api.github.com/users/prometheus/following{/other_user}","gists_url":"https://api.github.com/users/prometheus/gists{/gist_id}","starred_url":"https://api.github.com/users/prometheus/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/prometheus/subscriptions","organizations_url":"https://api.github.com/users/prometheus/orgs","repos_url":"https://api.github.com/users/prometheus/repos","events_url":"https://api.github.com/users/prometheus/events{/privacy}","received_events_url":"https://api.github.com/users/prometheus/received_events","type":"Organization","site_admin":false},"repo":{"id":16345015,"name":"pushgateway","full_name":"prometheus/pushgateway","owner":{"login":"prometheus","id":3380462,"avatar_url":"https://avatars.githubusercontent.com/u/3380462?v=3","gravatar_id":"","url":"https://api.github.com/users/prometheus","html_url":"https://github.com/prometheus","followers_url":"https://api.github.com/users/prometheus/followers","following_url":"https://api.github.com/users/prometheus/following{/other_user}","gists_url":"https://api.github.com/users/prometheus/gists{/gist_id}","starred_url":"https://api.github.com/users/prometheus/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/prometheus/subscriptions","organizations_url":"https://api.github.com/users/prometheus/orgs","repos_url":"https://api.github.com/users/prometheus/repos","events_url":"https://api.github.com/users/prometheus/events{/privacy}","received_events_url":"https://api.github.com/users/prometheus/received_events","type":"Organization","site_admin":false},"private":false,"html_url":"https://github.com/prometheus/pushgateway","description":"push acceptor for ephemeral and batch jobs","fork":false,"url":"https://api.github.com/repos/prometheus/pushgateway","forks_url":"https://api.github.com/repos/prometheus/pushgateway/forks","keys_url":"https://api.github.com/repos/prometheus/pushgateway/keys{/key_id}","collaborators_url":"https://api.github.com/repos/prometheus/pushgateway/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/prometheus/pushgateway/teams","hooks_url":"https://api.github.com/repos/prometheus/pushgateway/hooks","issue_events_url":"https://api.github.com/repos/prometheus/pushgateway/issues/events{/number}","events_url":"https://api.github.com/repos/prometheus/pushgateway/events","assignees_url":"https://api.github.com/repos/prometheus/pushgateway/assignees{/user}","branches_url":"https://api.github.com/repos/prometheus/pushgateway/branches{/branch}","tags_url":"https://api.github.com/repos/prometheus/pushgateway/tags","blobs_url":"https://api.github.com/repos/prometheus/pushgateway/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/prometheus/pushgateway/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/prometheus/pushgateway/git/refs{/sha}","trees_url":"https://api.github.com/repos/prometheus/pushgateway/git/trees{/sha}","statuses_url":"https://api.github.com/repos/prometheus/pushgateway/statuses/{sha}","languages_url":"https://api.github.com/repos/prometheus/pushgateway/languages","stargazers_url":"https://api.github.com/repos/prometheus/pushgateway/stargazers","contributors_url":"https://api.github.com/repos/prometheus/pushgateway/contributors","subscribers_url":"https://api.github.com/repos/prometheus/pushgateway/subscribers","subscription_url":"https://api.github.com/repos/prometheus/pushgateway/subscription","commits_url":"https://api.github.com/repos/prometheus/pushgateway/commits{/sha}","git_commits_url":"https://api.github.com/repos/prometheus/pushgateway/git/commits{/sha}","comments_url":"https://api.github.com/repos/prometheus/pushgateway/comments{/number}","issue_comment_url":"https://api.github.com/repos/prometheus/pushgateway/issues/comments{/number}","contents_url":"https://api.github.com/repos/prometheus/pushgateway/contents/{+path}","compare_url":"https://api.github.com/repos/prometheus/pushgateway/compare/{base}...{head}","merges_url":"https://api.github.com/repos/prometheus/pushgateway/merges","archive_url":"https://api.github.com/repos/prometheus/pushgateway/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/prometheus/pushgateway/downloads","issues_url":"https://api.github.com/repos/prometheus/pushgateway/issues{/number}","pulls_url":"https://api.github.com/repos/prometheus/pushgateway/pulls{/number}","milestones_url":"https://api.github.com/repos/prometheus/pushgateway/milestones{/number}","notifications_url":"https://api.github.com/repos/prometheus/pushgateway/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/prometheus/pushgateway/labels{/name}","releases_url":"https://api.github.com/repos/prometheus/pushgateway/releases{/id}","created_at":"2014-01-29T13:09:53Z","updated_at":"2015-06-02T16:36:45Z","pushed_at":"2015-06-09T16:41:08Z","git_url":"git://github.com/prometheus/pushgateway.git","ssh_url":"git@github.com:prometheus/pushgateway.git","clone_url":"https://github.com/prometheus/pushgateway.git","svn_url":"https://github.com/prometheus/pushgateway","homepage":null,"size":903,"stargazers_count":23,"watchers_count":23,"language":"Go","has_issues":true,"has_downloads":true,"has_wiki":false,"has_pages":false,"forks_count":9,"mirror_url":null,"open_issues_count":7,"forks":9,"open_issues":7,"watchers":23,"default_branch":"master"}},"base":{"label":"prometheus:master","ref":"master","sha":"a769dbd0d2a0914311f817c9823cba7735f672ba","user":{"login":"prometheus","id":3380462,"avatar_url":"https://avatars.githubusercontent.com/u/3380462?v=3","gravatar_id":"","url":"https://api.github.com/users/prometheus","html_url":"https://github.com/prometheus","followers_url":"https://api.github.com/users/prometheus/followers","following_url":"https://api.github.com/users/prometheus/following{/other_user}","gists_url":"https://api.github.com/users/prometheus/gists{/gist_id}","starred_url":"https://api.github.com/users/prometheus/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/prometheus/subscriptions","organizations_url":"https://api.github.com/users/prometheus/orgs","repos_url":"https://api.github.com/users/prometheus/repos","events_url":"https://api.github.com/users/prometheus/events{/privacy}","received_events_url":"https://api.github.com/users/prometheus/received_events","type":"Organization","site_admin":false},"repo":{"id":16345015,"name":"pushgateway","full_name":"prometheus/pushgateway","owner":{"login":"prometheus","id":3380462,"avatar_url":"https://avatars.githubusercontent.com/u/3380462?v=3","gravatar_id":"","url":"https://api.github.com/users/prometheus","html_url":"https://github.com/prometheus","followers_url":"https://api.github.com/users/prometheus/followers","following_url":"https://api.github.com/users/prometheus/following{/other_user}","gists_url":"https://api.github.com/users/prometheus/gists{/gist_id}","starred_url":"https://api.github.com/users/prometheus/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/prometheus/subscriptions","organizations_url":"https://api.github.com/users/prometheus/orgs","repos_url":"https://api.github.com/users/prometheus/repos","events_url":"https://api.github.com/users/prometheus/events{/privacy}","received_events_url":"https://api.github.com/users/prometheus/received_events","type":"Organization","site_admin":false},"private":false,"html_url":"https://github.com/prometheus/pushgateway","description":"push acceptor for ephemeral and batch jobs","fork":false,"url":"https://api.github.com/repos/prometheus/pushgateway","forks_url":"https://api.github.com/repos/prometheus/pushgateway/forks","keys_url":"https://api.github.com/repos/prometheus/pushgateway/keys{/key_id}","collaborators_url":"https://api.github.com/repos/prometheus/pushgateway/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/prometheus/pushgateway/teams","hooks_url":"https://api.github.com/repos/prometheus/pushgateway/hooks","issue_events_url":"https://api.github.com/repos/prometheus/pushgateway/issues/events{/number}","events_url":"https://api.github.com/repos/prometheus/pushgateway/events","assignees_url":"https://api.github.com/repos/prometheus/pushgateway/assignees{/user}","branches_url":"https://api.github.com/repos/prometheus/pushgateway/branches{/branch}","tags_url":"https://api.github.com/repos/prometheus/pushgateway/tags","blobs_url":"https://api.github.com/repos/prometheus/pushgateway/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/prometheus/pushgateway/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/prometheus/pushgateway/git/refs{/sha}","trees_url":"https://api.github.com/repos/prometheus/pushgateway/git/trees{/sha}","statuses_url":"https://api.github.com/repos/prometheus/pushgateway/statuses/{sha}","languages_url":"https://api.github.com/repos/prometheus/pushgateway/languages","stargazers_url":"https://api.github.com/repos/prometheus/pushgateway/stargazers","contributors_url":"https://api.github.com/repos/prometheus/pushgateway/contributors","subscribers_url":"https://api.github.com/repos/prometheus/pushgateway/subscribers","subscription_url":"https://api.github.com/repos/prometheus/pushgateway/subscription","commits_url":"https://api.github.com/repos/prometheus/pushgateway/commits{/sha}","git_commits_url":"https://api.github.com/repos/prometheus/pushgateway/git/commits{/sha}","comments_url":"https://api.github.com/repos/prometheus/pushgateway/comments{/number}","issue_comment_url":"https://api.github.com/repos/prometheus/pushgateway/issues/comments{/number}","contents_url":"https://api.github.com/repos/prometheus/pushgateway/contents/{+path}","compare_url":"https://api.github.com/repos/prometheus/pushgateway/compare/{base}...{head}","merges_url":"https://api.github.com/repos/prometheus/pushgateway/merges","archive_url":"https://api.github.com/repos/prometheus/pushgateway/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/prometheus/pushgateway/downloads","issues_url":"https://api.github.com/repos/prometheus/pushgateway/issues{/number}","pulls_url":"https://api.github.com/repos/prometheus/pushgateway/pulls{/number}","milestones_url":"https://api.github.com/repos/prometheus/pushgateway/milestones{/number}","notifications_url":"https://api.github.com/repos/prometheus/pushgateway/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/prometheus/pushgateway/labels{/name}","releases_url":"https://api.github.com/repos/prometheus/pushgateway/releases{/id}","created_at":"2014-01-29T13:09:53Z","updated_at":"2015-06-02T16:36:45Z","pushed_at":"2015-06-09T16:41:08Z","git_url":"git://github.com/prometheus/pushgateway.git","ssh_url":"git@github.com:prometheus/pushgateway.git","clone_url":"https://github.com/prometheus/pushgateway.git","svn_url":"https://github.com/prometheus/pushgateway","homepage":null,"size":903,"stargazers_count":23,"watchers_count":23,"language":"Go","has_issues":true,"has_downloads":true,"has_wiki":false,"has_pages":false,"forks_count":9,"mirror_url":null,"open_issues_count":7,"forks":9,"open_issues":7,"watchers":23,"default_branch":"master"}},"_links":{"self":{"href":"https://api.github.com/repos/prometheus/pushgateway/pulls/44"},"html":{"href":"https://github.com/prometheus/pushgateway/pull/44"},"issue":{"href":"https://api.github.com/repos/prometheus/pushgateway/issues/44"},"comments":{"href":"https://api.github.com/repos/prometheus/pushgateway/issues/44/comments"},"review_comments":{"href":"https://api.github.com/repos/prometheus/pushgateway/pulls/44/comments"},"review_comment":{"href":"https://api.github.com/repos/prometheus/pushgateway/pulls/comments{/number}"},"commits":{"href":"https://api.github.com/repos/prometheus/pushgateway/pulls/44/commits"},"statuses":{"href":"https://api.github.com/repos/prometheus/pushgateway/statuses/dcfda5f4afbef83eda66a869ba7a7f32086bc58f"}}}}