From 99e3ec5a594517c0eff3d51f10ac07b641e27ada Mon Sep 17 00:00:00 2001 From: David Ashpole Date: Thu, 15 Sep 2022 15:55:16 +0000 Subject: [PATCH 1/6] handle instrumentation scope when translating to and from prometheus --- specification/metrics/data-model.md | 57 +++++++++++++++++++++++++++++ 1 file changed, 57 insertions(+) diff --git a/specification/metrics/data-model.md b/specification/metrics/data-model.md index 24e162c40c5..b204903689c 100644 --- a/specification/metrics/data-model.md +++ b/specification/metrics/data-model.md @@ -66,9 +66,11 @@ linkTitle: Data Model + [Dropped Types](#dropped-types) + [Start Time](#start-time) + [Exemplars](#exemplars-1) + + [Instrumentation Scope](#instrumentation-scope) + [Resource Attributes](#resource-attributes) * [OTLP Metric points to Prometheus](#otlp-metric-points-to-prometheus) + [Metric Metadata](#metric-metadata-1) + + [Instrumentation Scope](#instrumentation-scope-1) + [Gauges](#gauges-1) + [Sums](#sums-1) + [Histograms](#histograms-1) @@ -1385,6 +1387,48 @@ retrieved from the `trace_id` and `span_id` label keys, respectively. All labels not used for the trace and span ids MUST be added to the OpenTelemetry exemplar as attributes. +#### Instrumentation Scope + +Each `opentelemetry_scope_info` metric point present in a batch of metrics +SHOULD be dropped from the incoming scrape, and converted to an instrumentation +scope. The `opentelemetry_scope_name` and `opentelemetry_scope_version` labels, +if present, MUST be converted to the Name and Version of the Instrumentation +Scope. Additional labels MUST be added as scope attributes, with keys and +values unaltered. Other metrics in the batch which have +`opentelemetry_scope_name` and `opentelemetry_scope_version` +labels that match an instrumentation scope MUST be placed within the matching +instrumentation scope, and MUST remove those labels. For example, the +OpenMetrics metrics: + +``` +# TYPE opentelemetry_scope_info info +opentelemetry_scope_info{opentelemetry_scope_name="go.opentelemetry.io.contrib.instrumentation.net.http.otelhttp",opentelemetry_scope_version="v0.24.0",library_mascot="bear"} 1 +# TYPE otelhttp_http_server_duration counter +otelhttp_http_server_duration{opentelemetry_scope_name="go.opentelemetry.io.contrib.instrumentation.net.http.otelhttp",opentelemetry_scope_version="v0.24.0"...} 1 +``` + +becomes: + +```yaml +# within a resource_metrics +scope_metrics: + scope: + name: go.opentelemetry.io.contrib.instrumentation.net.http.otelhttp + version: v0.24.0 + attributes: + library_mascot: bear + metrics: + - name: http_server_duration + data: + sum: + data_points: + - value: 1 +``` + +Metrics which are not found to be associated with an instrumentation scope are +all placed within an empty instrumentation scope, and do not have any labels +removed. + #### Resource Attributes When scraping a Prometheus endpoint, resource attributes MUST be added to the @@ -1445,6 +1489,19 @@ The data point type of an OTLP metric MUST be added as [OpenMetrics TYPE metadata](https://github.com/OpenObservability/OpenMetrics/blob/main/specification/OpenMetrics.md#metricfamily). It also dictates type-specific conversion rules listed below. +#### Instrumentation Scope + +Prometheus exporters SHOULD generate an [Info](https://github.com/OpenObservability/OpenMetrics/blob/main/specification/OpenMetrics.md#info)-typed +metric named `opentelemetry_scope_info`. If present, Instrumentation +Scope `name` and `version` MUST be added as `opentelemetry_scope_name` and +`opentelemetry_scope_version` labels. Scope attributes MUST also be added as +labels following the rules described in the +[`Metric Attributes`](#metric-attributes) section below. + +Prometheus exporters MUST add the scope name as the `opentelemetry_scope_name` +label and SHOULD add the scope version as the `opentelemetry_scope_version` label +on all metrics points. + #### Gauges An [OpenTelemetry Gauge](#gauge) MUST be converted to a Prometheus Gauge. From cb04666129ef4300def3b38adeed97387722b663 Mon Sep 17 00:00:00 2001 From: David Ashpole Date: Tue, 20 Sep 2022 14:11:42 +0000 Subject: [PATCH 2/6] rename scope labels to start with otel instead of opentelemetry --- specification/metrics/data-model.md | 33 ++++++++++++++--------------- 1 file changed, 16 insertions(+), 17 deletions(-) diff --git a/specification/metrics/data-model.md b/specification/metrics/data-model.md index b204903689c..d1403a780ec 100644 --- a/specification/metrics/data-model.md +++ b/specification/metrics/data-model.md @@ -1391,20 +1391,19 @@ exemplar as attributes. Each `opentelemetry_scope_info` metric point present in a batch of metrics SHOULD be dropped from the incoming scrape, and converted to an instrumentation -scope. The `opentelemetry_scope_name` and `opentelemetry_scope_version` labels, -if present, MUST be converted to the Name and Version of the Instrumentation -Scope. Additional labels MUST be added as scope attributes, with keys and -values unaltered. Other metrics in the batch which have -`opentelemetry_scope_name` and `opentelemetry_scope_version` +scope. The `otel_scope_name` and `otel_scope_version` labels, if present, MUST +be converted to the Name and Version of the Instrumentation Scope. Additional +labels MUST be added as scope attributes, with keys and values unaltered. Other +metrics in the batch which have `otel_scope_name` and `otel_scope_version` labels that match an instrumentation scope MUST be placed within the matching instrumentation scope, and MUST remove those labels. For example, the OpenMetrics metrics: ``` # TYPE opentelemetry_scope_info info -opentelemetry_scope_info{opentelemetry_scope_name="go.opentelemetry.io.contrib.instrumentation.net.http.otelhttp",opentelemetry_scope_version="v0.24.0",library_mascot="bear"} 1 -# TYPE otelhttp_http_server_duration counter -otelhttp_http_server_duration{opentelemetry_scope_name="go.opentelemetry.io.contrib.instrumentation.net.http.otelhttp",opentelemetry_scope_version="v0.24.0"...} 1 +opentelemetry_scope_info{otel_scope_name="go.opentelemetry.io.contrib.instrumentation.net.http.otelhttp",otel_scope_version="v0.24.0",library_mascot="bear"} 1 +# TYPE http_server_duration counter +http_server_duration{otel_scope_name="go.opentelemetry.io.contrib.instrumentation.net.http.otelhttp",otel_scope_version="v0.24.0"...} 1 ``` becomes: @@ -1492,15 +1491,15 @@ It also dictates type-specific conversion rules listed below. #### Instrumentation Scope Prometheus exporters SHOULD generate an [Info](https://github.com/OpenObservability/OpenMetrics/blob/main/specification/OpenMetrics.md#info)-typed -metric named `opentelemetry_scope_info`. If present, Instrumentation -Scope `name` and `version` MUST be added as `opentelemetry_scope_name` and -`opentelemetry_scope_version` labels. Scope attributes MUST also be added as -labels following the rules described in the -[`Metric Attributes`](#metric-attributes) section below. - -Prometheus exporters MUST add the scope name as the `opentelemetry_scope_name` -label and SHOULD add the scope version as the `opentelemetry_scope_version` label -on all metrics points. +metric named `opentelemetry_scope_info`. If present, Instrumentation Scope +`name` and `version` MUST be added as `otel_scope_name` and +`otel_scope_version` labels. Scope attributes MUST also be added as labels +following the rules described in the [`Metric Attributes`](#metric-attributes) +section below. + +Prometheus exporters MUST add the scope name as the `otel_scope_name` label and +SHOULD add the scope version as the `otel_scope_version` label on all metrics +points. #### Gauges From 4904d74c8eff6fe9644a40705647c02d0552f40e Mon Sep 17 00:00:00 2001 From: David Ashpole Date: Wed, 21 Sep 2022 18:29:54 +0000 Subject: [PATCH 3/6] address feedback --- specification/metrics/data-model.md | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/specification/metrics/data-model.md b/specification/metrics/data-model.md index d1403a780ec..8ec3f942df5 100644 --- a/specification/metrics/data-model.md +++ b/specification/metrics/data-model.md @@ -1389,7 +1389,7 @@ exemplar as attributes. #### Instrumentation Scope -Each `opentelemetry_scope_info` metric point present in a batch of metrics +Each `otel_scope_info` metric point present in a batch of metrics SHOULD be dropped from the incoming scrape, and converted to an instrumentation scope. The `otel_scope_name` and `otel_scope_version` labels, if present, MUST be converted to the Name and Version of the Instrumentation Scope. Additional @@ -1400,8 +1400,8 @@ instrumentation scope, and MUST remove those labels. For example, the OpenMetrics metrics: ``` -# TYPE opentelemetry_scope_info info -opentelemetry_scope_info{otel_scope_name="go.opentelemetry.io.contrib.instrumentation.net.http.otelhttp",otel_scope_version="v0.24.0",library_mascot="bear"} 1 +# TYPE otel_scope_info info +otel_scope_info{otel_scope_name="go.opentelemetry.io.contrib.instrumentation.net.http.otelhttp",otel_scope_version="v0.24.0",library_mascot="bear"} 1 # TYPE http_server_duration counter http_server_duration{otel_scope_name="go.opentelemetry.io.contrib.instrumentation.net.http.otelhttp",otel_scope_version="v0.24.0"...} 1 ``` @@ -1491,15 +1491,14 @@ It also dictates type-specific conversion rules listed below. #### Instrumentation Scope Prometheus exporters SHOULD generate an [Info](https://github.com/OpenObservability/OpenMetrics/blob/main/specification/OpenMetrics.md#info)-typed -metric named `opentelemetry_scope_info`. If present, Instrumentation Scope +metric named `otel_scope_info`. If present, Instrumentation Scope `name` and `version` MUST be added as `otel_scope_name` and `otel_scope_version` labels. Scope attributes MUST also be added as labels following the rules described in the [`Metric Attributes`](#metric-attributes) section below. Prometheus exporters MUST add the scope name as the `otel_scope_name` label and -SHOULD add the scope version as the `otel_scope_version` label on all metrics -points. +the scope version as the `otel_scope_version` label on all metric points. #### Gauges From 9c44f32741b0be8b4e80521b86065cd57ffda399 Mon Sep 17 00:00:00 2001 From: David Ashpole Date: Thu, 22 Sep 2022 14:11:17 +0000 Subject: [PATCH 4/6] changelog --- CHANGELOG.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 87b719942ec..a90c249db94 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -21,6 +21,9 @@ release. ### Compatibility +- Specify how Prometheus exporters and receivers handle instrumentation scope. + ([#2703](https://github.com/open-telemetry/opentelemetry-specification/pull/2703)). + ### OpenTelemetry Protocol ### SDK Configuration From 227c2f7c12ef500495ac8e6619602b0cb9e598b7 Mon Sep 17 00:00:00 2001 From: David Ashpole Date: Mon, 26 Sep 2022 13:34:25 +0000 Subject: [PATCH 5/6] clarify MUST be placed in an empty IS --- specification/metrics/data-model.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/specification/metrics/data-model.md b/specification/metrics/data-model.md index 8ec3f942df5..7910093f8fb 100644 --- a/specification/metrics/data-model.md +++ b/specification/metrics/data-model.md @@ -1424,8 +1424,8 @@ scope_metrics: - value: 1 ``` -Metrics which are not found to be associated with an instrumentation scope are -all placed within an empty instrumentation scope, and do not have any labels +Metrics which are not found to be associated with an instrumentation scope MUST +all be placed within an empty instrumentation scope, and MUST not have any labels removed. #### Resource Attributes From 02d434754e50584c4a5ea5f8a674dac33220b1de Mon Sep 17 00:00:00 2001 From: David Ashpole Date: Mon, 26 Sep 2022 20:37:11 +0000 Subject: [PATCH 6/6] allow disabling instrumentation scope labels --- specification/metrics/data-model.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/specification/metrics/data-model.md b/specification/metrics/data-model.md index 7910093f8fb..d1ba54992dc 100644 --- a/specification/metrics/data-model.md +++ b/specification/metrics/data-model.md @@ -1498,7 +1498,11 @@ following the rules described in the [`Metric Attributes`](#metric-attributes) section below. Prometheus exporters MUST add the scope name as the `otel_scope_name` label and -the scope version as the `otel_scope_version` label on all metric points. +the scope version as the `otel_scope_version` label on all metric points by +default. + +Prometheus exporters SHOULD provide a configuration option to disable the +`otel_scope_info` metric and `otel_scope_` labels. #### Gauges