disable django instrumentation if DJANGO_SETTINGS_MODULE is not set (#549)

*Issue #, if available:*

When using the OpenTelemetry Django instrumentation, users must set the
DJANGO_SETTINGS_MODULE environment variable before Python starts.
Otherwise, Django will fail to launch because it cannot locate the
required settings module.

*Description of changes:*
In the ADOT distribution, we can add logic so that if Django is
installed, the Django instrumentation is enabled only when the
DJANGO_SETTINGS_MODULE environment variable is present.

By submitting this pull request, I confirm that you can use, modify,
copy, and redistribute this contribution, under the terms of your
choice.

Author: wangzlei

CHANGELOG.md

@@ -11,6 +11,8 @@ For any change that affects end users of this package, please add an entry under
 If your change does not need a CHANGELOG entry, add the "skip changelog" label to your PR.
 
 ## Unreleased
+- Disable django instrumentation if DJANGO_SETTINGS_MODULE is not set
+  ([#549](https://github.com/aws-observability/aws-otel-python-instrumentation/pull/549))
 - [PATCH] Add safety check for bedrock ConverseStream responses
   ([#547](https://github.com/aws-observability/aws-otel-python-instrumentation/pull/547))
 - Add Service and Environment dimensions to EMF metrics when Application Signals EMF export is enabled

aws-opentelemetry-distro/src/amazon/opentelemetry/distro/aws_opentelemetry_distro.py

@@ -16,7 +16,7 @@
 import sys
 from logging import ERROR, Logger, getLogger
 
-from amazon.opentelemetry.distro._utils import get_aws_region, is_agent_observability_enabled
+from amazon.opentelemetry.distro._utils import get_aws_region, is_agent_observability_enabled, is_installed
 from amazon.opentelemetry.distro.aws_opentelemetry_configurator import (
     APPLICATION_SIGNALS_ENABLED_CONFIG,
     OTEL_EXPORTER_OTLP_LOGS_ENDPOINT,
@@ -86,6 +86,21 @@ def _configure(self, **kwargs):
         if cwd_path not in sys.path:
             sys.path.insert(0, cwd_path)
 
+        # Check if Django is installed and determine if Django instrumentation should be enabled
+        if is_installed("django"):
+            # Django instrumentation is allowed when DJANGO_SETTINGS_MODULE is set
+            if not os.getenv("DJANGO_SETTINGS_MODULE"):
+                # DJANGO_SETTINGS_MODULE is not set, disable Django instrumentation
+                disabled_instrumentations = os.getenv("OTEL_PYTHON_DISABLED_INSTRUMENTATIONS", "")
+                os.environ["OTEL_PYTHON_DISABLED_INSTRUMENTATIONS"] = disabled_instrumentations + ",django"
+                _logger.warning(
+                    "Django is installed but DJANGO_SETTINGS_MODULE is not set. Disabling django instrumentation."
+                )
+            else:
+                _logger.debug(
+                    "Django instrumentation enabled: DJANGO_SETTINGS_MODULE=%s", os.getenv("DJANGO_SETTINGS_MODULE")
+                )
+
         os.environ.setdefault(OTEL_EXPORTER_OTLP_PROTOCOL, "http/protobuf")
 
         if os.environ.get(OTEL_PROPAGATORS, None) is None:

aws-opentelemetry-distro/tests/amazon/opentelemetry/distro/test_aws_opentelemetry_distro.py

@@ -32,6 +32,7 @@ def setUp(self):
             "OTEL_PYTHON_DISABLED_INSTRUMENTATIONS",
             "OTEL_PYTHON_LOGGING_AUTO_INSTRUMENTATION_ENABLED",
             "OTEL_AWS_APPLICATION_SIGNALS_ENABLED",
+            "DJANGO_SETTINGS_MODULE",
         ]
 
         # First, save all current values
@@ -100,14 +101,21 @@ def test_configure_without_patches(self, mock_super_configure, mock_apply_patche
 
     @patch("amazon.opentelemetry.distro.aws_opentelemetry_distro.get_aws_region")
     @patch("amazon.opentelemetry.distro.aws_opentelemetry_distro.is_agent_observability_enabled")
+    @patch("amazon.opentelemetry.distro.aws_opentelemetry_distro.is_installed")
     @patch("amazon.opentelemetry.distro.aws_opentelemetry_distro.apply_instrumentation_patches")
     @patch("amazon.opentelemetry.distro.aws_opentelemetry_distro.OpenTelemetryDistro._configure")
     def test_configure_with_agent_observability_enabled(
-        self, mock_super_configure, mock_apply_patches, mock_is_agent_observability, mock_get_aws_region
+        self,
+        mock_super_configure,
+        mock_apply_patches,
+        mock_is_installed,
+        mock_is_agent_observability,
+        mock_get_aws_region,
     ):
         """Test that _configure sets agent observability defaults when enabled"""
         mock_is_agent_observability.return_value = True
         mock_get_aws_region.return_value = "us-west-2"
+        mock_is_installed.return_value = False  # Mock Django as not installed to avoid interference
 
         distro = AwsOpenTelemetryDistro()
         distro._configure()
@@ -277,3 +285,116 @@ def test_otel_propagators_added_when_not_user_defined(self, mock_super_configure
         for prop in individual_propagators:
             actual_propagators.append(type(prop).__name__)
         self.assertEqual(expected_propagators, actual_propagators)
+
+    # Django Instrumentation Tests
+    @patch("amazon.opentelemetry.distro.aws_opentelemetry_distro.is_installed")
+    @patch("amazon.opentelemetry.distro.aws_opentelemetry_distro.apply_instrumentation_patches")
+    @patch("amazon.opentelemetry.distro.aws_opentelemetry_distro.OpenTelemetryDistro._configure")
+    def test_django_instrumentation_enabled_with_settings_module(
+        self, mock_super_configure, mock_apply_patches, mock_is_installed
+    ):
+        """Test that Django instrumentation is enabled when DJANGO_SETTINGS_MODULE is set"""
+        mock_is_installed.return_value = True
+        os.environ["DJANGO_SETTINGS_MODULE"] = "myproject.settings"
+
+        distro = AwsOpenTelemetryDistro()
+        distro._configure()
+
+        # Verify that django is NOT in disabled instrumentations
+        disabled_instrumentations = os.environ.get("OTEL_PYTHON_DISABLED_INSTRUMENTATIONS", "")
+        self.assertNotIn("django", disabled_instrumentations)
+
+        mock_is_installed.assert_called_once_with("django")
+
+    @patch("amazon.opentelemetry.distro.aws_opentelemetry_distro.is_installed")
+    @patch("amazon.opentelemetry.distro.aws_opentelemetry_distro.apply_instrumentation_patches")
+    @patch("amazon.opentelemetry.distro.aws_opentelemetry_distro.OpenTelemetryDistro._configure")
+    def test_django_instrumentation_disabled_without_settings_module(
+        self, mock_super_configure, mock_apply_patches, mock_is_installed
+    ):
+        """Test that Django instrumentation is disabled when DJANGO_SETTINGS_MODULE is not set"""
+        mock_is_installed.return_value = True
+
+        distro = AwsOpenTelemetryDistro()
+        distro._configure()
+
+        # Verify that django is in disabled instrumentations
+        disabled_instrumentations = os.environ.get("OTEL_PYTHON_DISABLED_INSTRUMENTATIONS", "")
+        self.assertIn("django", disabled_instrumentations)
+
+        mock_is_installed.assert_called_once_with("django")
+
+    @patch("amazon.opentelemetry.distro.aws_opentelemetry_distro.is_installed")
+    @patch("amazon.opentelemetry.distro.aws_opentelemetry_distro.apply_instrumentation_patches")
+    @patch("amazon.opentelemetry.distro.aws_opentelemetry_distro.OpenTelemetryDistro._configure")
+    def test_django_instrumentation_disabled_with_existing_disabled_instrumentations(
+        self, mock_super_configure, mock_apply_patches, mock_is_installed
+    ):
+        """Test that Django is appended to existing disabled instrumentations"""
+        mock_is_installed.return_value = True
+        os.environ["OTEL_PYTHON_DISABLED_INSTRUMENTATIONS"] = "flask,fastapi"
+
+        distro = AwsOpenTelemetryDistro()
+        distro._configure()
+
+        # Verify that django is appended to existing disabled instrumentations
+        disabled_instrumentations = os.environ.get("OTEL_PYTHON_DISABLED_INSTRUMENTATIONS", "")
+        self.assertEqual("flask,fastapi,django", disabled_instrumentations)
+
+        mock_is_installed.assert_called_once_with("django")
+
+    @patch("amazon.opentelemetry.distro.aws_opentelemetry_distro.is_installed")
+    @patch("amazon.opentelemetry.distro.aws_opentelemetry_distro.apply_instrumentation_patches")
+    @patch("amazon.opentelemetry.distro.aws_opentelemetry_distro.OpenTelemetryDistro._configure")
+    def test_django_not_installed_no_effect(self, mock_super_configure, mock_apply_patches, mock_is_installed):
+        """Test that when Django is not installed, no changes are made to disabled instrumentations"""
+        mock_is_installed.return_value = False
+
+        distro = AwsOpenTelemetryDistro()
+        distro._configure()
+
+        # Verify that OTEL_PYTHON_DISABLED_INSTRUMENTATIONS is not affected
+        disabled_instrumentations = os.environ.get("OTEL_PYTHON_DISABLED_INSTRUMENTATIONS", "")
+        self.assertEqual("", disabled_instrumentations)
+
+        mock_is_installed.assert_called_once_with("django")
+
+    @patch("amazon.opentelemetry.distro.aws_opentelemetry_distro.is_installed")
+    @patch("amazon.opentelemetry.distro.aws_opentelemetry_distro.apply_instrumentation_patches")
+    @patch("amazon.opentelemetry.distro.aws_opentelemetry_distro.OpenTelemetryDistro._configure")
+    def test_django_instrumentation_enabled_with_settings_module_and_existing_disabled(
+        self, mock_super_configure, mock_apply_patches, mock_is_installed
+    ):
+        """Test that Django instrumentation is enabled even with existing disabled instrumentations"""
+        mock_is_installed.return_value = True
+        os.environ["DJANGO_SETTINGS_MODULE"] = "myproject.settings"
+        os.environ["OTEL_PYTHON_DISABLED_INSTRUMENTATIONS"] = "flask,fastapi"
+
+        distro = AwsOpenTelemetryDistro()
+        distro._configure()
+
+        # Verify that django is NOT added to disabled instrumentations
+        disabled_instrumentations = os.environ.get("OTEL_PYTHON_DISABLED_INSTRUMENTATIONS", "")
+        self.assertEqual("flask,fastapi", disabled_instrumentations)
+        self.assertNotIn("django", disabled_instrumentations)
+
+        mock_is_installed.assert_called_once_with("django")
+
+    @patch("amazon.opentelemetry.distro.aws_opentelemetry_distro.is_installed")
+    @patch("amazon.opentelemetry.distro.aws_opentelemetry_distro.apply_instrumentation_patches")
+    @patch("amazon.opentelemetry.distro.aws_opentelemetry_distro.OpenTelemetryDistro._configure")
+    def test_django_instrumentation_disabled_empty_settings_module(
+        self, mock_super_configure, mock_apply_patches, mock_is_installed
+    ):
+        """Test that Django instrumentation is disabled when DJANGO_SETTINGS_MODULE is empty"""
+        mock_is_installed.return_value = True
+        os.environ["DJANGO_SETTINGS_MODULE"] = ""
+
+        distro = AwsOpenTelemetryDistro()
+        distro._configure()
+
+        # Verify that django is in disabled instrumentations
+        disabled_instrumentations = os.environ.get("OTEL_PYTHON_DISABLED_INSTRUMENTATIONS", "")
+        self.assertIn("django", disabled_instrumentations)
+
+        mock_is_installed.assert_called_once_with("django")