Add comment LoggingChatClient et al trace-level logging (#6391)

Also fixed the name of the LoggingSpeechToTextClientBuilderExtensions type to conform to patterns used elsewhere in the library.

Author: stephentoub

src/Libraries/Microsoft.Extensions.AI/ChatCompletion/LoggingChatClient.cs

@@ -13,10 +13,18 @@
 namespace Microsoft.Extensions.AI;
 
 /// <summary>A delegating chat client that logs chat operations to an <see cref="ILogger"/>.</summary>
+/// <remarks>
 /// <para>
 /// The provided implementation of <see cref="IChatClient"/> is thread-safe for concurrent use so long as the
 /// <see cref="ILogger"/> employed is also thread-safe for concurrent use.
 /// </para>
+/// <para>
+/// When the employed <see cref="ILogger"/> enables <see cref="Logging.LogLevel.Trace"/>, the contents of
+/// chat messages and options are logged. These messages and options may contain sensitive application data.
+/// <see cref="Logging.LogLevel.Trace"/> is disabled by default and should never be enabled in a production environment.
+/// Messages and options are not logged at other logging levels.
+/// </para>
+/// </remarks>
 public partial class LoggingChatClient : DelegatingChatClient
 {
     /// <summary>An <see cref="ILogger"/> instance used for all logging.</summary>

src/Libraries/Microsoft.Extensions.AI/ChatCompletion/LoggingChatClientBuilderExtensions.cs

@@ -21,6 +21,14 @@ public static class LoggingChatClientBuilderExtensions
     /// <param name="configure">An optional callback that can be used to configure the <see cref="LoggingChatClient"/> instance.</param>
     /// <returns>The <paramref name="builder"/>.</returns>
     /// <exception cref="ArgumentNullException"><paramref name="builder"/> is <see langword="null"/>.</exception>
+    /// <remarks>
+    /// <para>
+    /// When the employed <see cref="ILogger"/> enables <see cref="Logging.LogLevel.Trace"/>, the contents of
+    /// chat messages and options are logged. These messages and options may contain sensitive application data.
+    /// <see cref="Logging.LogLevel.Trace"/> is disabled by default and should never be enabled in a production environment.
+    /// Messages and options are not logged at other logging levels.
+    /// </para>
+    /// </remarks>
     public static ChatClientBuilder UseLogging(
         this ChatClientBuilder builder,
         ILoggerFactory? loggerFactory = null,

src/Libraries/Microsoft.Extensions.AI/Embeddings/LoggingEmbeddingGenerator.cs

@@ -14,10 +14,18 @@ namespace Microsoft.Extensions.AI;
 /// <summary>A delegating embedding generator that logs embedding generation operations to an <see cref="ILogger"/>.</summary>
 /// <typeparam name="TInput">Specifies the type of the input passed to the generator.</typeparam>
 /// <typeparam name="TEmbedding">Specifies the type of the embedding instance produced by the generator.</typeparam>
+/// <remarks>
 /// <para>
 /// The provided implementation of <see cref="IEmbeddingGenerator{TInput, TEmbedding}"/> is thread-safe for concurrent use
 /// so long as the <see cref="ILogger"/> employed is also thread-safe for concurrent use.
 /// </para>
+/// <para>
+/// When the employed <see cref="ILogger"/> enables <see cref="Logging.LogLevel.Trace"/>, the contents of
+/// values and options are logged. These values and options may contain sensitive application data.
+/// <see cref="Logging.LogLevel.Trace"/> is disabled by default and should never be enabled in a production environment.
+/// Messages and options are not logged at other logging levels.
+/// </para>
+/// </remarks>
 public partial class LoggingEmbeddingGenerator<TInput, TEmbedding> : DelegatingEmbeddingGenerator<TInput, TEmbedding>
     where TEmbedding : Embedding
 {

src/Libraries/Microsoft.Extensions.AI/Embeddings/LoggingEmbeddingGeneratorBuilderExtensions.cs

@@ -23,6 +23,14 @@ public static class LoggingEmbeddingGeneratorBuilderExtensions
     /// <param name="configure">An optional callback that can be used to configure the <see cref="LoggingEmbeddingGenerator{TInput, TEmbedding}"/> instance.</param>
     /// <returns>The <paramref name="builder"/>.</returns>
     /// <exception cref="ArgumentNullException"><paramref name="builder"/> is <see langword="null"/>.</exception>
+    /// <remarks>
+    /// <para>
+    /// When the employed <see cref="ILogger"/> enables <see cref="Logging.LogLevel.Trace"/>, the contents of
+    /// values and options are logged. These values and options may contain sensitive application data.
+    /// <see cref="Logging.LogLevel.Trace"/> is disabled by default and should never be enabled in a production environment.
+    /// Messages and options are not logged at other logging levels.
+    /// </para>
+    /// </remarks>
     public static EmbeddingGeneratorBuilder<TInput, TEmbedding> UseLogging<TInput, TEmbedding>(
         this EmbeddingGeneratorBuilder<TInput, TEmbedding> builder,
         ILoggerFactory? loggerFactory = null,

src/Libraries/Microsoft.Extensions.AI/SpeechToText/LoggingSpeechToTextClient.cs

@@ -15,10 +15,18 @@
 namespace Microsoft.Extensions.AI;
 
 /// <summary>A delegating speech to text client that logs speech to text operations to an <see cref="ILogger"/>.</summary>
+/// <remarks>
 /// <para>
 /// The provided implementation of <see cref="ISpeechToTextClient"/> is thread-safe for concurrent use so long as the
 /// <see cref="ILogger"/> employed is also thread-safe for concurrent use.
 /// </para>
+/// <para>
+/// When the employed <see cref="ILogger"/> enables <see cref="Logging.LogLevel.Trace"/>, the contents of
+/// messages and options are logged. These messages and options may contain sensitive application data.
+/// <see cref="Logging.LogLevel.Trace"/> is disabled by default and should never be enabled in a production environment.
+/// Messages and options are not logged at other logging levels.
+/// </para>
+/// </remarks>
 [Experimental("MEAI001")]
 public partial class LoggingSpeechToTextClient : DelegatingSpeechToTextClient
 {

…t/SpeechToTextClientBuilderExtensions.cs …ngSpeechToTextClientBuilderExtensions.cssrc/Libraries/Microsoft.Extensions.AI/SpeechToText/SpeechToTextClientBuilderExtensions.cs renamed to src/Libraries/Microsoft.Extensions.AI/SpeechToText/LoggingSpeechToTextClientBuilderExtensions.cs src/Libraries/Microsoft.Extensions.AI/SpeechToText/SpeechToTextClientBuilderExtensions.cs renamed to src/Libraries/Microsoft.Extensions.AI/SpeechToText/LoggingSpeechToTextClientBuilderExtensions.cs

@@ -12,7 +12,7 @@ namespace Microsoft.Extensions.AI;
 
 /// <summary>Provides extensions for configuring <see cref="LoggingSpeechToTextClient"/> instances.</summary>
 [Experimental("MEAI001")]
-public static class SpeechToTextClientBuilderExtensions
+public static class LoggingSpeechToTextClientBuilderExtensions
 {
     /// <summary>Adds logging to the audio transcription client pipeline.</summary>
     /// <param name="builder">The <see cref="SpeechToTextClientBuilder"/>.</param>
@@ -22,6 +22,14 @@ public static class SpeechToTextClientBuilderExtensions
     /// </param>
     /// <param name="configure">An optional callback that can be used to configure the <see cref="LoggingSpeechToTextClient"/> instance.</param>
     /// <returns>The <paramref name="builder"/>.</returns>
+    /// <remarks>
+    /// <para>
+    /// When the employed <see cref="ILogger"/> enables <see cref="Logging.LogLevel.Trace"/>, the contents of
+    /// messages and options are logged. These messages and options may contain sensitive application data.
+    /// <see cref="Logging.LogLevel.Trace"/> is disabled by default and should never be enabled in a production environment.
+    /// Messages and options are not logged at other logging levels.
+    /// </para>
+    /// </remarks>
     public static SpeechToTextClientBuilder UseLogging(
         this SpeechToTextClientBuilder builder,
         ILoggerFactory? loggerFactory = null,