[reciever/prometheusremotewritereceiver] add help ref

.chloggen/metric-help-ref.yaml

@@ -0,0 +1,27 @@
+# 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. filelogreceiver)
+component: prometheusremotewritereciever
+
+# A brief description of the change.  Surround your text with quotes ("") if it needs to start with a backtick (`).
+note: 'Add help ref attribute to metric'
+
+# Mandatory: One or more tracking issues related to the change. You can use the PR number here if no issue exists.
+issues: [37277]
+
+# (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:
+
+# 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: [user]

receiver/prometheusremotewritereceiver/receiver.go

@@ -207,12 +207,18 @@ func (prw *prometheusRemoteWriteReceiver) translateV2(_ context.Context, req *wr
 
 		scopeName, scopeVersion := prw.extractScopeInfo(ls)
 		metricName := ls.Get(labels.MetricName)
-		// TODO: Like UnitRef, we should assign the HelpRef to the metric.
 		if ts.Metadata.UnitRef >= uint32(len(req.Symbols)) {
 			badRequestErrors = errors.Join(badRequestErrors, fmt.Errorf("unit ref %d is out of bounds of symbolsTable", ts.Metadata.UnitRef))
 			continue
 		}
+
+		if ts.Metadata.HelpRef >= uint32(len(req.Symbols)) {
+			badRequestErrors = errors.Join(badRequestErrors, fmt.Errorf("help ref %d is out of bounds of symbolsTable", ts.Metadata.HelpRef))
+			continue
+		}
+
 		unit := req.Symbols[ts.Metadata.UnitRef]
+		description := req.Symbols[ts.Metadata.HelpRef]
 
 		resourceID := identity.OfResource(rm.Resource())
 		// Temporary approach to generate the metric key.
@@ -248,6 +254,7 @@ func (prw *prometheusRemoteWriteReceiver) translateV2(_ context.Context, req *wr
 			metric = scope.Metrics().AppendEmpty()
 			metric.SetName(metricName)
 			metric.SetUnit(unit)
+			metric.SetDescription(description)
 
 			switch ts.Metadata.Type {
 			case writev2.Metadata_METRIC_TYPE_GAUGE:
@@ -265,6 +272,12 @@ func (prw *prometheusRemoteWriteReceiver) translateV2(_ context.Context, req *wr
 			metricCache[metricKey] = metric
 		}
 
+		// When the new description is longer than the existing one, we should update the metric description.
+		// Reference to this behavior: https://opentelemetry.io/docs/specs/otel/metrics/data-model/#opentelemetry-protocol-data-model-producer-recommendations
+		if len(metric.Description()) < len(description) {
+			metric.SetDescription(description)
+		}
+
 		// Otherwise, we append the samples to the existing metric.
 		switch ts.Metadata.Type {
 		case writev2.Metadata_METRIC_TYPE_GAUGE:

receiver/prometheusremotewritereceiver/receiver_test.go

@@ -191,6 +191,7 @@ func TestTranslateV2(t *testing.T) {
 				metrics1 := sm1.Metrics().AppendEmpty()
 				metrics1.SetName("test_metric1")
 				metrics1.SetUnit("")
+				metrics1.SetDescription("")
 
 				dp1 := metrics1.SetEmptyGauge().DataPoints().AppendEmpty()
 				dp1.SetTimestamp(pcommon.Timestamp(1 * int64(time.Millisecond)))
@@ -215,6 +216,7 @@ func TestTranslateV2(t *testing.T) {
 				metrics2 := sm2.Metrics().AppendEmpty()
 				metrics2.SetName("test_metric1")
 				metrics2.SetUnit("")
+				metrics2.SetDescription("")
 
 				dp3 := metrics2.SetEmptyGauge().DataPoints().AppendEmpty()
 				dp3.SetTimestamp(pcommon.Timestamp(2 * int64(time.Millisecond)))
@@ -273,6 +275,7 @@ func TestTranslateV2(t *testing.T) {
 				metrics1 := sm1.Metrics().AppendEmpty()
 				metrics1.SetName("test_metric")
 				metrics1.SetUnit("")
+				metrics1.SetDescription("")
 
 				dp1 := metrics1.SetEmptyGauge().DataPoints().AppendEmpty()
 				dp1.SetTimestamp(pcommon.Timestamp(1 * int64(time.Millisecond)))
@@ -290,6 +293,7 @@ func TestTranslateV2(t *testing.T) {
 				metrics2 := sm2.Metrics().AppendEmpty()
 				metrics2.SetName("test_metric")
 				metrics2.SetUnit("")
+				metrics1.SetDescription("")
 
 				dp3 := metrics2.SetEmptyGauge().DataPoints().AppendEmpty()
 				dp3.SetTimestamp(pcommon.Timestamp(3 * int64(time.Millisecond)))
@@ -314,21 +318,27 @@ func TestTranslateV2(t *testing.T) {
 					"foo", "bar", // 13, 14
 					"f", "g", // 15, 16
 					"seconds", "milliseconds", // 17, 18
+					"small desc", "longer description", // 19, 20
 				},
 				Timeseries: []writev2.TimeSeries{
+					// The only difference between ts 0 and 1 is the value assigned in the HelpRef. According to the spec
+					// Ref: https://opentelemetry.io/docs/specs/otel/metrics/data-model/#opentelemetry-protocol-data-model,
+					// the HelpRef(description) field is not considered an identifying property.
+					// This means that if you have two metrics with the same name, unit, scope, and resource attributes but different description values, they are still considered to be the same
+					// But, between them, the longer description should be used.
 					{
-						Metadata:   writev2.Metadata{Type: writev2.Metadata_METRIC_TYPE_GAUGE, UnitRef: 17},
+						Metadata:   writev2.Metadata{Type: writev2.Metadata_METRIC_TYPE_GAUGE, UnitRef: 17, HelpRef: 19},
 						LabelsRefs: []uint32{1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12},
 						Samples:    []writev2.Sample{{Value: 1, Timestamp: 1}},
 					},
 					{
-						Metadata:   writev2.Metadata{Type: writev2.Metadata_METRIC_TYPE_GAUGE, UnitRef: 17},
+						Metadata:   writev2.Metadata{Type: writev2.Metadata_METRIC_TYPE_GAUGE, UnitRef: 17, HelpRef: 20},
 						LabelsRefs: []uint32{1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12},
 						Samples:    []writev2.Sample{{Value: 2, Timestamp: 2}},
 					},
 					{
 						// Unit changed, so it should be a different metric.
-						Metadata:   writev2.Metadata{Type: writev2.Metadata_METRIC_TYPE_GAUGE, UnitRef: 18},
+						Metadata:   writev2.Metadata{Type: writev2.Metadata_METRIC_TYPE_GAUGE, UnitRef: 18, HelpRef: 19},
 						LabelsRefs: []uint32{1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 13, 14},
 						Samples:    []writev2.Sample{{Value: 3, Timestamp: 3}},
 					},
@@ -352,6 +362,8 @@ func TestTranslateV2(t *testing.T) {
 				metrics1 := sm1.Metrics().AppendEmpty()
 				metrics1.SetName("test_metric")
 				metrics1.SetUnit("seconds")
+				metrics1.SetDescription("longer description")
+
 				dp1 := metrics1.SetEmptyGauge().DataPoints().AppendEmpty()
 				dp1.SetTimestamp(pcommon.Timestamp(1 * int64(time.Millisecond)))
 				dp1.SetDoubleValue(1.0)
@@ -365,6 +377,8 @@ func TestTranslateV2(t *testing.T) {
 				metrics2 := sm1.Metrics().AppendEmpty()
 				metrics2.SetName("test_metric")
 				metrics2.SetUnit("milliseconds")
+				metrics2.SetDescription("small desc")
+
 				dp3 := metrics2.SetEmptyGauge().DataPoints().AppendEmpty()
 				dp3.SetTimestamp(pcommon.Timestamp(3 * int64(time.Millisecond)))
 				dp3.SetDoubleValue(3.0)