From 88fe340087a5f69823322ba81379f0f6be9c9666 Mon Sep 17 00:00:00 2001 From: lasea75 Date: Fri, 25 Aug 2023 11:30:38 -0500 Subject: [PATCH 1/5] Update data_model.md Added bullet points to draw attention to the importance of metric names and labels. Made small grammar changes. Signed-off-by: lasea75 --- content/docs/concepts/data_model.md | 35 +++++++++++++---------------- 1 file changed, 16 insertions(+), 19 deletions(-) diff --git a/content/docs/concepts/data_model.md b/content/docs/concepts/data_model.md index 23edfaf56..61a934206 100644 --- a/content/docs/concepts/data_model.md +++ b/content/docs/concepts/data_model.md @@ -13,31 +13,28 @@ 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 name:*** -Note: The colons are reserved for user defined recording rules. They should not -be used by exporters or direct instrumentation. + * Specifies 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: 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. + * 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. + * A label with an empty label value is considered equivalent to a label that does 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/). From 3f2e53aaf1ef21a6b16f2a173252825dd32c34a6 Mon Sep 17 00:00:00 2001 From: lasea75 Date: Thu, 28 Sep 2023 08:17:12 -0500 Subject: [PATCH 2/5] Update data_model.md Issues fixed for code-y bits and readability ;) Signed-off-by: lasea75 --- content/docs/concepts/data_model.md | 20 +++++++++----------- 1 file changed, 9 insertions(+), 11 deletions(-) diff --git a/content/docs/concepts/data_model.md b/content/docs/concepts/data_model.md index 61a934206..06afe96b4 100644 --- a/content/docs/concepts/data_model.md +++ b/content/docs/concepts/data_model.md @@ -15,25 +15,23 @@ as the result of queries. Every time series is uniquely identified by its metric name and optional key-value pairs called labels. -***metric name:*** +***Metric names:*** - * Specifies 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_:]. + * 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. -***metric labels:*** +***Metric 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. - * 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. + * 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. - * A label with an empty label value is considered equivalent to a label that does not exist. + * Labels with an empty label value are considered equivalent to labels that do not exist. See also the [best practices for naming metrics and labels](/docs/practices/naming/). From 1a61dacbc8372f83b73cabb51f2510366a80f27d Mon Sep 17 00:00:00 2001 From: lasea75 Date: Thu, 28 Sep 2023 08:41:32 -0500 Subject: [PATCH 3/5] Added time series definition to glossary Signed-off-by: lasea75 --- content/docs/introduction/glossary.md | 5 +++++ 1 file changed, 5 insertions(+) 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. + From f075f9804c86bf7c982aee3ae6d3fc99896d2b7b Mon Sep 17 00:00:00 2001 From: lasea75 Date: Thu, 28 Sep 2023 09:36:00 -0500 Subject: [PATCH 4/5] Add bullet points to improve the flow of information for the reader. Signed-off-by: lasea75 --- content/docs/practices/rules.md | 28 +++++++++++++++------------- 1 file changed, 15 insertions(+), 13 deletions(-) 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. From 6384addaa1a90765b52660a54afc8f875fa84af2 Mon Sep 17 00:00:00 2001 From: lasea75 Date: Sat, 14 Oct 2023 06:12:25 -0500 Subject: [PATCH 5/5] Cachet exporter link broken exporters.md Signed-off-by: lasea75 --- content/docs/instrumenting/exporters.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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)