feat: update EnvironmentGetter and EnvironmentSetter to use normalized environment variable names (open-telemetry#5119)

* feat: update EnvironmentGetter and EnvironmentSetter to use normalized environment variable names

* update CHANGELOG.md

---------

Co-authored-by: Mike Goldsmith <goldsmith.mike@gmail.com>
Co-authored-by: Riccardo Magliocchetti <riccardo.magliocchetti@gmail.com>

Author: 3 people

CHANGELOG.md

@@ -46,6 +46,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   ([#5135](https://github.com/open-telemetry/opentelemetry-python/pull/5135))
 - ci: wait for tracecontext server readiness instead of a fixed sleep in `scripts/tracecontext-integration-test.sh`
   ([#5149](https://github.com/open-telemetry/opentelemetry-python/pull/5149))
+- `opentelemetry-api`: update `EnvironmentGetter` and `EnvironmentSetter` to use normalized environment variable names
+  ([#5119](https://github.com/open-telemetry/opentelemetry-python/pull/5119))
 - `opentelemetry-sdk`: only load entrypoints for resource detectors if they are configured via `OTEL_EXPERIMENTAL_RESOURCE_DETECTORS`
   ([#5145](https://github.com/open-telemetry/opentelemetry-python/pull/5145))
 - `opentelemetry-exporter-otlp-json-common`: add 'opentelemetry-exporter-otlp-json-common' package for OTLP JSON exporters

opentelemetry-api/src/opentelemetry/propagators/_envcarrier.py

@@ -2,16 +2,24 @@
 # SPDX-License-Identifier: Apache-2.0
 
 import os
+import re
 import typing
 from collections.abc import MutableMapping
 
 from opentelemetry.propagators.textmap import Getter, Setter
 
 
+def _normalize_key(key: str) -> str:
+    result = re.sub(r"[^A-Za-z0-9_]", "_", key).upper()
+    if result and result[0].isdigit():
+        result = "_" + result
+    return result
+
+
 class EnvironmentGetter(Getter[typing.Mapping[str, str]]):
     """Getter implementation for extracting context and baggage from environment variables.
 
-    EnvironmentGetter creates a case-insensitive lookup from the current environment
+    EnvironmentGetter creates a normalized lookup from the current environment
     variables at initialization time and provides simple data access without validation.
 
     Per the OpenTelemetry specification, environment variables are treated as immutable
@@ -25,10 +33,10 @@ class EnvironmentGetter(Getter[typing.Mapping[str, str]]):
     """
 
     def __init__(self):
-        # Create case-insensitive lookup from current environment
+        # Create a normalized lookup from current environment
         # Per spec: "creates an in-memory copy of the current environment variables"
         self.carrier: dict[str, str] = {
-            k.lower(): v for k, v in os.environ.items()
+            _normalize_key(k): v for k, v in os.environ.items()
         }
 
     def get(
@@ -43,11 +51,9 @@ def get(
         Returns:
             A list with a single string value if the key exists, None otherwise.
         """
-        val = self.carrier.get(key.lower())
+        val = self.carrier.get(_normalize_key(key))
         if val is None:
             return None
-        if isinstance(val, typing.Iterable) and not isinstance(val, str):
-            return list(val)
         return [val]
 
     def keys(self, carrier: typing.Mapping[str, str]) -> list[str]:
@@ -57,7 +63,7 @@ def keys(self, carrier: typing.Mapping[str, str]) -> list[str]:
             carrier: Not used; maintained for interface compatibility with Getter[CarrierT]
 
         Returns:
-            List of all environment variable keys (lowercase).
+            List of all environment variable keys (normalized).
         """
         return list(self.carrier.keys())
 
@@ -85,4 +91,4 @@ def set(
             key: The key to set (will be converted to uppercase)
             value: The value to set
         """
-        carrier[key.upper()] = value
+        carrier[_normalize_key(key)] = value

opentelemetry-api/tests/propagators/test__envcarrier.py

@@ -14,12 +14,35 @@
 from opentelemetry.propagators._envcarrier import (
     EnvironmentGetter,
     EnvironmentSetter,
+    _normalize_key,
 )
 from opentelemetry.trace.propagation.tracecontext import (
     TraceContextTextMapPropagator,
 )
 
 
+class TestNormalizeKey(unittest.TestCase):
+    """Unit tests for _normalize_key."""
+
+    def test_lowercase(self):
+        self.assertEqual(_normalize_key("traceparent"), "TRACEPARENT")
+
+    def test_hyphen_replaced(self):
+        self.assertEqual(_normalize_key("trace-parent"), "TRACE_PARENT")
+
+    def test_non_ascii_replaced(self):
+        self.assertEqual(_normalize_key("héllo"), "H_LLO")
+
+    def test_leading_digit_prefixed(self):
+        self.assertEqual(_normalize_key("1abc"), "_1ABC")
+
+    def test_already_valid(self):
+        self.assertEqual(_normalize_key("ALREADY_VALID"), "ALREADY_VALID")
+
+    def test_empty_string(self):
+        self.assertEqual(_normalize_key(""), "")
+
+
 class TestEnvironmentGetter(unittest.TestCase):
     """Unit tests for EnvironmentGetter."""
 
@@ -67,7 +90,7 @@ def test_keys(self):
         with patch.dict(os.environ, test_env, clear=True):
             getter = EnvironmentGetter()
             keys = getter.keys({})
-            expected_keys = {"key1", "key2", "key3"}
+            expected_keys = {"KEY1", "KEY2", "KEY3"}
             self.assertEqual(set(keys), expected_keys)
 
     def test_keys_empty_environment(self):