[Sql Instrumentation] Unify exposed public API

src/OpenTelemetry.Instrumentation.Http/HttpClientInstrumentationOptions.cs

@@ -33,12 +33,12 @@ public class HttpClientInstrumentationOptions
         /// collect telemetry about requests on a per request basis.
         /// </summary>
         /// <remarks>
-        /// Notes:
-        /// <list type="bullet">
-        /// <item><b>FilterHttpRequestMessage is only executed on .NET and .NET
+        /// <para><b>FilterHttpRequestMessage is only executed on .NET and .NET
         /// Core runtimes. <see cref="HttpClient"/> and <see
         /// cref="HttpWebRequest"/> on .NET and .NET Core are both implemented
-        /// using <see cref="HttpRequestMessage"/>.</b></item>
+        /// using <see cref="HttpRequestMessage"/>.</b></para>
+        /// Notes:
+        /// <list type="bullet">
         /// <item>The return value for the filter function is interpreted as:
         /// <list type="bullet">
         /// <item>If filter returns <see langword="true" />, the request is
@@ -51,38 +51,32 @@ public class HttpClientInstrumentationOptions
         public Func<HttpRequestMessage, bool> FilterHttpRequestMessage { get; set; }
 
         /// <summary>
-        /// Gets or sets an action to enrich an Activity with <see cref="HttpRequestMessage"/>.
+        /// Gets or sets an action to enrich an <see cref="Activity"/> with <see cref="HttpRequestMessage"/>.
         /// </summary>
         /// <remarks>
         /// <para><b>EnrichWithHttpRequestMessage is only executed on .NET and .NET
         /// Core runtimes. <see cref="HttpClient"/> and <see
         /// cref="HttpWebRequest"/> on .NET and .NET Core are both implemented
         /// using <see cref="HttpRequestMessage"/>.</b></para>
-        /// <para><see cref="Activity"/>: the activity being enriched.</para>
-        /// <para><see cref="HttpRequestMessage"/> object from which additional information can be extracted to enrich the activity.</para>
         /// </remarks>
         public Action<Activity, HttpRequestMessage> EnrichWithHttpRequestMessage { get; set; }
 
         /// <summary>
-        /// Gets or sets an action to enrich an Activity with <see cref="HttpResponseMessage"/>.
+        /// Gets or sets an action to enrich an <see cref="Activity"/> with <see cref="HttpResponseMessage"/>.
         /// </summary>
         /// <remarks>
         /// <para><b>EnrichWithHttpResponseMessage is only executed on .NET and .NET
         /// Core runtimes. <see cref="HttpClient"/> and <see
         /// cref="HttpWebRequest"/> on .NET and .NET Core are both implemented
         /// using <see cref="HttpRequestMessage"/>.</b></para>
-        /// <para><see cref="Activity"/>: the activity being enriched.</para>
-        /// <para><see cref="HttpResponseMessage"/> object from which additional information can be extracted to enrich the activity.</para>
         /// </remarks>
         public Action<Activity, HttpResponseMessage> EnrichWithHttpResponseMessage { get; set; }
 
         /// <summary>
-        /// Gets or sets an action to enrich an Activity with <see cref="Exception"/>.
+        /// Gets or sets an action to enrich an <see cref="Activity"/> with <see cref="Exception"/>.
         /// </summary>
         /// <remarks>
         /// <para><b>EnrichWithException is called for all runtimes.</b></para>
-        /// <para><see cref="Activity"/>: the activity being enriched.</para>
-        /// <para><see cref="Exception"/> object from which additional information can be extracted to enrich the activity.</para>
         /// </remarks>
         public Action<Activity, Exception> EnrichWithException { get; set; }
 
@@ -91,12 +85,12 @@ public class HttpClientInstrumentationOptions
         /// collect telemetry about requests on a per request basis.
         /// </summary>
         /// <remarks>
-        /// Notes:
-        /// <list type="bullet">
-        /// <item><b>FilterHttpWebRequest is only executed on .NET Framework
+        /// <para><b>FilterHttpWebRequest is only executed on .NET Framework
         /// runtimes. <see cref="HttpClient"/> and <see cref="HttpWebRequest"/>
         /// on .NET Framework are both implemented using <see
-        /// cref="HttpWebRequest"/>.</b></item>
+        /// cref="HttpWebRequest"/>.</b></para>
+        /// Notes:
+        /// <list type="bullet">
         /// <item>The return value for the filter function is interpreted as:
         /// <list type="bullet">
         /// <item>If filter returns <see langword="true" />, the request is
@@ -109,36 +103,37 @@ public class HttpClientInstrumentationOptions
         public Func<HttpWebRequest, bool> FilterHttpWebRequest { get; set; }
 
         /// <summary>
-        /// Gets or sets an action to enrich an Activity with <see cref="HttpWebRequest"/>.
+        /// Gets or sets an action to enrich an <see cref="Activity"/> with <see cref="HttpWebRequest"/>.
         /// </summary>
         /// <remarks>
         /// <para><b>EnrichWithHttpWebRequest is only executed on .NET Framework
         /// runtimes. <see cref="HttpClient"/> and <see cref="HttpWebRequest"/>
         /// on .NET Framework are both implemented using <see
         /// cref="HttpWebRequest"/>.</b></para>
-        /// <para><see cref="Activity"/>: the activity being enriched.</para>
-        /// <para><see cref="HttpWebRequest"/> object from which additional information can be extracted to enrich the activity.</para>
         /// </remarks>
         public Action<Activity, HttpWebRequest> EnrichWithHttpWebRequest { get; set; }
 
         /// <summary>
-        /// Gets or sets an action to enrich an Activity with <see cref="HttpWebResponse"/>.
+        /// Gets or sets an action to enrich an <see cref="Activity"/> with <see cref="HttpWebResponse"/>.
         /// </summary>
         /// <remarks>
         /// <para><b>EnrichWithHttpWebResponse is only executed on .NET Framework
         /// runtimes. <see cref="HttpClient"/> and <see cref="HttpWebRequest"/>
         /// on .NET Framework are both implemented using <see
         /// cref="HttpWebRequest"/>.</b></para>
-        /// <para><see cref="Activity"/>: the activity being enriched.</para>
-        /// <para><see cref="HttpWebResponse"/> object from which additional information can be extracted to enrich the activity.</para>
         /// </remarks>
         public Action<Activity, HttpWebResponse> EnrichWithHttpWebResponse { get; set; }
 
         /// <summary>
-        /// Gets or sets a value indicating whether exception will be recorded as an <see cref="ActivityEvent"/> or not.
+        /// Gets or sets a value indicating whether exception will be recorded
+        /// as an <see cref="ActivityEvent"/> or not. Default value: <see
+        /// langword="false"/>.
         /// </summary>
         /// <remarks>
-        /// See: <see href="https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/semantic_conventions/exceptions.md" />.
+        /// <para><b>RecordException is supported on all runtimes.</b></para>
+        /// <para>For specification details see: <see
+        /// href="https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/semantic_conventions/exceptions.md"
+        /// />.</para>
         /// </remarks>
         public bool RecordException { get; set; }
 

src/OpenTelemetry.Instrumentation.SqlClient/.publicApi/net462/PublicAPI.Unshipped.txt

@@ -3,8 +3,14 @@ OpenTelemetry.Instrumentation.SqlClient.SqlClientInstrumentationOptions.EnableCo
 OpenTelemetry.Instrumentation.SqlClient.SqlClientInstrumentationOptions.EnableConnectionLevelAttributes.set -> void
 OpenTelemetry.Instrumentation.SqlClient.SqlClientInstrumentationOptions.Enrich.get -> System.Action<System.Diagnostics.Activity, string, object>
 OpenTelemetry.Instrumentation.SqlClient.SqlClientInstrumentationOptions.Enrich.set -> void
-OpenTelemetry.Instrumentation.SqlClient.SqlClientInstrumentationOptions.SetDbStatement.get -> bool
-OpenTelemetry.Instrumentation.SqlClient.SqlClientInstrumentationOptions.SetDbStatement.set -> void
+OpenTelemetry.Instrumentation.SqlClient.SqlClientInstrumentationOptions.Filter.get -> System.Func<object, bool>
+OpenTelemetry.Instrumentation.SqlClient.SqlClientInstrumentationOptions.Filter.set -> void
+OpenTelemetry.Instrumentation.SqlClient.SqlClientInstrumentationOptions.RecordException.get -> bool
+OpenTelemetry.Instrumentation.SqlClient.SqlClientInstrumentationOptions.RecordException.set -> void
+OpenTelemetry.Instrumentation.SqlClient.SqlClientInstrumentationOptions.SetDbStatementForStoredProcedure.get -> bool
+OpenTelemetry.Instrumentation.SqlClient.SqlClientInstrumentationOptions.SetDbStatementForStoredProcedure.set -> void
+OpenTelemetry.Instrumentation.SqlClient.SqlClientInstrumentationOptions.SetDbStatementForText.get -> bool
+OpenTelemetry.Instrumentation.SqlClient.SqlClientInstrumentationOptions.SetDbStatementForText.set -> void
 OpenTelemetry.Instrumentation.SqlClient.SqlClientInstrumentationOptions.SqlClientInstrumentationOptions() -> void
 OpenTelemetry.Trace.TracerProviderBuilderExtensions
 static OpenTelemetry.Trace.TracerProviderBuilderExtensions.AddSqlClientInstrumentation(this OpenTelemetry.Trace.TracerProviderBuilder builder, System.Action<OpenTelemetry.Instrumentation.SqlClient.SqlClientInstrumentationOptions> configureSqlClientInstrumentationOptions = null) -> OpenTelemetry.Trace.TracerProviderBuilder

src/OpenTelemetry.Instrumentation.SqlClient/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 ## Unreleased
 
+* **Breaking change**: The same API is now exposed for `net462` and
+  `netstandard2.0` targets. `SetDbStatement` has been removed. Use
+  `SetDbStatementForText` to capture command text and stored procedure names on
+  .NET Framework.
+  ([#3900](https://github.com/open-telemetry/opentelemetry-dotnet/pull/3900))
+
 ## 1.0.0-rc9.9
 
 Released 2022-Nov-07

src/OpenTelemetry.Instrumentation.SqlClient/Implementation/SqlEventSourceListener.netfx.cs

@@ -13,6 +13,7 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 // </copyright>
+
 #if NETFRAMEWORK
 using System;
 using System.Diagnostics;
@@ -30,13 +31,9 @@ namespace OpenTelemetry.Instrumentation.SqlClient.Implementation
     /// We hook into these event sources and process their BeginExecute/EndExecute events.
     /// </summary>
     /// <remarks>
-    /// Note that before version 2.0.0, Microsoft.Data.SqlClient used "Microsoft-AdoNet-SystemData"
-    /// EventSource (same as System.Data.SqlClient), but since 2.0.0 has switched to "Microsoft.Data.SqlClient.EventSource".
-    ///
-    /// Due to the limitation of the "Microsoft-AdoNet-SystemData", it is not possible to capture sql statement text
-    /// for CommandType.Text when using that EventSource. It only reports text for CommandType.StoredProcedure.
-    ///
-    /// "Microsoft.Data.SqlClient.EventSource" doesn't have that issue.
+    /// Note that before version 2.0.0, Microsoft.Data.SqlClient used
+    /// "Microsoft-AdoNet-SystemData" (same as System.Data.SqlClient), but since
+    /// 2.0.0 has switched to "Microsoft.Data.SqlClient.EventSource".
     /// </remarks>
     internal sealed class SqlEventSourceListener : EventListener
     {
@@ -115,8 +112,12 @@ private void OnBeginExecute(EventWrittenEventArgs eventData)
                 [3] -> CommandText
 
                 Note:
-                - For "Microsoft-AdoNet-SystemData": [3] CommandText = (CommandType == CommandType.StoredProcedure ? CommandText : string.Empty;
-                - For "Microsoft.Data.SqlClient.EventSource": [3] CommandText = sqlCommand.CommandText (so it is set for all command types).
+                - For "Microsoft-AdoNet-SystemData" v1.0: [3] CommandText = CommandType == CommandType.StoredProcedure ? CommandText : string.Empty; (so it is set for only StoredProcedure command types)
+                    (https://github.com/dotnet/SqlClient/blob/v1.0.19239.1/src/Microsoft.Data.SqlClient/netfx/src/Microsoft/Data/SqlClient/SqlCommand.cs#L6369)
+                - For "Microsoft-AdoNet-SystemData" v1.1: [3] CommandText = sqlCommand.CommandText (so it is set for all command types)
+                    (https://github.com/dotnet/SqlClient/blob/v1.1.0/src/Microsoft.Data.SqlClient/netfx/src/Microsoft/Data/SqlClient/SqlCommand.cs#L7459)
+                - For "Microsoft.Data.SqlClient.EventSource" v2.0+: [3] CommandText = sqlCommand.CommandText (so it is set for all command types).
+                    (https://github.com/dotnet/SqlClient/blob/f4568ce68da21db3fe88c0e72e1287368aaa1dc8/src/Microsoft.Data.SqlClient/netcore/src/Microsoft/Data/SqlClient/SqlCommand.cs#L6641)
              */
 
             if ((eventData?.Payload?.Count ?? 0) < 4)
@@ -148,7 +149,7 @@ private void OnBeginExecute(EventWrittenEventArgs eventData)
                 this.options.AddConnectionLevelDetailsToActivity((string)eventData.Payload[1], activity);
 
                 string commandText = (string)eventData.Payload[3];
-                if (!string.IsNullOrEmpty(commandText) && this.options.SetDbStatement)
+                if (!string.IsNullOrEmpty(commandText) && this.options.SetDbStatementForText)
                 {
                     activity.SetTag(SemanticConventions.AttributeDbStatement, commandText);
                 }