pkg/ottl: add metric.metadata as a valid path in OTTL (#40217)

<!--Ex. Fixing a bug - Describe the bug and how this fixes the issue.
Ex. Adding a feature - Explain what this achieves.-->
#### Description
Allow OTTL to get and set metric metadata.

<!-- Issue number (e.g. #1234) or full URL to issue, if applicable. -->
#### Link to tracking issue
Fixes #40214.

<!--Describe what testing was performed and which tests were added.-->
#### Testing
Added unit tests

<!--Describe the documentation added.-->
#### Documentation
Updated readme

Example statement that now works:
- set(metric.metadata["k"], "v") where
metric.metadata["prometheus.type"] == "unknown"

<!--Please delete paragraphs that you did not use before submitting.-->

---------

Signed-off-by: Ridwan Sharif <[email protected]>
Co-authored-by: Evan Bradley <[email protected]>

Author: ridwanmsharif

.chloggen/ottl-metadata.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: pkg/ottl
+
+# A brief description of the change.  Surround your text with quotes ("") if it needs to start with a backtick (`).
+note: Add metric.metadata as a valid OTTL path
+
+# Mandatory: One or more tracking issues related to the change. You can use the PR number here if no issue exists.
+issues: [40214]
+
+# (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: []

pkg/ottl/contexts/internal/ctxmetric/metric.go

@@ -10,6 +10,7 @@ import (
 
 	"github.com/open-telemetry/opentelemetry-collector-contrib/pkg/ottl"
 	"github.com/open-telemetry/opentelemetry-collector-contrib/pkg/ottl/contexts/internal/ctxerror"
+	"github.com/open-telemetry/opentelemetry-collector-contrib/pkg/ottl/contexts/internal/ctxutil"
 )
 
 func PathGetSetter[K Context](path ottl.Path[K]) (ottl.GetSetter[K], error) {
@@ -31,6 +32,11 @@ func PathGetSetter[K Context](path ottl.Path[K]) (ottl.GetSetter[K], error) {
 		return accessIsMonotonic[K](), nil
 	case "data_points":
 		return accessDataPoints[K](), nil
+	case "metadata":
+		if path.Keys() == nil {
+			return accessMetadata[K](), nil
+		}
+		return accessMetadataKey[K](path.Keys()), nil
 	default:
 		return nil, ctxerror.New(path.Name(), path.String(), Name, DocRef)
 	}
@@ -189,3 +195,25 @@ func accessDataPoints[K Context]() ottl.StandardGetSetter[K] {
 		},
 	}
 }
+
+func accessMetadata[K Context]() ottl.StandardGetSetter[K] {
+	return ottl.StandardGetSetter[K]{
+		Getter: func(_ context.Context, tCtx K) (any, error) {
+			return tCtx.GetMetric().Metadata(), nil
+		},
+		Setter: func(_ context.Context, tCtx K, val any) error {
+			return ctxutil.SetMap(tCtx.GetMetric().Metadata(), val)
+		},
+	}
+}
+
+func accessMetadataKey[K Context](keys []ottl.Key[K]) ottl.StandardGetSetter[K] {
+	return ottl.StandardGetSetter[K]{
+		Getter: func(ctx context.Context, tCtx K) (any, error) {
+			return ctxutil.GetMapValue(ctx, tCtx, tCtx.GetMetric().Metadata(), keys)
+		},
+		Setter: func(ctx context.Context, tCtx K, val any) error {
+			return ctxutil.SetMapValue(ctx, tCtx, tCtx.GetMetric().Metadata(), keys, val)
+		},
+	}
+}

pkg/ottl/contexts/internal/ctxmetric/metric_test.go

@@ -8,6 +8,7 @@ import (
 	"testing"
 
 	"github.com/stretchr/testify/assert"
+	"go.opentelemetry.io/collector/pdata/pcommon"
 	"go.opentelemetry.io/collector/pdata/pmetric"
 
 	"github.com/open-telemetry/opentelemetry-collector-contrib/pkg/ottl"
@@ -21,6 +22,9 @@ func TestPathGetSetter(t *testing.T) {
 	newMetric := pmetric.NewMetric()
 	newMetric.SetName("new name")
 
+	newMetadata := pcommon.NewMap()
+	newMetadata.PutStr("new_k", "new_v")
+
 	newDataPoints := pmetric.NewNumberDataPointSlice()
 	dataPoint := newDataPoints.AppendEmpty()
 	dataPoint.SetIntValue(1)
@@ -108,6 +112,17 @@ func TestPathGetSetter(t *testing.T) {
 				newDataPoints.CopyTo(metric.Sum().DataPoints())
 			},
 		},
+		{
+			name: "metric metadata",
+			path: &pathtest.Path[*testContext]{
+				N: "metadata",
+			},
+			orig:   pcommon.NewMap(),
+			newVal: newMetadata,
+			modified: func(metric pmetric.Metric) {
+				newMetadata.CopyTo(metric.Metadata())
+			},
+		},
 	}
 	for _, tt := range tests {
 		t.Run(tt.name, func(t *testing.T) {

pkg/ottl/contexts/internal/logging/logging.go

@@ -168,8 +168,8 @@ func (m Metric) MarshalLogObject(encoder zapcore.ObjectEncoder) error {
 	encoder.AddString("name", mm.Name())
 	encoder.AddString("unit", mm.Unit())
 	encoder.AddString("type", mm.Type().String())
+	err := encoder.AddObject("metadata", Map(mm.Metadata()))
 
-	var err error
 	switch mm.Type() {
 	case pmetric.MetricTypeSum:
 		encoder.AddString("aggregation_temporality", mm.Sum().AggregationTemporality().String())

pkg/ottl/contexts/ottlmetric/README.md

@@ -26,6 +26,7 @@ The following paths are supported.
 | metric.description                     | the description of the metric                                                                                                                      | string                                                                                                                                      |
 | metric.unit                            | the unit of the metric                                                                                                                             | string                                                                                                                                      |
 | metric.type                            | the data type of the metric                                                                                                                        | int64                                                                                                                                       |
+| metric.metadata                        | metadata associated with the metric                                                                                                                | pcommon.Map                                                                                                                                       |
 | metric.aggregation_temporality         | the aggregation temporality of the metric                                                                                                          | int64                                                                                                                                       |
 | metric.is_monotonic                    | the monotonicity of the metric                                                                                                                     | bool                                                                                                                                        |
 | metric.data_points                     | the data points of the metric                                                                                                                      | pmetric.NumberDataPointSlice, pmetric.HistogramDataPointSlice, pmetric.ExponentialHistogramDataPointSlice, or pmetric.SummaryDataPointSlice | 

pkg/ottl/contexts/ottlmetric/metrics_test.go

@@ -25,6 +25,9 @@ func Test_newPathGetSetter(t *testing.T) {
 	newCache := pcommon.NewMap()
 	newCache.PutStr("temp", "value")
 
+	newMetadata := pcommon.NewMap()
+	newMetadata.PutStr("new_k", "new_v")
+
 	newMetric := pmetric.NewMetric()
 	newMetric.SetName("new name")
 
@@ -115,6 +118,33 @@ func Test_newPathGetSetter(t *testing.T) {
 				newDataPoints.CopyTo(metric.Sum().DataPoints())
 			},
 		},
+		{
+			name: "metadata",
+			path: &pathtest.Path[TransformContext]{
+				N: "metadata",
+			},
+			orig:   pcommon.NewMap(),
+			newVal: newMetadata,
+			modified: func(metric pmetric.Metric, _ pcommon.Map) {
+				newMetadata.CopyTo(metric.Metadata())
+			},
+		},
+		{
+			name: "metadata access",
+			path: &pathtest.Path[TransformContext]{
+				N: "metadata",
+				KeySlice: []ottl.Key[TransformContext]{
+					&pathtest.Key[TransformContext]{
+						S: ottltest.Strp("temp"),
+					},
+				},
+			},
+			orig:   nil,
+			newVal: "new value",
+			modified: func(metric pmetric.Metric, _ pcommon.Map) {
+				metric.Metadata().PutStr("temp", "new value")
+			},
+		},
 		{
 			name: "cache",
 			path: &pathtest.Path[TransformContext]{