{"action":"created","comment":{"url":"https://api.github.com/repos/prometheus/docs/pulls/comments/59634989","id":59634989,"diff_hunk":"@@ -152,71 +152,71 @@ A histogram MUST have the following methods:\n \n A histogram SHOULD have the following methods:\n \n-Some way to time code for users in seconds. In Python this is the `time()` decorator/context manager. In Java this is startTimer/observeDuration. Units other than seconds MUST NOT be offered (if a user wants something else, they can do it by hand). This should follow the same pattern as Gauge/Summary.\n+Some way to time code for users in seconds. In Python this is the `time()` decorator/context manager. In Java this is `startTimer`/`observeDuration`. Units other than seconds MUST NOT be offered (if a user wants something else, they can do it by hand). This should follow the same pattern as Gauge/Summary.\n \n Histogram  `_count`/`_sum` and the buckets MUST start at 0.\n \n **Further metrics considerations**\n \n-Providing additional functionality in metrics beyond what’s documented above as makes sense for a given language is ENCOURAGED. \n+Providing additional functionality in metrics beyond what’s documented above as makes sense for a given language is ENCOURAGED.\n \n If there’s a common use case you can make simpler then go for it, as long as it won’t encourage undesirable behaviours (such as suboptimal metric/label layouts, or doing computation in the client).\n \n ### Labels\n \n-Labels are one of the most powerful aspects of Prometheus, but easily abused. Accordingly client libraries must be very careful in how labels are offered to users. See [http://prometheus.io/docs/practices/instrumentation/#use-labels](http://prometheus.io/docs/practices/instrumentation/#use-labels) and [http://prometheus.io/docs/practices/instrumentation/#do-not-overuse-labels](http://prometheus.io/docs/practices/instrumentation/#do-not-overuse-labels)\n+Labels are one of the [most powerful aspects](/docs/practices/instrumentation/#use-labels) of Prometheus, but [easily abused](/docs/practices/instrumentation/#do-not-overuse-labels). Accordingly client libraries must be very careful in how labels are offered to users.\n \n Client libraries MUST NOT under any circumstances allow users to have different label names for the same metric for Gauge/Counter/Summary/Histogram or any other Collector offered by the library.\n \n If your client library does validation of metrics at collect time, it MAY also verify this for custom Collectors.\n \n While labels are powerful, the majority of metrics will not have labels. Accordingly the API should allow for labels but not dominate it.\n \n-A client library MUST allow for optionally specifying a list of label names at Gauge/Counter/Summary/Histogram creation time. A client library SHOULD support any number of label names. A client library MUST validate that label names meet the requirements in [http://prometheus.io/docs/concepts/data_model/#metric-names-and-labels](http://prometheus.io/docs/concepts/data_model/#metric-names-and-labels)\n+A client library MUST allow for optionally specifying a list of label names at Gauge/Counter/Summary/Histogram creation time. A client library SHOULD support any number of label names. A client library MUST validate that label names meet the [documented requirements](/docs/concepts/data_model/#metric-names-and-labels).\n \n The general way to provide access to labeled dimension of a metric is via a `labels()` method that takes either a list of the label values or a map from label name to label value and returns a \"Child\". The usual `.inc()`/`.dec()`/`.observe()` etc. methods can then be called on the Child.\n \n The Child returned by `labels()` SHOULD be cacheable by the user, to avoid having to look it up again - this matters in latency-critical code.\n \n Metrics with labels SHOULD support a `remove()` method with the same signature as `labels()` that will remove a Child from the metric no longer exporting it, and a `clear()` method that removes all Children from the metric. These invalidate caching of Children.\n \n-There SHOULD be a way to initialize a given Child with the default value, usually just calling `labels()`. No-labels metrics MUST always be initialized. See [http://prometheus.io/docs/practices/instrumentation/#avoid-missing-metrics](http://prometheus.io/docs/practices/instrumentation/#avoid-missing-metrics)\n+There SHOULD be a way to initialize a given Child with the default value, usually just calling `labels()`. Metrics without labels MUST always be initialized to avoid [problems with missing metrics](/docs/practices/instrumentation/#avoid-missing-metrics).\n \n-## **Metric names**\n+### Naming","path":"content/docs/instrumenting/clientlib_guidelines.md","position":null,"original_position":152,"commit_id":"1180e82e944957c3a5926a0c3695e61c9e243a39","original_commit_id":"1180e82e944957c3a5926a0c3695e61c9e243a39","user":{"login":"grobie","id":3432,"avatar_url":"https://avatars.githubusercontent.com/u/3432?v=3","gravatar_id":"","url":"https://api.github.com/users/grobie","html_url":"https://github.com/grobie","followers_url":"https://api.github.com/users/grobie/followers","following_url":"https://api.github.com/users/grobie/following{/other_user}","gists_url":"https://api.github.com/users/grobie/gists{/gist_id}","starred_url":"https://api.github.com/users/grobie/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/grobie/subscriptions","organizations_url":"https://api.github.com/users/grobie/orgs","repos_url":"https://api.github.com/users/grobie/repos","events_url":"https://api.github.com/users/grobie/events{/privacy}","received_events_url":"https://api.github.com/users/grobie/received_events","type":"User","site_admin":false},"body":"Yes. This is a subheading of `Metrics`.","created_at":"2016-04-13T22:11:01Z","updated_at":"2016-04-13T22:11:01Z","html_url":"https://github.com/prometheus/docs/pull/381#discussion_r59634989","pull_request_url":"https://api.github.com/repos/prometheus/docs/pulls/381","_links":{"self":{"href":"https://api.github.com/repos/prometheus/docs/pulls/comments/59634989"},"html":{"href":"https://github.com/prometheus/docs/pull/381#discussion_r59634989"},"pull_request":{"href":"https://api.github.com/repos/prometheus/docs/pulls/381"}}},"pull_request":{"url":"https://api.github.com/repos/prometheus/docs/pulls/381","id":65307481,"html_url":"https://github.com/prometheus/docs/pull/381","diff_url":"https://github.com/prometheus/docs/pull/381.diff","patch_url":"https://github.com/prometheus/docs/pull/381.patch","issue_url":"https://api.github.com/repos/prometheus/docs/issues/381","number":381,"state":"open","locked":false,"title":"Add Client Lib Guidelines and Exporter Guidelines","user":{"login":"discordianfish","id":275966,"avatar_url":"https://avatars.githubusercontent.com/u/275966?v=3","gravatar_id":"","url":"https://api.github.com/users/discordianfish","html_url":"https://github.com/discordianfish","followers_url":"https://api.github.com/users/discordianfish/followers","following_url":"https://api.github.com/users/discordianfish/following{/other_user}","gists_url":"https://api.github.com/users/discordianfish/gists{/gist_id}","starred_url":"https://api.github.com/users/discordianfish/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/discordianfish/subscriptions","organizations_url":"https://api.github.com/users/discordianfish/orgs","repos_url":"https://api.github.com/users/discordianfish/repos","events_url":"https://api.github.com/users/discordianfish/events{/privacy}","received_events_url":"https://api.github.com/users/discordianfish/received_events","type":"User","site_admin":false},"body":"This closes #379\r\nIt's pretty much 1:1 translated. The only thing different/missing is the TOC.\r\nFeel free to push additional fixes etc to this branch.","created_at":"2016-04-05T13:50:17Z","updated_at":"2016-04-13T22:11:01Z","closed_at":null,"merged_at":null,"merge_commit_sha":"6e5e9b8d097c529312b67e3a7cc0cfecb8b72bd9","assignee":null,"milestone":null,"commits_url":"https://api.github.com/repos/prometheus/docs/pulls/381/commits","review_comments_url":"https://api.github.com/repos/prometheus/docs/pulls/381/comments","review_comment_url":"https://api.github.com/repos/prometheus/docs/pulls/comments{/number}","comments_url":"https://api.github.com/repos/prometheus/docs/issues/381/comments","statuses_url":"https://api.github.com/repos/prometheus/docs/statuses/1180e82e944957c3a5926a0c3695e61c9e243a39","head":{"label":"prometheus:fish/add-guidelines-clientlib-exporter","ref":"fish/add-guidelines-clientlib-exporter","sha":"1180e82e944957c3a5926a0c3695e61c9e243a39","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":28233924,"name":"docs","full_name":"prometheus/docs","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/docs","description":"Prometheus documentation: content and static site generator","fork":false,"url":"https://api.github.com/repos/prometheus/docs","forks_url":"https://api.github.com/repos/prometheus/docs/forks","keys_url":"https://api.github.com/repos/prometheus/docs/keys{/key_id}","collaborators_url":"https://api.github.com/repos/prometheus/docs/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/prometheus/docs/teams","hooks_url":"https://api.github.com/repos/prometheus/docs/hooks","issue_events_url":"https://api.github.com/repos/prometheus/docs/issues/events{/number}","events_url":"https://api.github.com/repos/prometheus/docs/events","assignees_url":"https://api.github.com/repos/prometheus/docs/assignees{/user}","branches_url":"https://api.github.com/repos/prometheus/docs/branches{/branch}","tags_url":"https://api.github.com/repos/prometheus/docs/tags","blobs_url":"https://api.github.com/repos/prometheus/docs/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/prometheus/docs/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/prometheus/docs/git/refs{/sha}","trees_url":"https://api.github.com/repos/prometheus/docs/git/trees{/sha}","statuses_url":"https://api.github.com/repos/prometheus/docs/statuses/{sha}","languages_url":"https://api.github.com/repos/prometheus/docs/languages","stargazers_url":"https://api.github.com/repos/prometheus/docs/stargazers","contributors_url":"https://api.github.com/repos/prometheus/docs/contributors","subscribers_url":"https://api.github.com/repos/prometheus/docs/subscribers","subscription_url":"https://api.github.com/repos/prometheus/docs/subscription","commits_url":"https://api.github.com/repos/prometheus/docs/commits{/sha}","git_commits_url":"https://api.github.com/repos/prometheus/docs/git/commits{/sha}","comments_url":"https://api.github.com/repos/prometheus/docs/comments{/number}","issue_comment_url":"https://api.github.com/repos/prometheus/docs/issues/comments{/number}","contents_url":"https://api.github.com/repos/prometheus/docs/contents/{+path}","compare_url":"https://api.github.com/repos/prometheus/docs/compare/{base}...{head}","merges_url":"https://api.github.com/repos/prometheus/docs/merges","archive_url":"https://api.github.com/repos/prometheus/docs/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/prometheus/docs/downloads","issues_url":"https://api.github.com/repos/prometheus/docs/issues{/number}","pulls_url":"https://api.github.com/repos/prometheus/docs/pulls{/number}","milestones_url":"https://api.github.com/repos/prometheus/docs/milestones{/number}","notifications_url":"https://api.github.com/repos/prometheus/docs/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/prometheus/docs/labels{/name}","releases_url":"https://api.github.com/repos/prometheus/docs/releases{/id}","deployments_url":"https://api.github.com/repos/prometheus/docs/deployments","created_at":"2014-12-19T15:06:35Z","updated_at":"2016-04-13T13:10:58Z","pushed_at":"2016-04-13T16:51:53Z","git_url":"git://github.com/prometheus/docs.git","ssh_url":"git@github.com:prometheus/docs.git","clone_url":"https://github.com/prometheus/docs.git","svn_url":"https://github.com/prometheus/docs","homepage":"https://prometheus.io","size":5038,"stargazers_count":14,"watchers_count":14,"language":"CSS","has_issues":true,"has_downloads":true,"has_wiki":false,"has_pages":false,"forks_count":55,"mirror_url":null,"open_issues_count":33,"forks":55,"open_issues":33,"watchers":14,"default_branch":"master"}},"base":{"label":"prometheus:master","ref":"master","sha":"803cb20bd643771e813dc3e9bae23e04c778c72e","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":28233924,"name":"docs","full_name":"prometheus/docs","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/docs","description":"Prometheus documentation: content and static site generator","fork":false,"url":"https://api.github.com/repos/prometheus/docs","forks_url":"https://api.github.com/repos/prometheus/docs/forks","keys_url":"https://api.github.com/repos/prometheus/docs/keys{/key_id}","collaborators_url":"https://api.github.com/repos/prometheus/docs/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/prometheus/docs/teams","hooks_url":"https://api.github.com/repos/prometheus/docs/hooks","issue_events_url":"https://api.github.com/repos/prometheus/docs/issues/events{/number}","events_url":"https://api.github.com/repos/prometheus/docs/events","assignees_url":"https://api.github.com/repos/prometheus/docs/assignees{/user}","branches_url":"https://api.github.com/repos/prometheus/docs/branches{/branch}","tags_url":"https://api.github.com/repos/prometheus/docs/tags","blobs_url":"https://api.github.com/repos/prometheus/docs/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/prometheus/docs/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/prometheus/docs/git/refs{/sha}","trees_url":"https://api.github.com/repos/prometheus/docs/git/trees{/sha}","statuses_url":"https://api.github.com/repos/prometheus/docs/statuses/{sha}","languages_url":"https://api.github.com/repos/prometheus/docs/languages","stargazers_url":"https://api.github.com/repos/prometheus/docs/stargazers","contributors_url":"https://api.github.com/repos/prometheus/docs/contributors","subscribers_url":"https://api.github.com/repos/prometheus/docs/subscribers","subscription_url":"https://api.github.com/repos/prometheus/docs/subscription","commits_url":"https://api.github.com/repos/prometheus/docs/commits{/sha}","git_commits_url":"https://api.github.com/repos/prometheus/docs/git/commits{/sha}","comments_url":"https://api.github.com/repos/prometheus/docs/comments{/number}","issue_comment_url":"https://api.github.com/repos/prometheus/docs/issues/comments{/number}","contents_url":"https://api.github.com/repos/prometheus/docs/contents/{+path}","compare_url":"https://api.github.com/repos/prometheus/docs/compare/{base}...{head}","merges_url":"https://api.github.com/repos/prometheus/docs/merges","archive_url":"https://api.github.com/repos/prometheus/docs/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/prometheus/docs/downloads","issues_url":"https://api.github.com/repos/prometheus/docs/issues{/number}","pulls_url":"https://api.github.com/repos/prometheus/docs/pulls{/number}","milestones_url":"https://api.github.com/repos/prometheus/docs/milestones{/number}","notifications_url":"https://api.github.com/repos/prometheus/docs/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/prometheus/docs/labels{/name}","releases_url":"https://api.github.com/repos/prometheus/docs/releases{/id}","deployments_url":"https://api.github.com/repos/prometheus/docs/deployments","created_at":"2014-12-19T15:06:35Z","updated_at":"2016-04-13T13:10:58Z","pushed_at":"2016-04-13T16:51:53Z","git_url":"git://github.com/prometheus/docs.git","ssh_url":"git@github.com:prometheus/docs.git","clone_url":"https://github.com/prometheus/docs.git","svn_url":"https://github.com/prometheus/docs","homepage":"https://prometheus.io","size":5038,"stargazers_count":14,"watchers_count":14,"language":"CSS","has_issues":true,"has_downloads":true,"has_wiki":false,"has_pages":false,"forks_count":55,"mirror_url":null,"open_issues_count":33,"forks":55,"open_issues":33,"watchers":14,"default_branch":"master"}},"_links":{"self":{"href":"https://api.github.com/repos/prometheus/docs/pulls/381"},"html":{"href":"https://github.com/prometheus/docs/pull/381"},"issue":{"href":"https://api.github.com/repos/prometheus/docs/issues/381"},"comments":{"href":"https://api.github.com/repos/prometheus/docs/issues/381/comments"},"review_comments":{"href":"https://api.github.com/repos/prometheus/docs/pulls/381/comments"},"review_comment":{"href":"https://api.github.com/repos/prometheus/docs/pulls/comments{/number}"},"commits":{"href":"https://api.github.com/repos/prometheus/docs/pulls/381/commits"},"statuses":{"href":"https://api.github.com/repos/prometheus/docs/statuses/1180e82e944957c3a5926a0c3695e61c9e243a39"}}}}