Support OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT to turn on message tracing in Agents SDK (Azure#42445)

dargilco · web-flow · commit 2dcb122fc85e · 2025-08-12T08:00:48.000-07:00
diff --git a/sdk/ai/azure-ai-agents/CHANGELOG.md b/sdk/ai/azure-ai-agents/CHANGELOG.md
@@ -6,6 +6,8 @@
 ### Features Added
 
 - Add support for Browser Automation tool.
+- Add support for environment variable `OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT` as defined by
+  [OpenTelemetry](https://opentelemetry.io/), to control tracing of user and Agent messages content.
 
 ### Bugs Fixed
 
diff --git a/sdk/ai/azure-ai-agents/README.md b/sdk/ai/azure-ai-agents/README.md
@@ -1616,11 +1616,15 @@ enable_telemetry(destination=sys.stdout)
 ```
 
 ### Enabling content recording
-Content recording controles whether message contents and tool call related details, such as parameters and return values, are captured with the traces.
-To enable content recording set the `AZURE_TRACING_GEN_AI_CONTENT_RECORDING_ENABLED` environment variable value to `true`. If the environment variable is not set, then the value will default to `false`.
 
+Content recording controls whether message contents and tool call related details, such as parameters and return values, are captured with the traces. This data may include sensitive user information.
 
-**Important:** The `AZURE_TRACING_GEN_AI_CONTENT_RECORDING_ENABLED` environment variable only controls content recording for built-in agent traces. When you use the `@trace_function` decorator on your own functions, all parameters and return values are always traced.
+To enable content recording set the `OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT` environment variable to `true`. This environment variable is defined
+by [OpenTelemetry](https://opentelemetry.io/), and all new applications are encouraged to use it when content recording is required. For legacy reasons, content recordings will also be enabled if `AZURE_TRACING_GEN_AI_CONTENT_RECORDING_ENABLED` environment variable is set to `true`.
+
+If neither environment variable is set, content recording defaults to `false`. If either variable is set to `false`, content recording will be disabled, regardless of the other's value.
+
+**Important:** The environment variables only control content recording for built-in agent traces. When you use the `@trace_function` decorator on your own functions, all parameters and return values are always traced.
 
 ### How to trace your own functions
 
diff --git a/sdk/ai/azure-ai-agents/azure/ai/agents/telemetry/_ai_agents_instrumentor.py b/sdk/ai/azure-ai-agents/azure/ai/agents/telemetry/_ai_agents_instrumentor.py
@@ -127,13 +127,16 @@ def instrument(self, enable_content_recording: Optional[bool] = None) -> None:
         :param enable_content_recording: Whether content recording is enabled as part
           of the traces or not. Content in this context refers to chat message content
           and function call tool related function names, function parameter names and
-          values. True will enable content recording, False will disable it. If no value
-          is provided, then the value read from environment variable
-          AZURE_TRACING_GEN_AI_CONTENT_RECORDING_ENABLED is used. If the environment variable
-          is not found, then the value will default to False. Please note that successive calls
+          values. `True` will enable content recording, `False` will disable it. If no value
+          is provided, then the value read from environment variables
+          OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT and
+          AZURE_TRACING_GEN_AI_CONTENT_RECORDING_ENABLED is used. The latter is supported
+          for legacy reasons. Applications are encouraged to use the former, which is defined by OTEL.
+          If the environment variable is not found, then the value will default to `False`.
+          Please note that successive calls
           to instrument will always apply the content recording value provided with the most
           recent call to instrument (including applying the environment variable if no value is
-          provided and defaulting to false if the environment variable is not found), even if
+          provided and defaulting to `False` if the environment variable is not found), even if
           instrument was already previously called without uninstrument being called in between
           the instrument calls.
         :type enable_content_recording: bool, optional
@@ -187,18 +190,47 @@ def instrument(self, enable_content_recording: Optional[bool] = None):
         Enable trace instrumentation for AI Agents.
 
         :param enable_content_recording: Whether content recording is enabled as part
-        of the traces or not. Content in this context refers to chat message content
-        and function call tool related function names, function parameter names and
-        values. True will enable content recording, False will disable it. If no value
-        is provided, then the value read from environment variable
-        AZURE_TRACING_GEN_AI_CONTENT_RECORDING_ENABLED is used. If the environment variable
-        is not found, then the value will default to False.
-
+          of the traces or not. Content in this context refers to chat message content
+          and function call tool related function names, function parameter names and
+          values. `True` will enable content recording, `False` will disable it. If no value
+          is provided, then the value read from environment variables
+          OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT and
+          AZURE_TRACING_GEN_AI_CONTENT_RECORDING_ENABLED is used. The latter is supported
+          for legacy reasons. Applications are encouraged to use the former, which is defined by OTEL.
+          If the environment variable is not found, then the value will default to `False`.
+          Please note that successive calls
+          to instrument will always apply the content recording value provided with the most
+          recent call to instrument (including applying the environment variable if no value is
+          provided and defaulting to `False` if the environment variable is not found), even if
+          instrument was already previously called without uninstrument being called in between
+          the instrument calls.
         :type enable_content_recording: bool, optional
+
         """
         if enable_content_recording is None:
-            var_value = os.environ.get("AZURE_TRACING_GEN_AI_CONTENT_RECORDING_ENABLED")
+
+            # AZURE_TRACING_GEN_AI_CONTENT_RECORDING_ENABLED was introduced before the standard
+            # OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT was defined by OTEL. Support both
+            # of them moving forward, but only document the standard one.
+            var_value_new = os.environ.get("OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT")
+            var_value_old = os.environ.get("AZURE_TRACING_GEN_AI_CONTENT_RECORDING_ENABLED")
+            var_value: Optional[str] = None
+
+            if var_value_new and var_value_old and var_value_new != var_value_old:
+                logger.error(
+                    "Environment variables OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT "
+                    "and AZURE_TRACING_GEN_AI_CONTENT_RECORDING_ENABLED are both set, and "
+                    "their values differ. Message content recording in this run will be disabled "
+                    "as a result. Please set OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT only."
+                )
+                var_value = None
+            elif var_value_new:
+                var_value = var_value_new
+            elif var_value_old:
+                var_value = var_value_old
+
             enable_content_recording = self._str_to_bool(var_value)
+
         if not self.is_instrumented():
             self._instrument_agents(enable_content_recording)
         else:
diff --git a/sdk/ai/azure-ai-agents/samples/agents_telemetry/sample_agents_basics_async_with_azure_monitor_tracing.py b/sdk/ai/azure-ai-agents/samples/agents_telemetry/sample_agents_basics_async_with_azure_monitor_tracing.py
@@ -20,7 +20,7 @@
     Set these environment variables with your own values:
     1) PROJECT_ENDPOINT - The Azure AI Project endpoint, as found in the Overview
        page of your Azure AI Foundry portal.
-    2) AZURE_TRACING_GEN_AI_CONTENT_RECORDING_ENABLED - Optional. Set to `true` to trace the content of chat
+    2) OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT - Optional. Set to `true` to trace the content of chat
        messages, which may contain personal data. False by default.
     3) APPLICATIONINSIGHTS_CONNECTION_STRING - Set to the connection string of your Application Insights resource.
        This is used to send telemetry data to Azure Monitor. You can also get the connection string programmatically
diff --git a/sdk/ai/azure-ai-agents/samples/agents_telemetry/sample_agents_basics_async_with_console_tracing.py b/sdk/ai/azure-ai-agents/samples/agents_telemetry/sample_agents_basics_async_with_console_tracing.py
@@ -25,7 +25,7 @@
     Set these environment variables with your own values:
     * PROJECT_ENDPOINT - The Azure AI Project endpoint, as found in the Overview
                           page of your Azure AI Foundry portal.
-    * AZURE_TRACING_GEN_AI_CONTENT_RECORDING_ENABLED - Optional. Set to `true` to trace the content of chat
+    * OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT - Optional. Set to `true` to trace the content of chat
       messages, which may contain personal data. False by default.
 """
 import asyncio
diff --git a/sdk/ai/azure-ai-agents/samples/agents_telemetry/sample_agents_basics_with_azure_monitor_tracing.py b/sdk/ai/azure-ai-agents/samples/agents_telemetry/sample_agents_basics_with_azure_monitor_tracing.py
@@ -22,7 +22,7 @@
        page of your Azure AI Foundry portal.
     2) MODEL_DEPLOYMENT_NAME - The deployment name of the AI model, as found under the "Name" column in
        the "Models + endpoints" tab in your Azure AI Foundry project.
-    3) AZURE_TRACING_GEN_AI_CONTENT_RECORDING_ENABLED - Optional. Set to `true` to trace the content of chat
+    3) OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT - Optional. Set to `true` to trace the content of chat
        messages, which may contain personal data. False by default.
     4) APPLICATIONINSIGHTS_CONNECTION_STRING - Set to the connection string of your Application Insights resource.
        This is used to send telemetry data to Azure Monitor. You can also get the connection string programmatically
diff --git a/sdk/ai/azure-ai-agents/samples/agents_telemetry/sample_agents_basics_with_console_tracing.py b/sdk/ai/azure-ai-agents/samples/agents_telemetry/sample_agents_basics_with_console_tracing.py
@@ -26,7 +26,7 @@
                           page of your Azure AI Foundry portal.
     2) MODEL_DEPLOYMENT_NAME - The deployment name of the AI model, as found under the "Name" column in
        the "Models + endpoints" tab in your Azure AI Foundry project.
-    3) AZURE_TRACING_GEN_AI_CONTENT_RECORDING_ENABLED - Optional. Set to `true` to trace the content of chat
+    3) OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT - Optional. Set to `true` to trace the content of chat
        messages, which may contain personal data. False by default.
 """
 
diff --git a/sdk/ai/azure-ai-agents/samples/agents_telemetry/sample_agents_basics_with_console_tracing_custom_attributes.py b/sdk/ai/azure-ai-agents/samples/agents_telemetry/sample_agents_basics_with_console_tracing_custom_attributes.py
@@ -27,7 +27,7 @@
                           page of your Azure AI Foundry portal.
     2) MODEL_DEPLOYMENT_NAME - The deployment name of the AI model, as found under the "Name" column in
        the "Models + endpoints" tab in your Azure AI Foundry project.
-    3) AZURE_TRACING_GEN_AI_CONTENT_RECORDING_ENABLED - Optional. Set to `true` to trace the content of chat
+    3) OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT - Optional. Set to `true` to trace the content of chat
        messages, which may contain personal data. False by default.
 """
 
diff --git a/sdk/ai/azure-ai-agents/samples/agents_telemetry/sample_agents_stream_eventhandler_with_azure_monitor_tracing.py b/sdk/ai/azure-ai-agents/samples/agents_telemetry/sample_agents_stream_eventhandler_with_azure_monitor_tracing.py
@@ -22,7 +22,7 @@
        page of your Azure AI Foundry portal.
     2) MODEL_DEPLOYMENT_NAME - The deployment name of the AI model, as found under the "Name" column in
        the "Models + endpoints" tab in your Azure AI Foundry project.
-    3) AZURE_TRACING_GEN_AI_CONTENT_RECORDING_ENABLED - Optional. Set to `true` to trace the content of chat
+    3) OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT - Optional. Set to `true` to trace the content of chat
        messages, which may contain personal data. False by default.
     4) APPLICATIONINSIGHTS_CONNECTION_STRING - Set to the connection string of your Application Insights resource.
        This is used to send telemetry data to Azure Monitor. You can also get the connection string programmatically
diff --git a/sdk/ai/azure-ai-agents/samples/agents_telemetry/sample_agents_stream_eventhandler_with_console_tracing.py b/sdk/ai/azure-ai-agents/samples/agents_telemetry/sample_agents_stream_eventhandler_with_console_tracing.py
@@ -26,7 +26,7 @@
                           page of your Azure AI Foundry portal.
     2) MODEL_DEPLOYMENT_NAME - The deployment name of the AI model, as found under the "Name" column in
        the "Models + endpoints" tab in your Azure AI Foundry project.
-    3) AZURE_TRACING_GEN_AI_CONTENT_RECORDING_ENABLED - Optional. Set to `true` to trace the content of chat
+    3) OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT - Optional. Set to `true` to trace the content of chat
        messages, which may contain personal data. False by default.
 """
 
diff --git a/sdk/ai/azure-ai-agents/samples/agents_telemetry/sample_agents_toolset_with_azure_monitor_tracing.py b/sdk/ai/azure-ai-agents/samples/agents_telemetry/sample_agents_toolset_with_azure_monitor_tracing.py
@@ -22,7 +22,7 @@
        page of your Azure AI Foundry portal.
     2) MODEL_DEPLOYMENT_NAME - The deployment name of the AI model, as found under the "Name" column in
        the "Models + endpoints" tab in your Azure AI Foundry project.
-    3) AZURE_TRACING_GEN_AI_CONTENT_RECORDING_ENABLED - Optional. Set to `true` to trace the content of chat
+    3) OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT - Optional. Set to `true` to trace the content of chat
        messages, which may contain personal data. False by default.
     4) APPLICATIONINSIGHTS_CONNECTION_STRING - Set to the connection string of your Application Insights resource.
        This is used to send telemetry data to Azure Monitor. You can also get the connection string programmatically
diff --git a/sdk/ai/azure-ai-agents/samples/agents_telemetry/sample_agents_toolset_with_console_tracing.py b/sdk/ai/azure-ai-agents/samples/agents_telemetry/sample_agents_toolset_with_console_tracing.py
@@ -26,7 +26,7 @@
                           page of your Azure AI Foundry portal.
     2) MODEL_DEPLOYMENT_NAME - The deployment name of the AI model, as found under the "Name" column in
        the "Models + endpoints" tab in your Azure AI Foundry project.
-    3) AZURE_TRACING_GEN_AI_CONTENT_RECORDING_ENABLED - Optional. Set to `true` to trace the content of chat
+    3) OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT - Optional. Set to `true` to trace the content of chat
        messages, which may contain personal data. False by default.
 """
 from typing import Any, Callable, Set
diff --git a/sdk/ai/azure-ai-agents/tests/test_ai_agents_instrumentor.py b/sdk/ai/azure-ai-agents/tests/test_ai_agents_instrumentor.py
@@ -9,7 +9,7 @@
 import json
 import time
 import functools
-from typing import Set, Callable, Any
+from typing import Set, Callable, Any, Optional
 from azure.ai.agents.models import (
     AgentsResponseFormatMode,
     AgentsResponseFormat,
@@ -48,7 +48,7 @@
     azure_ai_agents_tests_data_path="azureml://subscriptions/00000000-0000-0000-0000-000000000000/resourcegroups/rg-resour-cegr-oupfoo1/workspaces/abcd-abcdabcdabcda-abcdefghijklm/datastores/workspaceblobstore/paths/LocalUpload/000000000000/product_info_1.md",
 )
 
-CONTENT_TRACING_ENV_VARIABLE = "AZURE_TRACING_GEN_AI_CONTENT_RECORDING_ENABLED"
+CONTENT_TRACING_ENV_VARIABLE = "OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT"
 settings.tracing_implementation = "OpenTelemetry"
 _utils._span_impl_type = settings.tracing_implementation()
 
@@ -169,6 +169,58 @@ def test_uninstrumenting_twice_does_not_cause_exception(self, **kwargs):
             print(e)
         assert exception_caught == False
 
+    @pytest.mark.parametrize(
+        "env1, env2, expected",
+        [
+            (None, None, False),
+            (None, False, False),
+            (None, True, True),
+            (False, None, False),
+            (False, False, False),
+            (False, True, False),
+            (True, None, True),
+            (True, False, False),
+            (True, True, True),
+        ],
+    )
+    def test_content_recording_enabled_with_old_and_new_environment_variables(
+        self, env1: Optional[bool], env2: Optional[bool], expected: bool
+    ):
+        """
+        Test content recording enablement with both old and new environment variables.
+        This test verifies the behavior of content recording when both the current
+        and legacy environment variables are set to different combinations of values.
+        The method tests all possible combinations of None, True, and False for both
+        environment variables to ensure backward compatibility and proper precedence.
+        Args:
+            env1: Value for the current content tracing environment variable.
+                  Can be None (unset), True, or False.
+            env2: Value for the old/legacy content tracing environment variable.
+                  Can be None (unset), True, or False.
+            expected: The expected result of is_content_recording_enabled() given
+                      the environment variable combination.
+        The test ensures that only if one or both of the environment variables are
+        defined and set to "true" content recording is enabled.
+        """
+
+        OLD_CONTENT_TRACING_ENV_VARIABLE = "AZURE_TRACING_GEN_AI_CONTENT_RECORDING_ENABLED"  # Deprecated, undocumented.
+
+        def set_env_var(var_name, value):
+            if value is None:
+                os.environ.pop(var_name, None)
+            else:
+                os.environ[var_name] = "true" if value else "false"
+
+        set_env_var(CONTENT_TRACING_ENV_VARIABLE, env1)
+        set_env_var(OLD_CONTENT_TRACING_ENV_VARIABLE, env2)
+
+        self.setup_telemetry()
+        try:
+            assert AIAgentsInstrumentor().is_content_recording_enabled() == expected
+        finally:
+            self.cleanup()  # This also undefines CONTENT_TRACING_ENV_VARIABLE
+            os.environ.pop(OLD_CONTENT_TRACING_ENV_VARIABLE, None)
+
     @pytest.mark.usefixtures("instrument_with_content")
     @agentClientPreparer()
     @recorded_by_proxy
diff --git a/sdk/ai/azure-ai-agents/tests/test_ai_agents_instrumentor_async.py b/sdk/ai/azure-ai-agents/tests/test_ai_agents_instrumentor_async.py
@@ -49,7 +49,7 @@
     azure_ai_agents_tests_data_path="azureml://subscriptions/00000000-0000-0000-0000-000000000000/resourcegroups/rg-resour-cegr-oupfoo1/workspaces/abcd-abcdabcdabcda-abcdefghijklm/datastores/workspaceblobstore/paths/LocalUpload/000000000000/product_info_1.md",
 )
 
-CONTENT_TRACING_ENV_VARIABLE = "AZURE_TRACING_GEN_AI_CONTENT_RECORDING_ENABLED"
+CONTENT_TRACING_ENV_VARIABLE = "OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT"
 settings.tracing_implementation = "OpenTelemetry"
 _utils._span_impl_type = settings.tracing_implementation()
 
