{"action":"created","comment":{"url":"https://api.github.com/repos/hawkular/hawkular.github.io/pulls/comments/59285962","id":59285962,"diff_hunk":"@@ -4,22 +4,181 @@ Thomas Segismont\n :icons: font\n :jbake-type: page\n :jbake-status: published\n+:toc: macro\n+:toc-title:\n \n-Hawkular Metrics is the metric data store part of the http://www.hawkular.org/[Hawkular] organization.\n-It is currently used as the metric storage engine for Hawkular but it can also be used independently. The project relies on https://cassandra.apache.org/[Apache Cassandra] as a backend.\n+toc::[]\n \n+== Introduction\n+Hawkular Metrics is a metrics storage engine built on top of link:http://cassandra.apache.org[Cassandra] that offers\n+a rich, growing set of features that includes.\n \n-Three types of metrics are currently supported:\n+* Multi tenancy\n+* Multiple metric types\n+* Tagging\n+* Automatic data removal\n+* REST API\n+* Scalability\n+* Rich query support\n \n- * Availability: metric that represent availability: up or down\n- * Counter: numeric value that always goes up; example: the total number of visitors of a web page\n-   ** Rates: rate of change can be retrieve for counter rates\n- * Gauge: numeric value that can go up or down; example: the response time on an application\n-   ** Aggregate buckets (min/max/average on some intervals) can be obtained for gauges when individual datapoints are not needed\n+== Identifiers\n+All identifiers are stored as variable length, UTF-8 encoded strings. This includes,\n \n-Tags are available for easy filtering and querying, along with retention times for automatic pruning of older data.\n+* Tenant ids\n+* Metric names\n+* Tag keys (for both metric and data point tags)\n \n+[TIP]\n+At present there is no restriction on characters that can be used in identifiers. This may change in the future\n+though (See https://issues.jboss.org/browse/HWKMETRICS-208[HWKMETRICS-208] for details). For this reason it is\n+recommended to restrict the characters to letters, numbers, underscore, period, and forward slash.\n \n+== Multi Tenancy\n+Hawkular Metrics provides _virtual_ multi tenancy. All data is mapped to a tenant, but the data on disk is not\n+physically partitioned by tenant. From an API perspective though, everything is partitioned by tenant. All requests,\n+both reads and writes, must include a tenant id.\n+\n+A tenant has an id that uniquely identifies it. The id is a variable length, UTF-8 encoded string.\n+\n+TIP: Tenants do not have to be explicitly created. They will be created when inserting data points.\n+\n+== Metric Types\n+A metric represents a single time series or continuous stream of data points. A data point consists of a timestamp and\n+a value. The type of value will vary depending on the metric type. Three types of metrics are currently supported:\n+\n+* Availability\n+* Gauge\n+* Counter\n+\n+TIP: Metrics do not have to be explicitly created. They will be created when inserting data points.\n+\n+TIP: A string metric type may be added in a future release. See\n+https://issues.jboss.org/browse/HWKMETRICS-384(HWKMETRICS-384) for details.\n+\n+=== Availability\n+Represents the availability of a resource such as host machine (physical or virtual) or an application server. There\n+are only three supported availability types or values,\n+\n+* up\n+* down\n+* unknown\n+\n+Availability is stored as single, unsigned byte.\n+\n+=== Gauge\n+Has a numeric value that can fluctuate, going up or down. Some examples of gauges include,\n+\n+* Available heap space in the JVM\n+* Number of active HTTP sessions on a web server\n+* Disk space used by a database table\n+* Execution time for a REST API call\n+\n+With each of these examples, values can increase or decrease. In some instances, like JVM heap space, there are\n+well-defined bounds for the possible values.\n+\n+A gauge value is stored as a 64-bit floating point number.\n+\n+=== Counter\n+Has a numeric value that monotonically increases or decreases. Some examples include,\n+\n+* Total number of requests to a REST endpoint\n+* Total number of request timeouts for a Cassandra node\n+* Total number of request timeouts for a Cassandra cluster\n+\n+These examples involve values that are always increase. Counters can also be decreasing.\n+\n+A counter value is stored as a 64-bit signed long.\n+\n+There are two types of counters commonly uses with time series databases (TSDB). One stores the current count or total with\n+each data point. The other stores the delta or increment with each data point. The former is more commonly used with\n+counters that can easily be maintained by the client. Tracking the total number of requests to a REST endpoint for a\n+specific server can be done easily by the client. Tracking the total number of requests for the endpoint across all\n+servers however is more challenging. This can be done more easily by storing the deltas and allowing the TSDB to\n+compute and maintain the total count.\n+\n+Hawkular Metrics only supports the former in which each data point represents the total count; however, we can easily\n+simulate counters that store deltas. See the <<Incrementing Counters>> section for more details.\n+\n+==== Rate\n+A rate is a derived metric whose values are computed from counter data points. Rate data points can retrieved for any\n+counter. They are stored as 64-bit floating point numbers.\n+\n+== Metric Ids\n+Every metric has an id that uniquely identifies it. The id consists of three parts - the tenant id, the metric type,\n+and the metric name. The tenant id is a variable length, UTF-8 encoded string. The metric type is stored as a one byte\n+integer. The metric name is stored as a variable length, UTF-8 encoded string.\n+\n+The parts that comprise the metric id provide name spacing. A metric name only has to be unique for the metric type and","path":"src/main/jbake/content/docs/components/metrics/index.adoc","position":117,"original_position":117,"commit_id":"81276a8e113ef342c73870a1f4e1350a6fe42f61","original_commit_id":"81276a8e113ef342c73870a1f4e1350a6fe42f61","user":{"login":"stefannegrea","id":3912943,"avatar_url":"https://avatars.githubusercontent.com/u/3912943?v=3","gravatar_id":"","url":"https://api.github.com/users/stefannegrea","html_url":"https://github.com/stefannegrea","followers_url":"https://api.github.com/users/stefannegrea/followers","following_url":"https://api.github.com/users/stefannegrea/following{/other_user}","gists_url":"https://api.github.com/users/stefannegrea/gists{/gist_id}","starred_url":"https://api.github.com/users/stefannegrea/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/stefannegrea/subscriptions","organizations_url":"https://api.github.com/users/stefannegrea/orgs","repos_url":"https://api.github.com/users/stefannegrea/repos","events_url":"https://api.github.com/users/stefannegrea/events{/privacy}","received_events_url":"https://api.github.com/users/stefannegrea/received_events","type":"User","site_admin":false},"body":"`name spacing` should be a single word.","created_at":"2016-04-11T21:35:51Z","updated_at":"2016-04-11T21:35:51Z","html_url":"https://github.com/hawkular/hawkular.github.io/pull/159#discussion_r59285962","pull_request_url":"https://api.github.com/repos/hawkular/hawkular.github.io/pulls/159","_links":{"self":{"href":"https://api.github.com/repos/hawkular/hawkular.github.io/pulls/comments/59285962"},"html":{"href":"https://github.com/hawkular/hawkular.github.io/pull/159#discussion_r59285962"},"pull_request":{"href":"https://api.github.com/repos/hawkular/hawkular.github.io/pulls/159"}}},"pull_request":{"url":"https://api.github.com/repos/hawkular/hawkular.github.io/pulls/159","id":66064809,"html_url":"https://github.com/hawkular/hawkular.github.io/pull/159","diff_url":"https://github.com/hawkular/hawkular.github.io/pull/159.diff","patch_url":"https://github.com/hawkular/hawkular.github.io/pull/159.patch","issue_url":"https://api.github.com/repos/hawkular/hawkular.github.io/issues/159","number":159,"state":"open","locked":false,"title":"updating hawkular metrics docs","user":{"login":"jsanda","id":168121,"avatar_url":"https://avatars.githubusercontent.com/u/168121?v=3","gravatar_id":"","url":"https://api.github.com/users/jsanda","html_url":"https://github.com/jsanda","followers_url":"https://api.github.com/users/jsanda/followers","following_url":"https://api.github.com/users/jsanda/following{/other_user}","gists_url":"https://api.github.com/users/jsanda/gists{/gist_id}","starred_url":"https://api.github.com/users/jsanda/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/jsanda/subscriptions","organizations_url":"https://api.github.com/users/jsanda/orgs","repos_url":"https://api.github.com/users/jsanda/repos","events_url":"https://api.github.com/users/jsanda/events{/privacy}","received_events_url":"https://api.github.com/users/jsanda/received_events","type":"User","site_admin":false},"body":"","created_at":"2016-04-11T21:22:56Z","updated_at":"2016-04-11T21:35:51Z","closed_at":null,"merged_at":null,"merge_commit_sha":"e4d3e88db5fb886b40a6aa4c73779f1a66e36ed4","assignee":null,"milestone":null,"commits_url":"https://api.github.com/repos/hawkular/hawkular.github.io/pulls/159/commits","review_comments_url":"https://api.github.com/repos/hawkular/hawkular.github.io/pulls/159/comments","review_comment_url":"https://api.github.com/repos/hawkular/hawkular.github.io/pulls/comments{/number}","comments_url":"https://api.github.com/repos/hawkular/hawkular.github.io/issues/159/comments","statuses_url":"https://api.github.com/repos/hawkular/hawkular.github.io/statuses/81276a8e113ef342c73870a1f4e1350a6fe42f61","head":{"label":"jsanda:pages","ref":"pages","sha":"81276a8e113ef342c73870a1f4e1350a6fe42f61","user":{"login":"jsanda","id":168121,"avatar_url":"https://avatars.githubusercontent.com/u/168121?v=3","gravatar_id":"","url":"https://api.github.com/users/jsanda","html_url":"https://github.com/jsanda","followers_url":"https://api.github.com/users/jsanda/followers","following_url":"https://api.github.com/users/jsanda/following{/other_user}","gists_url":"https://api.github.com/users/jsanda/gists{/gist_id}","starred_url":"https://api.github.com/users/jsanda/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/jsanda/subscriptions","organizations_url":"https://api.github.com/users/jsanda/orgs","repos_url":"https://api.github.com/users/jsanda/repos","events_url":"https://api.github.com/users/jsanda/events{/privacy}","received_events_url":"https://api.github.com/users/jsanda/received_events","type":"User","site_admin":false},"repo":{"id":36505814,"name":"hawkular.github.io","full_name":"jsanda/hawkular.github.io","owner":{"login":"jsanda","id":168121,"avatar_url":"https://avatars.githubusercontent.com/u/168121?v=3","gravatar_id":"","url":"https://api.github.com/users/jsanda","html_url":"https://github.com/jsanda","followers_url":"https://api.github.com/users/jsanda/followers","following_url":"https://api.github.com/users/jsanda/following{/other_user}","gists_url":"https://api.github.com/users/jsanda/gists{/gist_id}","starred_url":"https://api.github.com/users/jsanda/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/jsanda/subscriptions","organizations_url":"https://api.github.com/users/jsanda/orgs","repos_url":"https://api.github.com/users/jsanda/repos","events_url":"https://api.github.com/users/jsanda/events{/privacy}","received_events_url":"https://api.github.com/users/jsanda/received_events","type":"User","site_admin":false},"private":false,"html_url":"https://github.com/jsanda/hawkular.github.io","description":"Web presence of Hawkular","fork":true,"url":"https://api.github.com/repos/jsanda/hawkular.github.io","forks_url":"https://api.github.com/repos/jsanda/hawkular.github.io/forks","keys_url":"https://api.github.com/repos/jsanda/hawkular.github.io/keys{/key_id}","collaborators_url":"https://api.github.com/repos/jsanda/hawkular.github.io/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/jsanda/hawkular.github.io/teams","hooks_url":"https://api.github.com/repos/jsanda/hawkular.github.io/hooks","issue_events_url":"https://api.github.com/repos/jsanda/hawkular.github.io/issues/events{/number}","events_url":"https://api.github.com/repos/jsanda/hawkular.github.io/events","assignees_url":"https://api.github.com/repos/jsanda/hawkular.github.io/assignees{/user}","branches_url":"https://api.github.com/repos/jsanda/hawkular.github.io/branches{/branch}","tags_url":"https://api.github.com/repos/jsanda/hawkular.github.io/tags","blobs_url":"https://api.github.com/repos/jsanda/hawkular.github.io/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/jsanda/hawkular.github.io/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/jsanda/hawkular.github.io/git/refs{/sha}","trees_url":"https://api.github.com/repos/jsanda/hawkular.github.io/git/trees{/sha}","statuses_url":"https://api.github.com/repos/jsanda/hawkular.github.io/statuses/{sha}","languages_url":"https://api.github.com/repos/jsanda/hawkular.github.io/languages","stargazers_url":"https://api.github.com/repos/jsanda/hawkular.github.io/stargazers","contributors_url":"https://api.github.com/repos/jsanda/hawkular.github.io/contributors","subscribers_url":"https://api.github.com/repos/jsanda/hawkular.github.io/subscribers","subscription_url":"https://api.github.com/repos/jsanda/hawkular.github.io/subscription","commits_url":"https://api.github.com/repos/jsanda/hawkular.github.io/commits{/sha}","git_commits_url":"https://api.github.com/repos/jsanda/hawkular.github.io/git/commits{/sha}","comments_url":"https://api.github.com/repos/jsanda/hawkular.github.io/comments{/number}","issue_comment_url":"https://api.github.com/repos/jsanda/hawkular.github.io/issues/comments{/number}","contents_url":"https://api.github.com/repos/jsanda/hawkular.github.io/contents/{+path}","compare_url":"https://api.github.com/repos/jsanda/hawkular.github.io/compare/{base}...{head}","merges_url":"https://api.github.com/repos/jsanda/hawkular.github.io/merges","archive_url":"https://api.github.com/repos/jsanda/hawkular.github.io/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/jsanda/hawkular.github.io/downloads","issues_url":"https://api.github.com/repos/jsanda/hawkular.github.io/issues{/number}","pulls_url":"https://api.github.com/repos/jsanda/hawkular.github.io/pulls{/number}","milestones_url":"https://api.github.com/repos/jsanda/hawkular.github.io/milestones{/number}","notifications_url":"https://api.github.com/repos/jsanda/hawkular.github.io/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/jsanda/hawkular.github.io/labels{/name}","releases_url":"https://api.github.com/repos/jsanda/hawkular.github.io/releases{/id}","deployments_url":"https://api.github.com/repos/jsanda/hawkular.github.io/deployments","created_at":"2015-05-29T13:25:36Z","updated_at":"2016-04-11T21:21:35Z","pushed_at":"2016-04-11T21:21:20Z","git_url":"git://github.com/jsanda/hawkular.github.io.git","ssh_url":"git@github.com:jsanda/hawkular.github.io.git","clone_url":"https://github.com/jsanda/hawkular.github.io.git","svn_url":"https://github.com/jsanda/hawkular.github.io","homepage":null,"size":5922,"stargazers_count":0,"watchers_count":0,"language":"CSS","has_issues":false,"has_downloads":true,"has_wiki":true,"has_pages":false,"forks_count":0,"mirror_url":null,"open_issues_count":0,"forks":0,"open_issues":0,"watchers":0,"default_branch":"pages"}},"base":{"label":"hawkular:pages","ref":"pages","sha":"00a192d8399393595779c1be5b062ec4a7e4898a","user":{"login":"hawkular","id":10179627,"avatar_url":"https://avatars.githubusercontent.com/u/10179627?v=3","gravatar_id":"","url":"https://api.github.com/users/hawkular","html_url":"https://github.com/hawkular","followers_url":"https://api.github.com/users/hawkular/followers","following_url":"https://api.github.com/users/hawkular/following{/other_user}","gists_url":"https://api.github.com/users/hawkular/gists{/gist_id}","starred_url":"https://api.github.com/users/hawkular/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/hawkular/subscriptions","organizations_url":"https://api.github.com/users/hawkular/orgs","repos_url":"https://api.github.com/users/hawkular/repos","events_url":"https://api.github.com/users/hawkular/events{/privacy}","received_events_url":"https://api.github.com/users/hawkular/received_events","type":"Organization","site_admin":false},"repo":{"id":29196628,"name":"hawkular.github.io","full_name":"hawkular/hawkular.github.io","owner":{"login":"hawkular","id":10179627,"avatar_url":"https://avatars.githubusercontent.com/u/10179627?v=3","gravatar_id":"","url":"https://api.github.com/users/hawkular","html_url":"https://github.com/hawkular","followers_url":"https://api.github.com/users/hawkular/followers","following_url":"https://api.github.com/users/hawkular/following{/other_user}","gists_url":"https://api.github.com/users/hawkular/gists{/gist_id}","starred_url":"https://api.github.com/users/hawkular/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/hawkular/subscriptions","organizations_url":"https://api.github.com/users/hawkular/orgs","repos_url":"https://api.github.com/users/hawkular/repos","events_url":"https://api.github.com/users/hawkular/events{/privacy}","received_events_url":"https://api.github.com/users/hawkular/received_events","type":"Organization","site_admin":false},"private":false,"html_url":"https://github.com/hawkular/hawkular.github.io","description":"Web presence of Hawkular","fork":false,"url":"https://api.github.com/repos/hawkular/hawkular.github.io","forks_url":"https://api.github.com/repos/hawkular/hawkular.github.io/forks","keys_url":"https://api.github.com/repos/hawkular/hawkular.github.io/keys{/key_id}","collaborators_url":"https://api.github.com/repos/hawkular/hawkular.github.io/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/hawkular/hawkular.github.io/teams","hooks_url":"https://api.github.com/repos/hawkular/hawkular.github.io/hooks","issue_events_url":"https://api.github.com/repos/hawkular/hawkular.github.io/issues/events{/number}","events_url":"https://api.github.com/repos/hawkular/hawkular.github.io/events","assignees_url":"https://api.github.com/repos/hawkular/hawkular.github.io/assignees{/user}","branches_url":"https://api.github.com/repos/hawkular/hawkular.github.io/branches{/branch}","tags_url":"https://api.github.com/repos/hawkular/hawkular.github.io/tags","blobs_url":"https://api.github.com/repos/hawkular/hawkular.github.io/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/hawkular/hawkular.github.io/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/hawkular/hawkular.github.io/git/refs{/sha}","trees_url":"https://api.github.com/repos/hawkular/hawkular.github.io/git/trees{/sha}","statuses_url":"https://api.github.com/repos/hawkular/hawkular.github.io/statuses/{sha}","languages_url":"https://api.github.com/repos/hawkular/hawkular.github.io/languages","stargazers_url":"https://api.github.com/repos/hawkular/hawkular.github.io/stargazers","contributors_url":"https://api.github.com/repos/hawkular/hawkular.github.io/contributors","subscribers_url":"https://api.github.com/repos/hawkular/hawkular.github.io/subscribers","subscription_url":"https://api.github.com/repos/hawkular/hawkular.github.io/subscription","commits_url":"https://api.github.com/repos/hawkular/hawkular.github.io/commits{/sha}","git_commits_url":"https://api.github.com/repos/hawkular/hawkular.github.io/git/commits{/sha}","comments_url":"https://api.github.com/repos/hawkular/hawkular.github.io/comments{/number}","issue_comment_url":"https://api.github.com/repos/hawkular/hawkular.github.io/issues/comments{/number}","contents_url":"https://api.github.com/repos/hawkular/hawkular.github.io/contents/{+path}","compare_url":"https://api.github.com/repos/hawkular/hawkular.github.io/compare/{base}...{head}","merges_url":"https://api.github.com/repos/hawkular/hawkular.github.io/merges","archive_url":"https://api.github.com/repos/hawkular/hawkular.github.io/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/hawkular/hawkular.github.io/downloads","issues_url":"https://api.github.com/repos/hawkular/hawkular.github.io/issues{/number}","pulls_url":"https://api.github.com/repos/hawkular/hawkular.github.io/pulls{/number}","milestones_url":"https://api.github.com/repos/hawkular/hawkular.github.io/milestones{/number}","notifications_url":"https://api.github.com/repos/hawkular/hawkular.github.io/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/hawkular/hawkular.github.io/labels{/name}","releases_url":"https://api.github.com/repos/hawkular/hawkular.github.io/releases{/id}","deployments_url":"https://api.github.com/repos/hawkular/hawkular.github.io/deployments","created_at":"2015-01-13T15:33:36Z","updated_at":"2016-04-09T19:15:00Z","pushed_at":"2016-04-11T21:22:56Z","git_url":"git://github.com/hawkular/hawkular.github.io.git","ssh_url":"git@github.com:hawkular/hawkular.github.io.git","clone_url":"https://github.com/hawkular/hawkular.github.io.git","svn_url":"https://github.com/hawkular/hawkular.github.io","homepage":null,"size":8703,"stargazers_count":6,"watchers_count":6,"language":"CSS","has_issues":true,"has_downloads":true,"has_wiki":true,"has_pages":true,"forks_count":22,"mirror_url":null,"open_issues_count":1,"forks":22,"open_issues":1,"watchers":6,"default_branch":"pages"}},"_links":{"self":{"href":"https://api.github.com/repos/hawkular/hawkular.github.io/pulls/159"},"html":{"href":"https://github.com/hawkular/hawkular.github.io/pull/159"},"issue":{"href":"https://api.github.com/repos/hawkular/hawkular.github.io/issues/159"},"comments":{"href":"https://api.github.com/repos/hawkular/hawkular.github.io/issues/159/comments"},"review_comments":{"href":"https://api.github.com/repos/hawkular/hawkular.github.io/pulls/159/comments"},"review_comment":{"href":"https://api.github.com/repos/hawkular/hawkular.github.io/pulls/comments{/number}"},"commits":{"href":"https://api.github.com/repos/hawkular/hawkular.github.io/pulls/159/commits"},"statuses":{"href":"https://api.github.com/repos/hawkular/hawkular.github.io/statuses/81276a8e113ef342c73870a1f4e1350a6fe42f61"}}}}