Python: support enable_message_events parameter in enable_instrumentation (#8412)

python/packages/core/agent_framework/observability.py

@@ -1556,6 +1556,7 @@ def disable_instrumentation() -> None:
 def enable_instrumentation(
     *,
     enable_sensitive_data: bool | None = None,
+    enable_message_events: bool | None = None,
     force: bool = False,
 ) -> None:
     """Enable instrumentation for Microsoft Agent Framework.
@@ -1568,6 +1569,10 @@ def enable_instrumentation(
     Keyword Args:
         enable_sensitive_data: Enable OpenTelemetry sensitive events. Overrides
             the environment variable ENABLE_SENSITIVE_DATA if set. Default is None.
+        enable_message_events: Emit the baseline v1.36.0 GenAI message events (``gen_ai.system.message``,
+            ``gen_ai.user.message``, ``gen_ai.assistant.message``, ``gen_ai.tool.message``, ``gen_ai.choice``)
+            for model invocation. Overrides the environment variable ENABLE_MESSAGE_EVENTS if set. Default is None.
+            Only takes effect when sensitive data capture is enabled.
         force: When True, clears any sticky disable previously set by
             ``disable_instrumentation()`` before enabling. Without it, calls are
             no-ops if instrumentation has been explicitly disabled.
@@ -1588,6 +1593,12 @@ def enable_instrumentation(
         # Re-read from current environment in case env vars were set after import (e.g. load_dotenv())
         OBSERVABILITY_SETTINGS.enable_sensitive_data = _read_bool_env("ENABLE_SENSITIVE_DATA")
 
+    if enable_message_events is not None:
+        OBSERVABILITY_SETTINGS.enable_message_events = enable_message_events
+    else:
+        # Re-read from current environment in case env vars were set after import (e.g. load_dotenv())
+        OBSERVABILITY_SETTINGS.enable_message_events = _read_bool_env("ENABLE_MESSAGE_EVENTS", default=True)
+
 
 def configure_otel_providers(
     *,

python/packages/core/tests/core/test_observability.py

@@ -1914,6 +1914,37 @@ def test_enable_instrumentation_explicit_param_overrides_env(monkeypatch):
     assert observability.OBSERVABILITY_SETTINGS.enable_sensitive_data is False
 
 
+def test_enable_instrumentation_with_message_events(monkeypatch):
+    """Test enable_instrumentation function with explicit enable_message_events parameter."""
+    import importlib
+
+    monkeypatch.setenv("ENABLE_INSTRUMENTATION", "false")
+    monkeypatch.setenv("ENABLE_MESSAGE_EVENTS", "true")
+
+    observability = importlib.import_module("agent_framework.observability")
+    importlib.reload(observability)
+
+    observability.enable_instrumentation(enable_message_events=False)
+    assert observability.OBSERVABILITY_SETTINGS.enable_instrumentation is True
+    assert observability.OBSERVABILITY_SETTINGS.enable_message_events is False
+
+
+def test_enable_instrumentation_explicit_message_events_overrides_env(monkeypatch):
+    """Test that explicit enable_message_events parameter to enable_instrumentation overrides env var."""
+    import importlib
+
+    monkeypatch.setenv("ENABLE_INSTRUMENTATION", "false")
+    monkeypatch.setenv("ENABLE_MESSAGE_EVENTS", "false")
+
+    observability = importlib.import_module("agent_framework.observability")
+    importlib.reload(observability)
+
+    # Explicit True should override the env var False
+    observability.enable_instrumentation(enable_message_events=True)
+    assert observability.OBSERVABILITY_SETTINGS.enable_instrumentation is True
+    assert observability.OBSERVABILITY_SETTINGS.enable_message_events is True
+
+
 def test_enable_instrumentation_does_not_touch_console_exporters(monkeypatch):
     """Test enable_instrumentation does not modify enable_console_exporters (it is an exporter concern)."""
     import importlib
@@ -2253,6 +2284,24 @@ def test_enable_instrumentation_reads_env_sensitive_data(monkeypatch):
     assert observability.OBSERVABILITY_SETTINGS.enable_sensitive_data is True
 
 
+def test_enable_instrumentation_reads_env_message_events(monkeypatch):
+    """No-arg enable_instrumentation() re-reads ENABLE_MESSAGE_EVENTS from env at call time."""
+    import importlib
+
+    monkeypatch.setenv("ENABLE_INSTRUMENTATION", "false")
+    monkeypatch.setenv("ENABLE_MESSAGE_EVENTS", "true")
+
+    observability = importlib.import_module("agent_framework.observability")
+    importlib.reload(observability)
+
+    # Simulate load_dotenv() or runtime env change setting the env var after import
+    monkeypatch.setenv("ENABLE_MESSAGE_EVENTS", "false")
+    observability.enable_instrumentation()
+
+    assert observability.OBSERVABILITY_SETTINGS.enable_instrumentation is True
+    assert observability.OBSERVABILITY_SETTINGS.enable_message_events is False
+
+
 # region Test GenAI semconv stability opt-in