From 1cc90ab42c773ffceb8d1dea765456ff785be75d Mon Sep 17 00:00:00 2001 From: Reiley Yang Date: Mon, 15 Nov 2021 10:45:11 -0800 Subject: [PATCH 01/10] Add details to Prometheus Exporter requirement --- .../metrics/sdk_exporters/prometheus.md | 21 ++++++++++++++++++- 1 file changed, 20 insertions(+), 1 deletion(-) diff --git a/specification/metrics/sdk_exporters/prometheus.md b/specification/metrics/sdk_exporters/prometheus.md index 4edcf3625b2..b1658205dec 100644 --- a/specification/metrics/sdk_exporters/prometheus.md +++ b/specification/metrics/sdk_exporters/prometheus.md @@ -4,4 +4,23 @@ Prometheus Exporter is a [Pull Metric Exporter](../sdk.md#pull-metric-exporter) which reacts to the Prometheus scraper and report the metrics passively to -[Prometheus](https://prometheus.io/). +[Prometheus](https://prometheus.io/). [Pushing +Metrics](https://prometheus.io/docs/instrumenting/pushing/) to a [Prometheus +Pushgateway](https://github.com/prometheus/pushgateway) is **not** in the scope +for now. + +Prometheus Exporter MUST support version `0.0.4` of the [Text-based +format](https://github.com/prometheus/docs/blob/main/content/docs/instrumenting/exposition_formats.md#text-based-format). + +Prometheus Exporter SHOULD only support [Cumulative +Temporality](../datamodel.md#temporality). Attempt to change the [Aggregation +Temporality](../datamodel.md#temporality) to +[Delta]((../datamodel.md#temporality)) SHOULD be treated as an error. It is +unspecified _how_ the this error should be handled (e.g. it could fail fast +during the exporter configuration time). Please refer to [Error handling in +OpenTelemetry](../../error-handling.md) for the general guidance. + +Prometheus Exporter MAY support [OpenMetrics Text +Format](https://github.com/prometheus/docs/blob/main/content/docs/instrumenting/exposition_formats.md#openmetrics-text-format), +including the +[Exemplars](https://github.com/OpenObservability/OpenMetrics/blob/main/specification/OpenMetrics.md#exemplars). From ae5bd50c7c92a05e9380bbdfeabe57de7eb92921 Mon Sep 17 00:00:00 2001 From: Reiley Yang Date: Mon, 15 Nov 2021 11:01:41 -0800 Subject: [PATCH 02/10] fix link --- specification/metrics/sdk_exporters/prometheus.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/metrics/sdk_exporters/prometheus.md b/specification/metrics/sdk_exporters/prometheus.md index b1658205dec..57a97c5518c 100644 --- a/specification/metrics/sdk_exporters/prometheus.md +++ b/specification/metrics/sdk_exporters/prometheus.md @@ -15,7 +15,7 @@ format](https://github.com/prometheus/docs/blob/main/content/docs/instrumenting/ Prometheus Exporter SHOULD only support [Cumulative Temporality](../datamodel.md#temporality). Attempt to change the [Aggregation Temporality](../datamodel.md#temporality) to -[Delta]((../datamodel.md#temporality)) SHOULD be treated as an error. It is +[Delta](../datamodel.md#temporality) SHOULD be treated as an error. It is unspecified _how_ the this error should be handled (e.g. it could fail fast during the exporter configuration time). Please refer to [Error handling in OpenTelemetry](../../error-handling.md) for the general guidance. From 789ec8684d5a150a96f20de307a4d4265f867fd0 Mon Sep 17 00:00:00 2001 From: Reiley Yang Date: Mon, 15 Nov 2021 11:26:02 -0800 Subject: [PATCH 03/10] allow push --- .../metrics/sdk_exporters/prometheus.md | 19 +++++++++++++------ 1 file changed, 13 insertions(+), 6 deletions(-) diff --git a/specification/metrics/sdk_exporters/prometheus.md b/specification/metrics/sdk_exporters/prometheus.md index 57a97c5518c..fcb303c3fa2 100644 --- a/specification/metrics/sdk_exporters/prometheus.md +++ b/specification/metrics/sdk_exporters/prometheus.md @@ -2,12 +2,19 @@ **Status**: [Experimental](../../document-status.md) -Prometheus Exporter is a [Pull Metric Exporter](../sdk.md#pull-metric-exporter) -which reacts to the Prometheus scraper and report the metrics passively to -[Prometheus](https://prometheus.io/). [Pushing -Metrics](https://prometheus.io/docs/instrumenting/pushing/) to a [Prometheus -Pushgateway](https://github.com/prometheus/pushgateway) is **not** in the scope -for now. +Prometheus Exporter is a [MetricExporter](../sdk.md#metricexporter) which reacts +to the Prometheus scraper and report the metrics passively to +[Prometheus](https://prometheus.io/), or [push +metrics](https://prometheus.io/docs/instrumenting/pushing/) to a [Prometheus +Pushgateway](https://github.com/prometheus/pushgateway). + +Prometheus Exporter SHOULD support [Pull mode](../sdk.md#pull-metric-exporter), +if possible. + +Prometheus Exporter MAY support [Push mode](../sdk.md#push-metric-exporter), if +there is a need to support short-lived applications (e.g. short-lived +service-level batch jobs, a JavaScript application running inside a web +browser). Prometheus Exporter MUST support version `0.0.4` of the [Text-based format](https://github.com/prometheus/docs/blob/main/content/docs/instrumenting/exposition_formats.md#text-based-format). From b657150f78278699d9e33254ec3f35f4972a1bee Mon Sep 17 00:00:00 2001 From: Reiley Yang Date: Mon, 15 Nov 2021 11:27:04 -0800 Subject: [PATCH 04/10] improve wording --- specification/metrics/sdk_exporters/prometheus.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/specification/metrics/sdk_exporters/prometheus.md b/specification/metrics/sdk_exporters/prometheus.md index fcb303c3fa2..2d95f4c0f20 100644 --- a/specification/metrics/sdk_exporters/prometheus.md +++ b/specification/metrics/sdk_exporters/prometheus.md @@ -13,8 +13,8 @@ if possible. Prometheus Exporter MAY support [Push mode](../sdk.md#push-metric-exporter), if there is a need to support short-lived applications (e.g. short-lived -service-level batch jobs, a JavaScript application running inside a web -browser). +service-level batch jobs, JavaScript applications running inside web browsers, +etc.). Prometheus Exporter MUST support version `0.0.4` of the [Text-based format](https://github.com/prometheus/docs/blob/main/content/docs/instrumenting/exposition_formats.md#text-based-format). From 6f5f46e27286dbf0edf4c1429480057927eaad99 Mon Sep 17 00:00:00 2001 From: Reiley Yang Date: Mon, 15 Nov 2021 12:02:49 -0800 Subject: [PATCH 05/10] fix typo --- specification/metrics/sdk_exporters/prometheus.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/metrics/sdk_exporters/prometheus.md b/specification/metrics/sdk_exporters/prometheus.md index 2d95f4c0f20..429b45848fb 100644 --- a/specification/metrics/sdk_exporters/prometheus.md +++ b/specification/metrics/sdk_exporters/prometheus.md @@ -4,7 +4,7 @@ Prometheus Exporter is a [MetricExporter](../sdk.md#metricexporter) which reacts to the Prometheus scraper and report the metrics passively to -[Prometheus](https://prometheus.io/), or [push +[Prometheus](https://prometheus.io/), or [pushes metrics](https://prometheus.io/docs/instrumenting/pushing/) to a [Prometheus Pushgateway](https://github.com/prometheus/pushgateway). From d55b65bfc16396d8d4e6772486fe42a2dd678ffa Mon Sep 17 00:00:00 2001 From: Reiley Yang Date: Mon, 15 Nov 2021 12:03:10 -0800 Subject: [PATCH 06/10] fix typo --- specification/metrics/sdk_exporters/prometheus.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/metrics/sdk_exporters/prometheus.md b/specification/metrics/sdk_exporters/prometheus.md index 429b45848fb..cf149db66e4 100644 --- a/specification/metrics/sdk_exporters/prometheus.md +++ b/specification/metrics/sdk_exporters/prometheus.md @@ -3,7 +3,7 @@ **Status**: [Experimental](../../document-status.md) Prometheus Exporter is a [MetricExporter](../sdk.md#metricexporter) which reacts -to the Prometheus scraper and report the metrics passively to +to the Prometheus scraper and reports the metrics passively to [Prometheus](https://prometheus.io/), or [pushes metrics](https://prometheus.io/docs/instrumenting/pushing/) to a [Prometheus Pushgateway](https://github.com/prometheus/pushgateway). From a19943d1c8ae2d058df7e693ef00b8336b574bf7 Mon Sep 17 00:00:00 2001 From: Reiley Yang Date: Tue, 16 Nov 2021 13:17:55 -0800 Subject: [PATCH 07/10] update based on review feedback --- specification/metrics/sdk_exporters/prometheus.md | 13 +++---------- 1 file changed, 3 insertions(+), 10 deletions(-) diff --git a/specification/metrics/sdk_exporters/prometheus.md b/specification/metrics/sdk_exporters/prometheus.md index cf149db66e4..bc2ec169913 100644 --- a/specification/metrics/sdk_exporters/prometheus.md +++ b/specification/metrics/sdk_exporters/prometheus.md @@ -11,21 +11,14 @@ Pushgateway](https://github.com/prometheus/pushgateway). Prometheus Exporter SHOULD support [Pull mode](../sdk.md#pull-metric-exporter), if possible. -Prometheus Exporter MAY support [Push mode](../sdk.md#push-metric-exporter), if -there is a need to support short-lived applications (e.g. short-lived -service-level batch jobs, JavaScript applications running inside web browsers, -etc.). +Support for [Push mode](../sdk.md#push-metric-exporter) is out of scope for the +initial release. Prometheus Exporter MUST support version `0.0.4` of the [Text-based format](https://github.com/prometheus/docs/blob/main/content/docs/instrumenting/exposition_formats.md#text-based-format). Prometheus Exporter SHOULD only support [Cumulative -Temporality](../datamodel.md#temporality). Attempt to change the [Aggregation -Temporality](../datamodel.md#temporality) to -[Delta](../datamodel.md#temporality) SHOULD be treated as an error. It is -unspecified _how_ the this error should be handled (e.g. it could fail fast -during the exporter configuration time). Please refer to [Error handling in -OpenTelemetry](../../error-handling.md) for the general guidance. +Temporality](../datamodel.md#temporality). Prometheus Exporter MAY support [OpenMetrics Text Format](https://github.com/prometheus/docs/blob/main/content/docs/instrumenting/exposition_formats.md#openmetrics-text-format), From 32381e0ea9ae98a20d0ed354799a561f3e9132a0 Mon Sep 17 00:00:00 2001 From: Reiley Yang Date: Wed, 17 Nov 2021 19:40:56 -0800 Subject: [PATCH 08/10] update based on review feedback --- .../metrics/sdk_exporters/prometheus.md | 21 ++++++++----------- 1 file changed, 9 insertions(+), 12 deletions(-) diff --git a/specification/metrics/sdk_exporters/prometheus.md b/specification/metrics/sdk_exporters/prometheus.md index bc2ec169913..f6b1231460f 100644 --- a/specification/metrics/sdk_exporters/prometheus.md +++ b/specification/metrics/sdk_exporters/prometheus.md @@ -2,24 +2,21 @@ **Status**: [Experimental](../../document-status.md) -Prometheus Exporter is a [MetricExporter](../sdk.md#metricexporter) which reacts -to the Prometheus scraper and reports the metrics passively to -[Prometheus](https://prometheus.io/), or [pushes -metrics](https://prometheus.io/docs/instrumenting/pushing/) to a [Prometheus -Pushgateway](https://github.com/prometheus/pushgateway). +Prometheus Exporter is a [Pull Metric Exporter](../sdk.md#pull-metric-exporter) +which reports metrics by responding to the [Prometheus](https://prometheus.io/) +scraper requests. -Prometheus Exporter SHOULD support [Pull mode](../sdk.md#pull-metric-exporter), -if possible. +Prometheus Exporter MUST support [Pull mode](../sdk.md#pull-metric-exporter). -Support for [Push mode](../sdk.md#push-metric-exporter) is out of scope for the -initial release. +Prometheus Exporter MUST NOT support [Push +mode](../sdk.md#push-metric-exporter). + +Prometheus Exporter MUST only support [Cumulative +Temporality](../datamodel.md#temporality). Prometheus Exporter MUST support version `0.0.4` of the [Text-based format](https://github.com/prometheus/docs/blob/main/content/docs/instrumenting/exposition_formats.md#text-based-format). -Prometheus Exporter SHOULD only support [Cumulative -Temporality](../datamodel.md#temporality). - Prometheus Exporter MAY support [OpenMetrics Text Format](https://github.com/prometheus/docs/blob/main/content/docs/instrumenting/exposition_formats.md#openmetrics-text-format), including the From 878a6ed4544f9871eae55bcb23d9de31bafc7e25 Mon Sep 17 00:00:00 2001 From: Reiley Yang Date: Wed, 17 Nov 2021 19:44:58 -0800 Subject: [PATCH 09/10] update changelog --- CHANGELOG.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index d9dc1f9d91c..4ae667f7ede 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -15,6 +15,8 @@ release. - Rename None aggregation to Drop. ([#2101](https://github.com/open-telemetry/opentelemetry-specification/pull/2101)) +- Add details to the Prometheus Exporter requirements. + ([#2124](https://github.com/open-telemetry/opentelemetry-specification/pull/2124)) ### Logs From dd8a5cc5de1550ac31fcbcb72e2dec946820cb0d Mon Sep 17 00:00:00 2001 From: Joshua MacDonald Date: Tue, 30 Nov 2021 10:27:42 -0800 Subject: [PATCH 10/10] Apply suggestions from code review Committing these as Reiley has requested for help from native english speakers. Co-authored-by: Tyler Yahn --- specification/metrics/sdk_exporters/prometheus.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/specification/metrics/sdk_exporters/prometheus.md b/specification/metrics/sdk_exporters/prometheus.md index f6b1231460f..c12994a0276 100644 --- a/specification/metrics/sdk_exporters/prometheus.md +++ b/specification/metrics/sdk_exporters/prometheus.md @@ -2,22 +2,22 @@ **Status**: [Experimental](../../document-status.md) -Prometheus Exporter is a [Pull Metric Exporter](../sdk.md#pull-metric-exporter) +A Prometheus Exporter is a [Pull Metric Exporter](../sdk.md#pull-metric-exporter) which reports metrics by responding to the [Prometheus](https://prometheus.io/) scraper requests. -Prometheus Exporter MUST support [Pull mode](../sdk.md#pull-metric-exporter). +A Prometheus Exporter MUST support [Pull mode](../sdk.md#pull-metric-exporter). -Prometheus Exporter MUST NOT support [Push +A Prometheus Exporter MUST NOT support [Push mode](../sdk.md#push-metric-exporter). -Prometheus Exporter MUST only support [Cumulative +A Prometheus Exporter MUST only support [Cumulative Temporality](../datamodel.md#temporality). -Prometheus Exporter MUST support version `0.0.4` of the [Text-based +A Prometheus Exporter MUST support version `0.0.4` of the [Text-based format](https://github.com/prometheus/docs/blob/main/content/docs/instrumenting/exposition_formats.md#text-based-format). -Prometheus Exporter MAY support [OpenMetrics Text +A Prometheus Exporter MAY support [OpenMetrics Text Format](https://github.com/prometheus/docs/blob/main/content/docs/instrumenting/exposition_formats.md#openmetrics-text-format), including the [Exemplars](https://github.com/OpenObservability/OpenMetrics/blob/main/specification/OpenMetrics.md#exemplars).