feat(ddtrace/settings/_env): add new EnvConfig class to wrap std os.environ

Author: genesor

ddtrace/__init__.py

@@ -1,4 +1,3 @@
-import os
 import sys
 
 
@@ -14,14 +13,14 @@
 
 # Enable telemetry writer and excepthook as early as possible to ensure we capture any exceptions from initialization
 import ddtrace.internal.telemetry  # noqa: E402
-from .settings._config import config, _get_env
 from ddtrace.vendor import debtcollector
 
 from ._monkey import patch  # noqa: E402
 from ._monkey import patch_all  # noqa: E402
 from .internal.compat import PYTHON_VERSION_INFO  # noqa: E402
 from .internal.utils.deprecations import DDTraceDeprecationWarning  # noqa: E402
 from .settings._config import config
+from .settings._config import _get_env
 from .version import get_version  # noqa: E402
 
 

ddtrace/internal/telemetry/__init__.py

@@ -4,17 +4,19 @@
 ``DD_INSTRUMENTATION_TELEMETRY_ENABLED`` variable to ``False``.
 """
 
-import os
 import typing as t
 
 from ddtrace.internal.logger import get_logger
 from ddtrace.internal.telemetry.constants import TELEMETRY_NAMESPACE
 from ddtrace.internal.utils.formats import asbool
 from ddtrace.settings._agent import config as agent_config
+from ddtrace.settings._core import ENV_CONFIG
 from ddtrace.settings._core import FLEET_CONFIG
 from ddtrace.settings._core import FLEET_CONFIG_IDS
 from ddtrace.settings._core import LOCAL_CONFIG
 from ddtrace.settings._core import DDConfig
+from ddtrace.settings._env import environ as _environ
+from ddtrace.settings._env import get_env as _get_env
 from ddtrace.settings._otel_remapper import ENV_VAR_MAPPINGS
 from ddtrace.settings._otel_remapper import SUPPORTED_OTEL_ENV_VARS
 from ddtrace.settings._otel_remapper import parse_otel_env
@@ -25,13 +27,6 @@
 __all__ = ["telemetry_writer"]
 
 
-def get_env(env_name: str, default: t.Any = None) -> t.Any:
-    if env_name.startswith(("DD_", "OTEL_", "_DD")):
-        return get_config(env_name, default)
-
-    return os.environ.get(env_name, default)
-
-
 def get_config(
     envs: t.Union[str, t.List[str]],
     default: t.Any = None,
@@ -67,7 +62,7 @@ def get_config(
             effective_val = val
             break
 
-    if otel_env is not None and otel_env in os.environ:
+    if otel_env is not None and otel_env in ENV_CONFIG:
         raw_val, parsed_val = parse_otel_env(otel_env)
         if parsed_val is not None:
             val = parsed_val
@@ -82,14 +77,14 @@ def get_config(
             _invalid_otel_config(otel_env)
 
     for env in envs:
-        if env in os.environ:
-            val = os.environ[env]
+        if env in ENV_CONFIG:
+            val = ENV_CONFIG[env]
             if modifier:
                 val = modifier(val)
 
             if report_telemetry:
                 telemetry_writer.add_configuration(telemetry_name, val, "env_var")
-                if otel_env is not None and otel_env in os.environ:
+                if otel_env is not None and otel_env in ENV_CONFIG:
                     _hiding_otel_config(otel_env, env)
             effective_val = val
             break
@@ -103,7 +98,7 @@ def get_config(
 
             if report_telemetry:
                 telemetry_writer.add_configuration(telemetry_name, val, "fleet_stable_config", config_id)
-                if otel_env is not None and otel_env in os.environ:
+                if otel_env is not None and otel_env in ENV_CONFIG:
                     _hiding_otel_config(otel_env, env)
             effective_val = val
             break
@@ -139,7 +134,7 @@ def _invalid_otel_config(otel_env):
     log.warning(
         "Setting %s to %s is not supported by ddtrace, this configuration will be ignored.",
         otel_env,
-        os.environ.get(otel_env, ""),
+        _get_env(otel_env, ""),
     )
     telemetry_writer.add_count_metric(
         TELEMETRY_NAMESPACE.TRACERS,
@@ -160,7 +155,7 @@ def _unsupported_otel_config(otel_env):
 
 
 def validate_otel_envs():
-    user_envs = {key.upper(): value for key, value in os.environ.items()}
+    user_envs = {key.upper(): value for key, value in ENV_CONFIG.items()}
     for otel_env, _ in user_envs.items():
         if (
             otel_env not in ENV_VAR_MAPPINGS
@@ -170,7 +165,7 @@ def validate_otel_envs():
             _unsupported_otel_config(otel_env)
         elif otel_env == "OTEL_LOGS_EXPORTER":
             # check for invalid values
-            otel_value = os.environ.get(otel_env, "none").lower()
+            otel_value = _get_env(otel_env, "none").lower()
             if otel_value != "none":
                 _invalid_otel_config(otel_env)
             # TODO: Separate from validation
@@ -182,9 +177,8 @@ def validate_otel_envs():
 
 def validate_and_report_otel_metrics_exporter_enabled():
     metrics_exporter_enabled = True
-    user_envs = {key.upper(): value for key, value in os.environ.items()}
-    if "OTEL_METRICS_EXPORTER" in user_envs:
-        otel_value = os.environ.get("OTEL_METRICS_EXPORTER", "otlp").lower()
+    if "OTEL_METRICS_EXPORTER" in _environ:
+        otel_value = _get_env("OTEL_METRICS_EXPORTER", "otlp").lower()
         if otel_value == "none":
             metrics_exporter_enabled = False
         elif otel_value != "otlp":
@@ -201,7 +195,7 @@ def _hiding_otel_config(otel_env, dd_env):
         "Datadog configuration %s is already set. OpenTelemetry configuration will be ignored: %s=%s",
         dd_env,
         otel_env,
-        os.environ[otel_env],
+        ENV_CONFIG[otel_env],
     )
     telemetry_writer.add_count_metric(
         TELEMETRY_NAMESPACE.TRACERS,

ddtrace/settings/_config.py

@@ -35,9 +35,9 @@
 from ..internal.schema import DEFAULT_SPAN_SERVICE_NAME
 from ..internal.serverless import in_aws_lambda
 from ..internal.telemetry import get_config as _get_config
-from ..internal.telemetry import get_env as _get_env  # noqa:F401
 from ..internal.utils.formats import asbool
 from ..internal.utils.formats import parse_tags_str
+from ._env import get_env as _get_env  # noqa:F401
 from ._inferred_base_service import detect_service
 from .endpoint_config import fetch_config_from_endpoint
 from .http import HttpConfig

ddtrace/settings/_core.py

@@ -1,16 +1,17 @@
 from collections import ChainMap
 from enum import Enum
-import os
 from typing import Dict  # noqa:F401
 from typing import Optional  # noqa:F401
 from typing import Union  # noqa:F401
 
 from envier import Env
 
 from ddtrace.internal.native import get_configuration_from_disk
+from ddtrace.settings._env import environ
 
 
 FLEET_CONFIG, LOCAL_CONFIG, FLEET_CONFIG_IDS = get_configuration_from_disk()
+ENV_CONFIG = environ
 
 
 class ValueSource(str, Enum):
@@ -34,7 +35,7 @@ def __init__(
     ) -> None:
         self.fleet_source = FLEET_CONFIG
         self.local_source = LOCAL_CONFIG
-        self.env_source = os.environ
+        self.env_source = ENV_CONFIG
 
         # Order of precedence: provided source < local stable config < environment variables < fleet stable config
         full_source = ChainMap(self.fleet_source, self.env_source, self.local_source, source or {})

ddtrace/settings/_env.py

@@ -0,0 +1,104 @@
+from collections.abc import MutableMapping
+import os
+import typing as t
+
+
+class EnvConfig(MutableMapping):
+    """
+    Wrapper around os.environ that validates the variable against list of allowed variables.
+
+    It is used to get and set environment variables in a safe way mimicking the behavior of os.environ.
+    """
+
+    def __init__(self):
+        self._env = os.environ
+
+    def __getitem__(self, key):
+        """Handles: environ[key]"""
+        # TODO: Check will go here to validate the variable against list of allowed variables
+
+        return self._env[key]
+
+    def get(self, key, default=None):
+        """
+        Get an environment variable.
+        If the variable is a DD_ or OTEL_ or _DD prefixed variable, it will be validated against list
+        of allowed variables.
+
+        This is a wrapper around os.environ.get(key, default). as direct access to os.environ is not allowed.
+        """
+        # TODO: Check will go here to validate the variable against list of allowed variables
+
+        return self._env.get(key, default)
+
+    def __setitem__(self, key, value):
+        """Handles: environ[key] = value"""
+        self._env[key] = value
+
+    def __delitem__(self, key):
+        """Handles: del environ[key]"""
+        del self._env[key]
+
+    def __contains__(self, key):
+        """Handles: key in environ"""
+        # TODO: Check will go here to validate the variable against list of allowed variables
+
+        return key in self._env
+
+    def __iter__(self):
+        """Handles: for key in environ"""
+        # TODO: Check will go here to filter out unknown variables against list of allowed variables
+
+        return iter(self._env)
+
+    def __len__(self):
+        """Handles: len(environ)"""
+        return len(self._env)
+
+    def items(self):
+        """Handles: environ.items()"""
+        # TODO: Check will go here to filter out unknown variables against list of allowed variables
+
+        return self._env.items()
+
+    def keys(self):
+        """Handles: environ.keys()"""
+        # TODO: Check will go here to filter out unknown variables against list of allowed variables
+
+        return self._env.keys()
+
+    def values(self):
+        """
+        Get all the values of the environment variables.
+        If the variable is a DD_ or OTEL_ or _DD prefixed variable, it will be validated against list of allowed
+        variables.
+
+        This is a wrapper around os.environ.values(). as direct access to os.environ is not allowed.
+        """
+        # TODO: Check will go here to filter out unknown variables against list of allowed variables
+
+        return self._env.values()
+
+
+environ = EnvConfig()
+"""
+Equivalent to os.environ using the EnvConfig wrapper-class.
+"""
+
+
+def get_env(env_name: str, default: t.Any = None) -> t.Any:
+    """
+    Get an environment variable.
+    If the variable is a DD_ or OTEL_ or _DD prefixed variable, it will be validated against list of allowed variables.
+
+    This is a wrapper around os.environ.get(env_name, default). as direct access to os.environ is not allowed.
+    """
+    return environ.get(env_name, default)
+
+
+def set_env(env_name: str, value: t.Any) -> None:
+    """
+    Set an environment variable.
+    This is a wrapper around os.environ[env_name] = value. as direct access to os.environ is not allowed.
+    """
+    os.environ[env_name] = value

ddtrace/settings/_otel_remapper.py

@@ -1,4 +1,3 @@
-import os
 from typing import Callable
 from typing import Dict
 from typing import List
@@ -8,6 +7,7 @@
 from ..constants import ENV_KEY
 from ..constants import VERSION_KEY
 from ..internal.logger import get_logger
+from ._env import get_env as _get_env
 
 
 log = get_logger(__name__)
@@ -55,7 +55,7 @@ def _remap_traces_sampler(otel_value: str) -> Optional[str]:
     elif otel_value == "parentbased_always_off":
         rate = "0.0"
     elif otel_value == "parentbased_traceidratio":
-        rate = os.environ.get("OTEL_TRACES_SAMPLER_ARG", "1")
+        rate = _get_env("OTEL_TRACES_SAMPLER_ARG", "1")
 
     if rate is not None:
         return f'[{{"sample_rate":{rate}}}]'
@@ -165,7 +165,7 @@ def _remap_default(otel_value: str) -> Optional[str]:
 
 def parse_otel_env(otel_env: str) -> Tuple[str, Optional[str]]:
     _, otel_config_validator = ENV_VAR_MAPPINGS[otel_env]
-    raw_value = os.environ.get(otel_env, "")
+    raw_value = _get_env(otel_env, "")
     if otel_env not in ("OTEL_RESOURCE_ATTRIBUTES", "OTEL_SERVICE_NAME"):
         # Resource attributes and service name are case-insensitive
         raw_value = raw_value.lower()