Add new experimental toStringMapRaw method to xconfmap (open-telemetry#14480)

<!--Ex. Fixing a bug - Describe the bug and how this fixes the issue.
Ex. Adding a feature - Explain what this achieves.-->
#### Description
This experimental method allows for stringmap manipulations without
destroying internal types like `ExpandedValue`.
Destroying these internal values could lead to unrecoverable errors like
having an env var fully numeric but expected as string. Using
`ToStringMap` would permanently flatten the `ExpandedValue` into its
`Value` type regardless of intent.
<!--Describe what testing was performed and which tests were added.-->
#### Testing

Added tests.

---------

Co-authored-by: Pablo Baeyens <pbaeyens31+github@gmail.com>

Author: theomagellan

.chloggen/add-tostringmapraw-xconfmap.yaml

@@ -0,0 +1,26 @@
+# 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/otlp)
+component: pkg/confmap
+
+# A brief description of the change.  Surround your text with quotes ("") if it needs to start with a backtick (`).
+note: Add experimental `ToStringMapRaw` function to decode `confmap.Conf` into a string map without losing internal types
+
+# One or more tracking issues or pull requests related to the change
+issues: [14480]
+
+# (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: |
+   This method exposes the internal structure of a `confmap.Conf` which may change at any time without prior notice
+
+# 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: []

confmap/internal/conf.go

@@ -182,6 +182,10 @@ func (l *Conf) ToStringMap() map[string]any {
 	return sanitize(l.toStringMapWithExpand()).(map[string]any)
 }
 
+func ToStringMapRaw(conf *Conf) map[string]any {
+	return conf.toStringMapWithExpand()
+}
+
 func (l *Conf) unsanitizedGet(key string) any {
 	return l.k.Get(key)
 }

confmap/internal/e2e/expand_test.go

@@ -12,8 +12,10 @@ import (
 	"github.com/stretchr/testify/require"
 
 	"go.opentelemetry.io/collector/confmap"
+	"go.opentelemetry.io/collector/confmap/internal"
 	"go.opentelemetry.io/collector/confmap/provider/envprovider"
 	"go.opentelemetry.io/collector/confmap/provider/fileprovider"
+	"go.opentelemetry.io/collector/confmap/xconfmap"
 )
 
 func Test_EscapedEnvVars_NoDefaultScheme(t *testing.T) {
@@ -111,3 +113,17 @@ func Test_EscapedEnvVars_DefaultScheme(t *testing.T) {
 	m := cfgMap.ToStringMap()
 	assert.Equal(t, expectedMap, m)
 }
+
+func Test_RawConfMap(t *testing.T) {
+	data := map[string]any{
+		"value": internal.ExpandedValue{
+			Value:    8080,
+			Original: "8080",
+		},
+	}
+	conf := confmap.NewFromStringMap(data)
+
+	rawData := xconfmap.ToStringMapRaw(conf)
+	_, isPresentAndExpandedValue := rawData["value"].(internal.ExpandedValue)
+	require.True(t, isPresentAndExpandedValue)
+}

confmap/internal/e2e/go.mod

@@ -8,6 +8,7 @@ require (
 	go.opentelemetry.io/collector/confmap v1.51.0
 	go.opentelemetry.io/collector/confmap/provider/envprovider v1.51.0
 	go.opentelemetry.io/collector/confmap/provider/fileprovider v1.51.0
+	go.opentelemetry.io/collector/confmap/xconfmap v0.145.0
 	go.opentelemetry.io/collector/featuregate v1.51.0
 )
 
@@ -22,7 +23,6 @@ require (
 	github.com/mitchellh/copystructure v1.2.0 // indirect
 	github.com/mitchellh/reflectwalk v1.0.2 // indirect
 	github.com/pmezard/go-difflib v1.0.0 // indirect
-	go.opentelemetry.io/collector/confmap/xconfmap v0.145.0 // indirect
 	go.uber.org/multierr v1.11.0 // indirect
 	go.uber.org/zap v1.27.1 // indirect
 	go.yaml.in/yaml/v3 v3.0.4 // indirect

confmap/xconfmap/confmap.go

@@ -0,0 +1,27 @@
+// Copyright The OpenTelemetry Authors
+// SPDX-License-Identifier: Apache-2.0
+
+package xconfmap // import "go.opentelemetry.io/collector/confmap/xconfmap"
+
+import (
+	"go.opentelemetry.io/collector/confmap"
+	"go.opentelemetry.io/collector/confmap/internal"
+)
+
+// ExpandedValue represents a configuration value that has been expanded from a template
+// (e.g., environment variable substitution). It contains both the parsed value and the
+// original string representation.
+//
+// This type is exposed to allow working with configuration values returned by ToStringMapRaw.
+type ExpandedValue = internal.ExpandedValue
+
+// ToStringMapRaw returns the raw configuration map without sanitization.
+// This is an experimental API and may change or be removed in future versions.
+// The returned map may change at any time without prior notice.
+//
+// Unlike confmap.Conf.ToStringMap(), this function does not sanitize the map
+// by removing expandedValue references. This allows for configmap manipulation
+// without destroying internal types.
+func ToStringMapRaw(conf *confmap.Conf) map[string]any {
+	return internal.ToStringMapRaw(conf)
+}