chore: generate feature flag files from shared (#7361)

Given the observed facts, multiple components need to depend on the x
package together. To reduce duplication and unify style management, this
PR is added.

PS: Currently only
`go.opentelemetry.io/otel/exporters/stdout/stdouttrace` is supported;
other components will be supplemented after this PR is merged.

---------

Co-authored-by: Damien Mathieu <[email protected]>

Author: flc1125

exporters/stdout/stdouttrace/internal/gen.go

@@ -7,3 +7,6 @@ package internal // import "go.opentelemetry.io/otel/exporters/stdout/stdouttrac
 
 //go:generate gotmpl --body=../../../../internal/shared/counter/counter.go.tmpl "--data={ \"pkg\": \"go.opentelemetry.io/otel/exporters/stdout/stdouttrace/internal/counter\" }" --out=counter/counter.go
 //go:generate gotmpl --body=../../../../internal/shared/counter/counter_test.go.tmpl "--data={}" --out=counter/counter_test.go
+
+//go:generate gotmpl --body=../../../../internal/shared/x/x.go.tmpl "--data={ \"pkg\": \"go.opentelemetry.io/otel/exporters/stdout/stdouttrace\" }" --out=x/x.go
+//go:generate gotmpl --body=../../../../internal/shared/x/x_test.go.tmpl "--data={}" --out=x/x_test.go

exporters/stdout/stdouttrace/internal/x/features.go

@@ -0,0 +1,23 @@
+// Copyright The OpenTelemetry Authors
+// SPDX-License-Identifier: Apache-2.0
+
+// Package x documents experimental features for [go.opentelemetry.io/otel/exporters/stdout/stdouttrace].
+package x // import "go.opentelemetry.io/otel/exporters/stdout/stdouttrace/internal/x"
+
+import "strings"
+
+// Observability is an experimental feature flag that determines if exporter
+// observability metrics are enabled.
+//
+// To enable this feature set the OTEL_GO_X_OBSERVABILITY environment variable
+// to the case-insensitive string value of "true" (i.e. "True" and "TRUE"
+// will also enable this).
+var Observability = newFeature(
+	[]string{"OBSERVABILITY", "SELF_OBSERVABILITY"},
+	func(v string) (string, bool) {
+		if strings.EqualFold(v, "true") {
+			return v, true
+		}
+		return "", false
+	},
+)

exporters/stdout/stdouttrace/internal/x/features_test.go

@@ -0,0 +1,24 @@
+// Copyright The OpenTelemetry Authors
+// SPDX-License-Identifier: Apache-2.0
+
+package x
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/require"
+)
+
+func TestObservability(t *testing.T) {
+	const key = "OTEL_GO_X_OBSERVABILITY"
+	require.Contains(t, Observability.Keys(), key)
+
+	const altKey = "OTEL_GO_X_SELF_OBSERVABILITY"
+	require.Contains(t, Observability.Keys(), altKey)
+
+	t.Run("100", run(setenv(key, "100"), assertDisabled(Observability)))
+	t.Run("true", run(setenv(key, "true"), assertEnabled(Observability, "true")))
+	t.Run("True", run(setenv(key, "True"), assertEnabled(Observability, "True")))
+	t.Run("false", run(setenv(key, "false"), assertDisabled(Observability)))
+	t.Run("empty", run(assertDisabled(Observability)))
+}

exporters/stdout/stdouttrace/internal/x/x.go

@@ -0,0 +1,58 @@
+// Code generated by gotmpl. DO NOT MODIFY.
+// source: internal/shared/x/x.go.tmpl
+
+// Copyright The OpenTelemetry Authors
+// SPDX-License-Identifier: Apache-2.0
+
+// Package x documents experimental features for [{{.pkg}}].
+package x // import "{{.pkg}}/internal/x"
+
+import (
+	"os"
+)
+
+// Feature is an experimental feature control flag. It provides a uniform way
+// to interact with these feature flags and parse their values.
+type Feature[T any] struct {
+	keys  []string
+	parse func(v string) (T, bool)
+}
+
+func newFeature[T any](suffix []string, parse func(string) (T, bool)) Feature[T] {
+	const envKeyRoot = "OTEL_GO_X_"
+	keys := make([]string, 0, len(suffix))
+	for _, s := range suffix {
+		keys = append(keys, envKeyRoot+s)
+	}
+	return Feature[T]{
+		keys:  keys,
+		parse: parse,
+	}
+}
+
+// Keys returns the environment variable keys that can be set to enable the
+// feature.
+func (f Feature[T]) Keys() []string { return f.keys }
+
+// Lookup returns the user configured value for the feature and true if the
+// user has enabled the feature. Otherwise, if the feature is not enabled, a
+// zero-value and false are returned.
+func (f Feature[T]) Lookup() (v T, ok bool) {
+	// https://github.com/open-telemetry/opentelemetry-specification/blob/62effed618589a0bec416a87e559c0a9d96289bb/specification/configuration/sdk-environment-variables.md#parsing-empty-value
+	//
+	// > The SDK MUST interpret an empty value of an environment variable the
+	// > same way as when the variable is unset.
+	for _, key := range f.keys {
+		vRaw := os.Getenv(key)
+		if vRaw != "" {
+			return f.parse(vRaw)
+		}
+	}
+	return v, ok
+}
+
+// Enabled reports whether the feature is enabled.
+func (f Feature[T]) Enabled() bool {
+	_, ok := f.Lookup()
+	return ok
+}

exporters/stdout/stdouttrace/internal/x/x_test.go

@@ -0,0 +1,75 @@
+// Code generated by gotmpl. DO NOT MODIFY.
+// source: internal/shared/x/x_text.go.tmpl
+
+// Copyright The OpenTelemetry Authors
+// SPDX-License-Identifier: Apache-2.0
+
+package x
+
+import (
+	"strings"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+const (
+	mockKey  = "OTEL_GO_X_MOCK_FEATURE"
+	mockKey2 = "OTEL_GO_X_MOCK_FEATURE2"
+)
+
+var mockFeature = newFeature([]string{"MOCK_FEATURE", "MOCK_FEATURE2"}, func(v string) (string, bool) {
+	if strings.EqualFold(v, "true") {
+		return v, true
+	}
+	return "", false
+})
+
+func TestFeature(t *testing.T) {
+	require.Contains(t, mockFeature.Keys(), mockKey)
+	require.Contains(t, mockFeature.Keys(), mockKey2)
+
+	t.Run("100", run(setenv(mockKey, "100"), assertDisabled(mockFeature)))
+	t.Run("true", run(setenv(mockKey, "true"), assertEnabled(mockFeature, "true")))
+	t.Run("True", run(setenv(mockKey, "True"), assertEnabled(mockFeature, "True")))
+	t.Run("false", run(setenv(mockKey, "false"), assertDisabled(mockFeature)))
+	t.Run("empty", run(assertDisabled(mockFeature)))
+}
+
+func run(steps ...func(*testing.T)) func(*testing.T) {
+	return func(t *testing.T) {
+		t.Helper()
+		for _, step := range steps {
+			step(t)
+		}
+	}
+}
+
+func setenv(k, v string) func(t *testing.T) { //nolint:unparam // This is a reusable test utility function.
+	return func(t *testing.T) { t.Setenv(k, v) }
+}
+
+func assertEnabled[T any](f Feature[T], want T) func(*testing.T) {
+	return func(t *testing.T) {
+		t.Helper()
+		assert.True(t, f.Enabled(), "not enabled")
+
+		v, ok := f.Lookup()
+		assert.True(t, ok, "Lookup state")
+		assert.Equal(t, want, v, "Lookup value")
+	}
+}
+
+func assertDisabled[T any](f Feature[T]) func(*testing.T) {
+	var zero T
+	return func(t *testing.T) {
+		t.Helper()
+
+		assert.False(t, f.Enabled(), "enabled")
+
+		v, ok := f.Lookup()
+		assert.False(t, ok, "Lookup state")
+		assert.Equal(t, zero, v, "Lookup value")
+	}
+}