From 7b55b79bdb732b1dde61142eb88dec0a88e4f495 Mon Sep 17 00:00:00 2001
From: Copilot <198982749+Copilot@users.noreply.github.com>
Date: Mon, 17 Nov 2025 07:57:32 -0600
Subject: [PATCH] Add Microsoft.Extensions.AI tracing documentation to OpenAI
 integration (#5745)

* Initial plan

* Add Microsoft.Extensions.AI tracing info and EnableSensitiveTelemetryData to OpenAI docs

Co-authored-by: JamesNK <303201+JamesNK@users.noreply.github.com>

* Move OpenAI telemetry details to "Using underlying library telemetry" section

Co-authored-by: JamesNK <303201+JamesNK@users.noreply.github.com>

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: JamesNK <303201+JamesNK@users.noreply.github.com>
---
 docs/openai/openai-integration.md | 51 +++++++++++++++++++++++++++++--
 1 file changed, 49 insertions(+), 2 deletions(-)

diff --git a/docs/openai/openai-integration.md b/docs/openai/openai-integration.md
index 5a2e40bfcb..100a9e9c77 100644
--- a/docs/openai/openai-integration.md
+++ b/docs/openai/openai-integration.md
@@ -239,7 +239,7 @@ Endpoint={endpoint};Key={api_key};Model={model_name}
 
 #### Use configuration providers
 
-Configure via `Aspire:OpenAI` keys (global) and `Aspire:OpenAI:{connectionName}` (per named client). Supported settings include `Key`, `Endpoint`, `DisableTracing`, `DisableMetrics`, and the `ClientOptions` subtree (`UserAgentApplicationId`, `OrganizationId`, `ProjectId`, `NetworkTimeout`, logging options, etc.).
+Configure via `Aspire:OpenAI` keys (global) and `Aspire:OpenAI:{connectionName}` (per named client). Supported settings include `Key`, `Endpoint`, `DisableTracing`, `DisableMetrics`, `EnableSensitiveTelemetryData`, and the `ClientOptions` subtree (`UserAgentApplicationId`, `OrganizationId`, `ProjectId`, `NetworkTimeout`, logging options, etc.).
 
 ```json
 {
@@ -280,7 +280,54 @@ Explore the end-to-end sample that wires up the hosting and client integrations,
 
 #### Tracing
 
-- `OpenAI.*` (when telemetry enabled and not disabled)
+The Aspire OpenAI integration will emit the following tracing activities using OpenTelemetry:
+
+- `Experimental.Microsoft.Extensions.AI` - Used by Microsoft.Extensions.AI to record AI operations
+
+> [!IMPORTANT]
+> Telemetry is only recorded by default when using the `IChatClient` interface from Microsoft.Extensions.AI. Raw `OpenAIClient` calls do not automatically generate telemetry.
+
+##### Configuring sensitive data in telemetry
+
+By default, telemetry includes metadata such as token counts, but not raw inputs and outputs like message content. To include potentially sensitive information in telemetry, set the `EnableSensitiveTelemetryData` configuration option:
+
+```csharp
+builder.AddOpenAIClient("chat", settings =>
+{
+    settings.EnableSensitiveTelemetryData = true;
+})
+.AddChatClient();
+```
+
+Or through configuration:
+
+```json
+{
+  "Aspire": {
+    "OpenAI": {
+      "EnableSensitiveTelemetryData": true
+    }
+  }
+}
+```
+
+Alternatively, you can enable sensitive data capture by setting the environment variable:
+
+```bash
+OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=true
+```
+
+##### Using underlying library telemetry
+
+If you need to access telemetry from the underlying OpenAI library directly, you can manually add the appropriate activity sources and meters to your OpenTelemetry configuration:
+
+```csharp
+builder.Services.AddOpenTelemetry()
+    .WithTracing(tracing => tracing.AddSource("OpenAI.*"))
+    .WithMetrics(metrics => metrics.AddMeter("OpenAI.*"));
+```
+
+However, you'll need to enable experimental telemetry support in the OpenAI library by setting the `OPENAI_EXPERIMENTAL_ENABLE_OPEN_TELEMETRY` environment variable to `"true"` or calling `AppContext.SetSwitch("OpenAI.Experimental.EnableOpenTelemetry", true)` during app startup.
 
 #### Metrics