[receiver/prometheus] Generate Scope Attributes from otel_scope_<attribute-name> labels (#46612)

#### Description

Add support for extracting scope attributes from
otel_scope_<attribute-name> labels on metrics in the Prometheus
receiver, per the spec change.
This is gated behind
`receiver.prometheusreceiver.UseScopeAttributeLabels` (alpha, disabled
by default). The gate acts as a switch:
* Disabled (default): existing behavior — scope attributes come from
otel_scope_info, and otel_scope_<attr> labels are treated as regular
data point attributes.
* Enabled: scope attributes are read from otel_scope_<attr> labels on
every metric, otel_scope_info is ignored.

#### Link to tracking issue
Fixes
#41502

#### Testing
* Added integration tests (TestScopeAttributeLabelsFeatureGate) covering
both gate states: enabled extracts scope attributes and splits scopes;
disabled preserves otel_scope_* as regular labels.
* Existing TestScopeInfoScopeAttributes and all internal tests pass
unchanged.

---------

Signed-off-by: Arthur Silva Sens <arthursens2005@gmail.com>

Author: ArthurSens

.chloggen/enhancement_prometheusreceiver_scope_attribute_labels.yaml

@@ -0,0 +1,32 @@
+# Use this changelog template to create an entry for release notes.
+
+# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix'
+change_type: enhancement
+
+# The name of the component, or a single word describing the area of concern, (e.g. receiver/filelog)
+component: receiver/prometheus
+
+# A brief description of the change.  Surround your text with quotes ("") if it needs to start with a backtick (`).
+note: Add support for reading instrumentation scope attributes from `otel_scope_<attribute-name>` labels while feature-gating deprecation of `otel_scope_info`.
+
+# Mandatory: One or more tracking issues related to the change. You can use the PR number here if no issue exists.
+issues: [41502]
+
+# (Optional) One or more lines of additional information to render under the primary note.
+# These lines will be padded with 2 spaces and then inserted directly into the document.
+# Use pipe (|) for multiline entries.
+subtext: |
+  Scope attributes are always extracted from `otel_scope_<attribute-name>` labels on metrics.
+  The `receiver.prometheusreceiver.IgnoreScopeInfoMetric` feature gate (alpha, disabled by default)
+  controls only whether the legacy `otel_scope_info` metric is ignored for scope attribute extraction.
+  When the gate is disabled, both mechanisms coexist to support migration.
+  See the specification change for motivation: https://github.com/open-telemetry/opentelemetry-specification/pull/4505
+
+# If your change doesn't affect end users or the exported elements of any package,
+# you should instead start your pull request title with [chore] or use the "Skip Changelog" label.
+# Optional: The change log or logs in which this entry should be included.
+# e.g. '[user]' or '[user, api]'
+# Include 'user' if the change is relevant to end users.
+# Include 'api' if there is a change to a library API.
+# Default: '[user]'
+change_logs: []

pkg/translator/prometheus/constants.go

@@ -20,6 +20,10 @@ const (
 	// attributes in Prometheus format:
 	// https://github.com/open-telemetry/opentelemetry-specification/blob/e6eccba97ebaffbbfad6d4358408a2cead0ec2df/specification/compatibility/prometheus_and_openmetrics.md#instrumentation-scope
 	ScopeInfoMetricName = "otel_scope_info"
+	// ScopeLabelPrefix prefixes instrumentation scope labels in Prometheus
+	// format:
+	// https://github.com/open-telemetry/opentelemetry-specification/blob/fd43145dde7e5192ebc59a20992d98a3e6af5553/specification/compatibility/prometheus_and_openmetrics.md#instrumentation-scope
+	ScopeLabelPrefix = "otel_scope_"
 	// ScopeNameLabelKey is the name of the label key used to identify the name
 	// of the OpenTelemetry scope which produced the metric:
 	// https://github.com/open-telemetry/opentelemetry-specification/blob/e6eccba97ebaffbbfad6d4358408a2cead0ec2df/specification/compatibility/prometheus_and_openmetrics.md#instrumentation-scope

receiver/prometheusreceiver/documentation.md

@@ -10,6 +10,7 @@ This component has the following feature gates:
 | ------------ | ----- | ----------- | ------------ | ---------- | --------- |
 | `receiver.prometheusreceiver.EnableCreatedTimestampZeroIngestion` | alpha | Enables the Prometheus created-timestamps-zero-injection feature. Created timestamps are injected as 0-valued samples when appropriate. This is disabled by default due to worse CPU performance with higher metric volumes. | v0.113.0 | N/A | [Link](https://github.com/open-telemetry/opentelemetry-collector-contrib/issues/40355) |
 | `receiver.prometheusreceiver.EnableNativeHistograms` | stable | Converts scraped Prometheus native histograms into OpenTelemetry exponential histograms. You still need to configure 'scrape_native_histograms: true' in your Prometheus scrape config to actually scrape native histograms. For mixed histograms (both classic and native), only the native histogram buckets are used. | v0.142.0 | v0.145.0 | [Link](https://github.com/open-telemetry/opentelemetry-collector-contrib/pull/34473) |
+| `receiver.prometheusreceiver.IgnoreScopeInfoMetric` | alpha | When enabled, the `otel_scope_info` metric is ignored for scope attribute extraction. | v0.148.0 | N/A | [Link](https://github.com/open-telemetry/opentelemetry-collector-contrib/issues/41502) |
 | `receiver.prometheusreceiver.RemoveStartTimeAdjustment` | stable | When enabled, the Prometheus receiver will leave the start time unset. Use the metric_start_time processor instead if you need this functionality. | v0.121.0 | v0.142.0 | [Link](https://github.com/open-telemetry/opentelemetry-collector-contrib/pull/36364) |
 | `receiver.prometheusreceiver.UseCreatedMetric` | deprecated | When enabled, the Prometheus receiver will retrieve the start time for Summary, Histogram and Sum metrics from _created metric. | v0.89.0 | v0.141.0 | [Link](https://github.com/open-telemetry/opentelemetry-collector-contrib/issues/21909) |
 

receiver/prometheusreceiver/go.mod

@@ -11,8 +11,10 @@ require (
 	github.com/grafana/regexp v0.0.0-20250905093917-f7b3be9d1853
 	github.com/mwitkow/go-conntrack v0.0.0-20190716064945-2f068394615f
 	github.com/open-telemetry/opentelemetry-collector-contrib/exporter/prometheusremotewriteexporter v0.148.0
+	github.com/open-telemetry/opentelemetry-collector-contrib/internal/common v0.148.0
 	github.com/open-telemetry/opentelemetry-collector-contrib/internal/coreinternal v0.148.0
 	github.com/open-telemetry/opentelemetry-collector-contrib/pkg/pdatatest v0.148.0
+	github.com/open-telemetry/opentelemetry-collector-contrib/pkg/pdatautil v0.148.0
 	github.com/open-telemetry/opentelemetry-collector-contrib/pkg/translator/prometheus v0.148.0
 	github.com/prometheus/client_golang v1.23.2
 	github.com/prometheus/common v0.67.5
@@ -211,7 +213,6 @@ require (
 	github.com/oklog/ulid/v2 v2.1.1 // indirect
 	github.com/open-telemetry/opentelemetry-collector-contrib/internal/exp/metrics v0.148.0 // indirect
 	github.com/open-telemetry/opentelemetry-collector-contrib/pkg/golden v0.148.0 // indirect
-	github.com/open-telemetry/opentelemetry-collector-contrib/pkg/pdatautil v0.148.0 // indirect
 	github.com/open-telemetry/opentelemetry-collector-contrib/pkg/resourcetotelemetry v0.148.0 // indirect
 	github.com/open-telemetry/opentelemetry-collector-contrib/pkg/translator/prometheusremotewrite v0.148.0 // indirect
 	github.com/open-telemetry/opentelemetry-collector-contrib/processor/deltatocumulativeprocessor v0.148.0 // indirect

receiver/prometheusreceiver/internal/metadata/generated_feature_gates.go

@@ -432,6 +432,9 @@ func populateAttributes(mType pmetric.MetricType, ls labels.Labels, dest pcommon
 		if j < len(names) && l.Name == names[j] {
 			return
 		}
+		if strings.HasPrefix(l.Name, prometheus.ScopeLabelPrefix) {
+			return
+		}
 		if l.Value == "" {
 			// empty label values should be omitted
 			return

receiver/prometheusreceiver/internal/metricfamily.go

@@ -257,7 +257,7 @@ func TestMetricGroupData_toDistributionUnitTest(t *testing.T) {
 				} else {
 					lbls = tt.labels.Copy()
 				}
-				sRef, _ := getSeriesRef(nil, lbls, mp.mtype)
+				sRef, _ := getSeriesRefWithoutScopeLabels(nil, lbls, mp.mtype)
 				err := mp.addSeries(sRef, tv.metric, lbls, tv.at, tv.value)
 				if tt.wantErr {
 					if i != 0 {
@@ -405,7 +405,7 @@ func TestMetricGroupData_toNHCBDistributionUnitTest(t *testing.T) {
 	for _, tt := range tests {
 		t.Run(tt.name, func(t *testing.T) {
 			mp := newMetricFamily(tt.metricName, mc, zap.NewNop(), false, false)
-			sRef, _ := getSeriesRef(nil, tt.labels, mp.mtype)
+			sRef, _ := getSeriesRefWithoutScopeLabels(nil, tt.labels, mp.mtype)
 
 			err := mp.addNHCBSeries(sRef, tt.metricName, tt.labels, tt.intervalStartTimeMs, tt.integerHistogram, tt.floatHistogram)
 			require.NoError(t, err)
@@ -575,14 +575,14 @@ func TestMetricGroupData_toExponentialDistributionUnitTest(t *testing.T) {
 				switch {
 				case tv.integerHistogram != nil:
 					mp.mtype = pmetric.MetricTypeExponentialHistogram
-					sRef, _ := getSeriesRef(nil, lbls, mp.mtype)
+					sRef, _ := getSeriesRefWithoutScopeLabels(nil, lbls, mp.mtype)
 					err = mp.addExponentialHistogramSeries(sRef, tv.metric, lbls, tv.at, tv.integerHistogram, nil)
 				case tv.floatHistogram != nil:
 					mp.mtype = pmetric.MetricTypeExponentialHistogram
-					sRef, _ := getSeriesRef(nil, lbls, mp.mtype)
+					sRef, _ := getSeriesRefWithoutScopeLabels(nil, lbls, mp.mtype)
 					err = mp.addExponentialHistogramSeries(sRef, tv.metric, lbls, tv.at, nil, tv.floatHistogram)
 				default:
-					sRef, _ := getSeriesRef(nil, lbls, mp.mtype)
+					sRef, _ := getSeriesRefWithoutScopeLabels(nil, lbls, mp.mtype)
 					err = mp.addSeries(sRef, tv.metric, lbls, tv.at, tv.value)
 				}
 				if tt.wantErr {
@@ -866,7 +866,7 @@ func TestMetricGroupData_toSummaryUnitTest(t *testing.T) {
 			for _, lbs := range tt.labelsScrapes {
 				for i, scrape := range lbs.scrapes {
 					lb := lbs.labels.Copy()
-					sRef, _ := getSeriesRef(nil, lb, mp.mtype)
+					sRef, _ := getSeriesRefWithoutScopeLabels(nil, lb, mp.mtype)
 					err := mp.addSeries(sRef, scrape.metric, lb, scrape.at, scrape.value)
 					if tt.wantErr {
 						// The first scrape won't have an error
@@ -1004,7 +1004,7 @@ func TestMetricGroupData_toNumberDataUnitTest(t *testing.T) {
 			mp := newMetricFamily(tt.metricKind, mc, zap.NewNop(), false, false)
 			for _, tv := range tt.scrapes {
 				lb := tt.labels.Copy()
-				sRef, _ := getSeriesRef(nil, lb, mp.mtype)
+				sRef, _ := getSeriesRefWithoutScopeLabels(nil, lb, mp.mtype)
 				require.NoError(t, mp.addSeries(sRef, tv.metric, lb, tv.at, tv.value))
 			}
 

receiver/prometheusreceiver/internal/metricfamily_test.go

@@ -8,6 +8,7 @@ import (
 	"errors"
 	"fmt"
 	"math"
+	"strings"
 
 	"github.com/prometheus/common/model"
 	"github.com/prometheus/prometheus/model/exemplar"
@@ -25,6 +26,7 @@ import (
 	"go.opentelemetry.io/collector/receiver/receiverhelper"
 	"go.uber.org/zap"
 
+	"github.com/open-telemetry/opentelemetry-collector-contrib/pkg/pdatautil"
 	"github.com/open-telemetry/opentelemetry-collector-contrib/pkg/translator/prometheus"
 	mdata "github.com/open-telemetry/opentelemetry-collector-contrib/receiver/prometheusreceiver/internal/metadata"
 )
@@ -56,6 +58,7 @@ type transaction struct {
 	externalLabels        labels.Labels
 	nodeResources         map[resourceKey]pcommon.Resource
 	scopeAttributes       map[resourceKey]map[scopeID]pcommon.Map
+	ignoreScopeInfoMetric bool
 	logger                *zap.Logger
 	buildInfo             component.BuildInfo
 	obsrecv               *receiverhelper.ObsReport
@@ -69,6 +72,7 @@ type scopeID struct {
 	name      string
 	version   string
 	schemaURL string
+	attrsHash [16]byte
 }
 
 func newTransaction(
@@ -81,19 +85,20 @@ func newTransaction(
 	useMetadata bool,
 ) *transaction {
 	return &transaction{
-		ctx:             ctx,
-		families:        make(map[resourceKey]map[scopeID]map[metricFamilyKey]*metricFamily),
-		isNew:           true,
-		trimSuffixes:    trimSuffixes,
-		useMetadata:     useMetadata,
-		sink:            sink,
-		externalLabels:  externalLabels,
-		logger:          settings.Logger,
-		buildInfo:       settings.BuildInfo,
-		obsrecv:         obsrecv,
-		bufBytes:        make([]byte, 0, 1024),
-		scopeAttributes: make(map[resourceKey]map[scopeID]pcommon.Map),
-		nodeResources:   map[resourceKey]pcommon.Resource{},
+		ctx:                   ctx,
+		families:              make(map[resourceKey]map[scopeID]map[metricFamilyKey]*metricFamily),
+		isNew:                 true,
+		trimSuffixes:          trimSuffixes,
+		useMetadata:           useMetadata,
+		sink:                  sink,
+		externalLabels:        externalLabels,
+		logger:                settings.Logger,
+		buildInfo:             settings.BuildInfo,
+		obsrecv:               obsrecv,
+		bufBytes:              make([]byte, 0, 1024),
+		scopeAttributes:       make(map[resourceKey]map[scopeID]pcommon.Map),
+		ignoreScopeInfoMetric: mdata.ReceiverPrometheusreceiverIgnoreScopeInfoMetricFeatureGate.IsEnabled(),
+		nodeResources:         map[resourceKey]pcommon.Resource{},
 	}
 }
 
@@ -157,12 +162,13 @@ func (t *transaction) Append(_ storage.SeriesRef, ls labels.Labels, atMs int64,
 	}
 
 	// For the `otel_scope_info` metric we need to convert it to scope attributes.
-	if metricName == prometheus.ScopeInfoMetricName {
+	if metricName == prometheus.ScopeInfoMetricName && !t.ignoreScopeInfoMetric {
 		t.addScopeInfo(*rKey, ls)
 		return 0, nil
 	}
 
-	scope := getScopeID(ls)
+	scope, attrs := getScopeID(ls)
+	t.addScopeAttributesFromLabels(*rKey, scope, attrs)
 
 	if value.IsStaleNaN(val) {
 		if t.detectAndStoreNativeHistogramStaleness(atMs, rKey, scope, metricName, ls) {
@@ -278,7 +284,9 @@ func (t *transaction) AppendExemplar(_ storage.SeriesRef, l labels.Labels, e exe
 		return 0, errMetricNameNotFound
 	}
 
-	mf := t.getOrCreateMetricFamily(*rKey, getScopeID(l), mn)
+	scope, attrs := getScopeID(l)
+	t.addScopeAttributesFromLabels(*rKey, scope, attrs)
+	mf := t.getOrCreateMetricFamily(*rKey, scope, mn)
 	mf.addExemplar(t.getSeriesRef(l, mf.mtype), e)
 
 	return 0, nil
@@ -329,7 +337,9 @@ func (t *transaction) AppendHistogram(_ storage.SeriesRef, ls labels.Labels, atM
 	// The `up`, `target_info`, `otel_scope_info` metrics should never generate native histograms,
 	// thus we don't check for them here as opposed to the Append function.
 
-	curMF := t.getOrCreateMetricFamily(*rKey, getScopeID(ls), metricName)
+	scope, attrs := getScopeID(ls)
+	t.addScopeAttributesFromLabels(*rKey, scope, attrs)
+	curMF := t.getOrCreateMetricFamily(*rKey, scope, metricName)
 	seriesRef := t.getSeriesRef(ls, curMF.mtype)
 	cacheRef := ls.Hash()
 
@@ -405,7 +415,9 @@ func (t *transaction) setStartTimestamp(ls labels.Labels, atMs, stMs int64) (sto
 		return 0, errMetricNameNotFound
 	}
 
-	curMF := t.getOrCreateMetricFamily(*rKey, getScopeID(ls), metricName)
+	scope, attrs := getScopeID(ls)
+	t.addScopeAttributesFromLabels(*rKey, scope, attrs)
+	curMF := t.getOrCreateMetricFamily(*rKey, scope, metricName)
 
 	seriesRef := t.getSeriesRef(ls, curMF.mtype)
 	curMF.addCreationTimestamp(seriesRef, ls, atMs, stMs)
@@ -418,8 +430,8 @@ func (*transaction) SetOptions(_ *storage.AppendOptions) {
 }
 
 func (t *transaction) getSeriesRef(ls labels.Labels, mtype pmetric.MetricType) uint64 {
-	var hash uint64
-	hash, t.bufBytes = getSeriesRef(t.bufBytes, ls, mtype)
+	hash, bufBytes := getSeriesRefWithoutScopeLabels(t.bufBytes, ls, mtype)
+	t.bufBytes = bufBytes
 	return hash
 }
 
@@ -457,8 +469,6 @@ func (t *transaction) getMetrics() (pmetric.Metrics, error) {
 				if scope.schemaURL != "" {
 					ils.SetSchemaUrl(scope.schemaURL)
 				}
-				// If we got an otel_scope_info metric for that scope, get scope
-				// attributes from it.
 				if scopeAttributes, ok := t.scopeAttributes[rKey]; ok {
 					if attributes, ok := scopeAttributes[scope]; ok {
 						attributes.CopyTo(ils.Scope().Attributes())
@@ -489,20 +499,44 @@ func (t *transaction) getMetrics() (pmetric.Metrics, error) {
 	return md, nil
 }
 
-func getScopeID(ls labels.Labels) scopeID {
+func getScopeID(ls labels.Labels) (scopeID, pcommon.Map) {
 	var scope scopeID
+	attrs := pcommon.NewMap()
 	ls.Range(func(lbl labels.Label) {
-		if lbl.Name == prometheus.ScopeNameLabelKey {
+		switch lbl.Name {
+		case prometheus.ScopeNameLabelKey:
 			scope.name = lbl.Value
-		}
-		if lbl.Name == prometheus.ScopeVersionLabelKey {
+			return
+		case prometheus.ScopeVersionLabelKey:
 			scope.version = lbl.Value
-		}
-		if lbl.Name == prometheus.ScopeSchemaURLLabelKey {
+			return
+		case prometheus.ScopeSchemaURLLabelKey:
 			scope.schemaURL = lbl.Value
+			return
+		}
+		if !strings.HasPrefix(lbl.Name, prometheus.ScopeLabelPrefix) {
+			return
 		}
+		attrKey := strings.TrimPrefix(lbl.Name, prometheus.ScopeLabelPrefix)
+		attrs.PutStr(attrKey, lbl.Value)
 	})
-	return scope
+	scope.attrsHash = pdatautil.MapHash(attrs)
+	return scope, attrs
+}
+
+func (t *transaction) addScopeAttributesFromLabels(key resourceKey, scope scopeID, attrs pcommon.Map) {
+	if attrs.Len() == 0 {
+		return
+	}
+	if _, ok := t.scopeAttributes[key]; !ok {
+		t.scopeAttributes[key] = make(map[scopeID]pcommon.Map)
+	}
+	if _, exists := t.scopeAttributes[key][scope]; exists {
+		return
+	}
+	copied := pcommon.NewMap()
+	attrs.CopyTo(copied)
+	t.scopeAttributes[key][scope] = copied
 }
 
 func (t *transaction) initTransaction(lbs labels.Labels) (*resourceKey, error) {
@@ -637,6 +671,6 @@ func (t *transaction) addScopeInfo(key resourceKey, ls labels.Labels) {
 	t.scopeAttributes[key][scope] = attrs
 }
 
-func getSeriesRef(bytes []byte, ls labels.Labels, mtype pmetric.MetricType) (uint64, []byte) {
-	return ls.HashWithoutLabels(bytes, getSortedNotUsefulLabels(mtype)...)
+func getSeriesRefWithoutScopeLabels(bytes []byte, ls labels.Labels, mtype pmetric.MetricType) (uint64, []byte) {
+	return ls.HashWithoutLabels(bytes, getSortedNotUsefulLabelsForSeries(mtype, ls)...)
 }

receiver/prometheusreceiver/internal/transaction.go

@@ -27,6 +27,8 @@ import (
 	"go.opentelemetry.io/collector/receiver/receivertest"
 	"go.uber.org/zap"
 	"go.uber.org/zap/zaptest/observer"
+
+	"github.com/open-telemetry/opentelemetry-collector-contrib/pkg/translator/prometheus"
 )
 
 const (
@@ -2044,7 +2046,7 @@ func TestGetOrCreateMetricFamily_DistinctFamiliesForNativeVsClassic(t *testing.T
 }
 
 func TestGetSeriesRef_IgnoresNotUsefulLabels(t *testing.T) {
-	// Build two label sets that differ only in labels likely excluded by getSortedNotUsefulLabels (e.g., _otel_* scope labels)
+	// Build two label sets that differ only in scope labels, which are excluded from series identity.
 	lsA := labels.FromStrings(
 		string(model.MetricNameLabel), "metric_x",
 		"env", "prod",
@@ -2058,12 +2060,25 @@ func TestGetSeriesRef_IgnoresNotUsefulLabels(t *testing.T) {
 	)
 
 	var buf []byte
-	hashA, buf := getSeriesRef(buf, lsA, pmetric.MetricTypeSum)
-	hashB, _ := getSeriesRef(buf, lsB, pmetric.MetricTypeSum)
+	hashA, buf := getSeriesRefWithoutScopeLabels(buf, lsA, pmetric.MetricTypeSum)
+	hashB, _ := getSeriesRefWithoutScopeLabels(buf, lsB, pmetric.MetricTypeSum)
 
 	require.Equal(t, hashA, hashB, "series ref should be equal when differing only by excluded labels")
 }
 
+func TestGetScopeID_EmptyScopeAttributesUseZeroHash(t *testing.T) {
+	scope, attrs := getScopeID(labels.FromStrings(
+		string(model.MetricNameLabel), "metric_x",
+		prometheus.ScopeNameLabelKey, "scope.with.info",
+		prometheus.ScopeVersionLabelKey, "v1.0.0",
+	))
+
+	require.Equal(t, "scope.with.info", scope.name)
+	require.Equal(t, "v1.0.0", scope.version)
+	require.Zero(t, scope.attrsHash)
+	require.Zero(t, attrs.Len())
+}
+
 func TestAddTargetInfo_DoesNotCopyJobInstanceOrMetricName(t *testing.T) {
 	tr := newTxn(t, false)
 	rk := resourceKey{job: "job-a", instance: "localhost:1234"}