diff --git a/content/docs/concepts/data_model.md b/content/docs/concepts/data_model.md index 23edfaf56..06afe96b4 100644 --- a/content/docs/concepts/data_model.md +++ b/content/docs/concepts/data_model.md @@ -13,31 +13,26 @@ as the result of queries. ## Metric names and labels -Every time series is uniquely identified by its _metric name_ and optional -key-value pairs called _labels_. +Every time series is uniquely identified by its metric name and optional key-value pairs called labels. -The _metric name_ specifies the general feature of a system that is measured -(e.g. `http_requests_total` - the total number of HTTP requests received). It -may contain ASCII letters and digits, as well as underscores and colons. It -must match the regex `[a-zA-Z_:][a-zA-Z0-9_:]*`. +***Metric names:*** -Note: The colons are reserved for user defined recording rules. They should not -be used by exporters or direct instrumentation. + * Specify the general feature of a system that is measured (e.g. `http_requests_total` - the total number of HTTP requests received). + * Metric names may contain ASCII letters, digits, underscores, and colons. It must match the regex `[a-zA-Z_:][a-zA-Z0-9_:]*`. + +Note: The colons are reserved for user defined recording rules. They should not be used by exporters or direct instrumentation. -Labels enable Prometheus's dimensional data model: any given combination of -labels for the same metric name identifies a particular dimensional -instantiation of that metric (for example: all HTTP requests that used the -method `POST` to the `/api/tracks` handler). The query language -allows filtering and aggregation based on these dimensions. Changing any label -value, including adding or removing a label, will create a new time series. -Label names may contain ASCII letters, numbers, as well as underscores. They -must match the regex `[a-zA-Z_][a-zA-Z0-9_]*`. Label names beginning with `__` -(two "_") are reserved for internal use. -Label values may contain any Unicode characters. +***Metric labels:*** + + * Enable Prometheus's dimensional data model to identify any given combination of labels for the same metric name. It identifies a particular dimensional instantiation of that metric (for example: all HTTP requests that used the method `POST` to the `/api/tracks` handler). The query language allows filtering and aggregation based on these dimensions. + * The change of any labels value, including adding or removing labels, will create a new time series. + * Labels may contain ASCII letters, numbers, as well as underscores. They must match the regex `[a-zA-Z_][a-zA-Z0-9_]*`. + * Label names beginning with `__` (two "_") are reserved for internal use. + * Label values may contain any Unicode characters. + * Labels with an empty label value are considered equivalent to labels that do not exist. -A label with an empty label value is considered equivalent to a label that does not exist. See also the [best practices for naming metrics and labels](/docs/practices/naming/). diff --git a/content/docs/instrumenting/exporters.md b/content/docs/instrumenting/exporters.md index d6b84e671..77eff08ed 100644 --- a/content/docs/instrumenting/exporters.md +++ b/content/docs/instrumenting/exporters.md @@ -201,7 +201,7 @@ wide variety of JVM-based applications, for example [Kafka](http://kafka.apache. * [Bungeecord exporter](https://github.com/weihao/bungeecord-prometheus-exporter) * [BOSH exporter](https://github.com/cloudfoundry-community/bosh_exporter) * [cAdvisor](https://github.com/google/cadvisor) - * [Cachet exporter](https://github.com/ContaAzul/cachet_exporter) + * Cachet exporter * [ccache exporter](https://github.com/virtualtam/ccache_exporter) * [c-lightning exporter](https://github.com/lightningd/plugins/tree/master/prometheus) * [DHCPD leases exporter](https://github.com/DRuggeri/dhcpd_leases_exporter) diff --git a/content/docs/introduction/glossary.md b/content/docs/introduction/glossary.md index 239d46172..1e6dc841d 100644 --- a/content/docs/introduction/glossary.md +++ b/content/docs/introduction/glossary.md @@ -122,3 +122,8 @@ being included in notifications. A target is the definition of an object to scrape. For example, what labels to apply, any authentication required to connect, or other information that defines how the scrape will occur. +### Time Series + +The Prometheus time series are streams of timestamped values belonging to the same metric and the same set of labeled dimensions. +Prometheus stores all data as time series. + diff --git a/content/docs/practices/rules.md b/content/docs/practices/rules.md index 257628f8c..12c16ab5b 100644 --- a/content/docs/practices/rules.md +++ b/content/docs/practices/rules.md @@ -9,16 +9,15 @@ A consistent naming scheme for [recording rules](/docs/prometheus/latest/configu makes it easier to interpret the meaning of a rule at a glance. It also avoids mistakes by making incorrect or meaningless calculations stand out. -This page documents how to correctly do aggregation and suggests a naming -convention. +This page documents proper naming conventions and aggregation for recording rules. -## Naming and aggregation +## Naming -Recording rules should be of the general form `level:metric:operations`. -`level` represents the aggregation level and labels of the rule output. -`metric` is the metric name and should be unchanged other than stripping -`_total` off counters when using `rate()` or `irate()`. `operations` is a list -of operations that were applied to the metric, newest operation first. +* Recording rules should be of the general form `level:metric:operations`. +* `level` represents the aggregation level and labels of the rule output. +* `metric` is the metric name and should be unchanged other than stripping. +* `_total` off counters when using `rate()` or `irate()`. +* `operations` is a list of operations that were applied to the metric, newest operation first. Keeping the metric name unchanged makes it easy to know what a metric is and easy to find in the codebase. @@ -31,17 +30,20 @@ If there is no obvious operation to use, use `sum`. When taking a ratio by doing division, separate the metrics using `_per_` and call the operation `ratio`. -When aggregating up ratios, aggregate up the numerator and denominator -separately and then divide. Do not take the average of a ratio or average of an -average as that is not statistically valid. +## Aggregation -When aggregating up the `_count` and `_sum` of a Summary and dividing to +* When aggregating up ratios, aggregate up the numerator and denominator +separately and then divide. +* Do not take the average of a ratio or average of an +average, as that is not statistically valid. + +* When aggregating up the `_count` and `_sum` of a Summary and dividing to calculate average observation size, treating it as a ratio would be unwieldy. Instead keep the metric name without the `_count` or `_sum` suffix and replace the `rate` in the operation with `mean`. This represents the average observation size over that time period. -Always specify a `without` clause with the labels you are aggregating away. +* Always specify a `without` clause with the labels you are aggregating away. This is to preserve all the other labels such as `job`, which will avoid conflicts and give you more useful metrics and alerts.