From 24f71a66c621300532a89f20aa7df6b825098812 Mon Sep 17 00:00:00 2001 From: Mikel Blanchard Date: Mon, 14 Nov 2022 10:29:00 -0800 Subject: [PATCH 1/5] Unify public api exposed in sql instrumentation package. --- .../HttpClientInstrumentationOptions.cs | 45 +++--- .../.publicApi/net462/PublicAPI.Unshipped.txt | 10 +- .../CHANGELOG.md | 6 + .../SqlEventSourceListener.netfx.cs | 21 +-- .../SqlClientInstrumentationOptions.cs | 141 +++++++++++------- .../SqlClientTests.cs | 19 +-- .../SqlEventSourceTests.netfx.cs | 6 +- 7 files changed, 141 insertions(+), 107 deletions(-) diff --git a/src/OpenTelemetry.Instrumentation.Http/HttpClientInstrumentationOptions.cs b/src/OpenTelemetry.Instrumentation.Http/HttpClientInstrumentationOptions.cs index 2c5b478c8aa..a4ef77bdb53 100644 --- a/src/OpenTelemetry.Instrumentation.Http/HttpClientInstrumentationOptions.cs +++ b/src/OpenTelemetry.Instrumentation.Http/HttpClientInstrumentationOptions.cs @@ -33,12 +33,12 @@ public class HttpClientInstrumentationOptions /// collect telemetry about requests on a per request basis. /// /// - /// Notes: - /// - /// FilterHttpRequestMessage is only executed on .NET and .NET + /// FilterHttpRequestMessage is only executed on .NET and .NET /// Core runtimes. and on .NET and .NET Core are both implemented - /// using . + /// using . + /// Notes: + /// /// The return value for the filter function is interpreted as: /// /// If filter returns , the request is @@ -51,38 +51,32 @@ public class HttpClientInstrumentationOptions public Func FilterHttpRequestMessage { get; set; } /// - /// Gets or sets an action to enrich an Activity with . + /// Gets or sets an action to enrich an with . /// /// /// EnrichWithHttpRequestMessage is only executed on .NET and .NET /// Core runtimes. and on .NET and .NET Core are both implemented /// using . - /// : the activity being enriched. - /// object from which additional information can be extracted to enrich the activity. /// public Action EnrichWithHttpRequestMessage { get; set; } /// - /// Gets or sets an action to enrich an Activity with . + /// Gets or sets an action to enrich an with . /// /// /// EnrichWithHttpResponseMessage is only executed on .NET and .NET /// Core runtimes. and on .NET and .NET Core are both implemented /// using . - /// : the activity being enriched. - /// object from which additional information can be extracted to enrich the activity. /// public Action EnrichWithHttpResponseMessage { get; set; } /// - /// Gets or sets an action to enrich an Activity with . + /// Gets or sets an action to enrich an with . /// /// /// EnrichWithException is called for all runtimes. - /// : the activity being enriched. - /// object from which additional information can be extracted to enrich the activity. /// public Action EnrichWithException { get; set; } @@ -91,12 +85,12 @@ public class HttpClientInstrumentationOptions /// collect telemetry about requests on a per request basis. /// /// - /// Notes: - /// - /// FilterHttpWebRequest is only executed on .NET Framework + /// FilterHttpWebRequest is only executed on .NET Framework /// runtimes. and /// on .NET Framework are both implemented using . + /// cref="HttpWebRequest"/>. + /// Notes: + /// /// The return value for the filter function is interpreted as: /// /// If filter returns , the request is @@ -109,36 +103,37 @@ public class HttpClientInstrumentationOptions public Func FilterHttpWebRequest { get; set; } /// - /// Gets or sets an action to enrich an Activity with . + /// Gets or sets an action to enrich an with . /// /// /// EnrichWithHttpWebRequest is only executed on .NET Framework /// runtimes. and /// on .NET Framework are both implemented using . - /// : the activity being enriched. - /// object from which additional information can be extracted to enrich the activity. /// public Action EnrichWithHttpWebRequest { get; set; } /// - /// Gets or sets an action to enrich an Activity with . + /// Gets or sets an action to enrich an with . /// /// /// EnrichWithHttpWebResponse is only executed on .NET Framework /// runtimes. and /// on .NET Framework are both implemented using . - /// : the activity being enriched. - /// object from which additional information can be extracted to enrich the activity. /// public Action EnrichWithHttpWebResponse { get; set; } /// - /// Gets or sets a value indicating whether exception will be recorded as an or not. + /// Gets or sets a value indicating whether exception will be recorded + /// as an or not. Default value: . /// /// - /// See: . + /// RecordException is supported on all runtimes. + /// For specification details see: . /// public bool RecordException { get; set; } diff --git a/src/OpenTelemetry.Instrumentation.SqlClient/.publicApi/net462/PublicAPI.Unshipped.txt b/src/OpenTelemetry.Instrumentation.SqlClient/.publicApi/net462/PublicAPI.Unshipped.txt index 83aa554a2e0..4958bb839fd 100644 --- a/src/OpenTelemetry.Instrumentation.SqlClient/.publicApi/net462/PublicAPI.Unshipped.txt +++ b/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 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 +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 configureSqlClientInstrumentationOptions = null) -> OpenTelemetry.Trace.TracerProviderBuilder diff --git a/src/OpenTelemetry.Instrumentation.SqlClient/CHANGELOG.md b/src/OpenTelemetry.Instrumentation.SqlClient/CHANGELOG.md index 1e04989284c..b487184a716 100644 --- a/src/OpenTelemetry.Instrumentation.SqlClient/CHANGELOG.md +++ b/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. + ([#XXXX](https://github.com/open-telemetry/opentelemetry-dotnet/pull/XXXX)) + ## 1.0.0-rc9.9 Released 2022-Nov-07 diff --git a/src/OpenTelemetry.Instrumentation.SqlClient/Implementation/SqlEventSourceListener.netfx.cs b/src/OpenTelemetry.Instrumentation.SqlClient/Implementation/SqlEventSourceListener.netfx.cs index fde30c97575..c2065174776 100644 --- a/src/OpenTelemetry.Instrumentation.SqlClient/Implementation/SqlEventSourceListener.netfx.cs +++ b/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. // + #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. /// /// - /// 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". /// 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); } diff --git a/src/OpenTelemetry.Instrumentation.SqlClient/SqlClientInstrumentationOptions.cs b/src/OpenTelemetry.Instrumentation.SqlClient/SqlClientInstrumentationOptions.cs index b413952e6cf..6cfb81a9587 100644 --- a/src/OpenTelemetry.Instrumentation.SqlClient/SqlClientInstrumentationOptions.cs +++ b/src/OpenTelemetry.Instrumentation.SqlClient/SqlClientInstrumentationOptions.cs @@ -26,6 +26,9 @@ namespace OpenTelemetry.Instrumentation.SqlClient /// /// Options for . /// + /// + /// For help and examples see: . + /// public class SqlClientInstrumentationOptions { /* @@ -61,95 +64,121 @@ public class SqlClientInstrumentationOptions private static readonly ConcurrentDictionary ConnectionDetailCache = new(StringComparer.OrdinalIgnoreCase); - // .NET Framework implementation uses SqlEventSource from which we can't reliably distinguish - // StoredProcedures from regular Text sql commands. -#if NETFRAMEWORK - /// - /// Gets or sets a value indicating whether or not the should - /// add the text of the executed Sql commands as the tag. - /// Default value: False. + /// Gets or sets a value indicating whether or not the should add the names of commands as the tag. Default + /// value: . /// /// - /// - /// WARNING: potential sensitive data capture! If you use Microsoft.Data.SqlClient, the instrumentation will capture sqlCommand.CommandText - /// for and . Make sure your CommandText property never contains - /// any sensitive data for commands. - /// - /// - /// When using System.Data.SqlClient, the instrumentation will only capture sqlCommand.CommandText for commands. - /// + /// SetDbStatementForStoredProcedure is only supported on .NET + /// and .NET Core runtimes. /// - public bool SetDbStatement { get; set; } -#else - /// - /// Gets or sets a value indicating whether or not the should add the names of commands as the tag. Default value: True. - /// public bool SetDbStatementForStoredProcedure { get; set; } = true; /// - /// Gets or sets a value indicating whether or not the should add the text of commands as the tag. Default value: False. + /// Gets or sets a value indicating whether or not the should add the text of commands as + /// the tag. + /// Default value: . /// + /// + /// + /// WARNING: SetDbStatementForText will capture the raw + /// CommandText. Make sure your CommandText property never + /// contains any sensitive data. + /// + /// SetDbStatementForText is supported on all runtimes. + /// + /// On .NET and .NET Core SetDbStatementForText only applies to + /// SqlCommands with . + /// On .NET Framework SetDbStatementForText applies to all + /// SqlCommands regardless of . Use + /// SetDbStatementForText to capture Text, StoredProcedure, and all + /// other command text. + /// + /// + /// public bool SetDbStatementForText { get; set; } -#endif /// - /// Gets or sets a value indicating whether or not the should parse the DataSource on a SqlConnection into server name, instance name, and/or port connection-level attribute tags. Default value: False. + /// Gets or sets a value indicating whether or not the should parse the DataSource on a + /// SqlConnection into server name, instance name, and/or port + /// connection-level attribute tags. Default value: . /// /// - /// The default behavior is to set the SqlConnection DataSource as the tag. If enabled, SqlConnection DataSource will be parsed and the server name will be sent as the or tag, the instance name will be sent as the tag, and the port will be sent as the tag if it is not 1433 (the default port). + /// EnableConnectionLevelAttributes is supported on all + /// runtimes. + /// The default behavior is to set the SqlConnection DataSource as + /// the tag. If + /// enabled, SqlConnection DataSource will be parsed and the server name + /// will be sent as the or tag, the instance + /// name will be sent as the tag, and + /// the port will be sent as the tag if it is not + /// 1433 (the default port). /// public bool EnableConnectionLevelAttributes { get; set; } /// - /// Gets or sets an action to enrich an Activity. + /// Gets or sets an action to enrich an with the + /// raw SqlCommand object. /// /// - /// : the activity being enriched. - /// string: the name of the event. - /// object: the raw SqlCommand object from which additional information can be extracted to enrich the activity. - /// See also: example. + /// Enrich is only executed on .NET and .NET Core + /// runtimes. + /// The parameters passed to the enrich action are: + /// + /// The being enriched. + /// The name of the event. Currently only "OnCustom" is + /// used but more events may be added in the future. + /// The raw SqlCommand object from which additional + /// information can be extracted to enrich the . + /// /// - /// - /// - /// using var tracerProvider = Sdk.CreateTracerProviderBuilder() - /// .AddSqlClientInstrumentation(opt => opt.Enrich - /// = (activity, eventName, rawObject) => - /// { - /// if (eventName.Equals("OnCustom")) - /// { - /// if (rawObject is SqlCommand cmd) - /// { - /// activity.SetTag("db.commandTimeout", cmd.CommandTimeout); - /// } - /// } - /// }) - /// .Build(); - /// - /// public Action Enrich { get; set; } -#if !NETFRAMEWORK /// - /// Gets or sets a Filter function that determines whether or not to collect telemetry about a command - /// The Filter gets the SqlCommand, and should return a boolean. - /// If Filter returns true, the request is collected. - /// If Filter returns false or throw exception, the request is filtered out. + /// Gets or sets a filter function that determines whether or not to + /// collect telemetry about a command. /// /// - /// object: the raw SqlCommand object to interrogate for a decision on whether to trace or not. + /// Filter is only executed on .NET and .NET Core + /// runtimes. + /// Notes: + /// + /// The first parameter passed to the filter function is the raw + /// SqlCommand object for the command being executed. + /// The return value for the filter function is interpreted as: + /// + /// If filter returns , the command is + /// collected. + /// If filter returns or throws an + /// exception the command is NOT collected. + /// + /// /// - /// true to collect request, false to filter out. public Func Filter { get; set; } /// - /// Gets or sets a value indicating whether the exception will be recorded as ActivityEvent or not. Default value: False. + /// Gets or sets a value indicating whether the exception will be + /// recorded as or not. Default value: . /// /// - /// https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/semantic_conventions/exceptions.md. + /// RecordException is only supported on .NET and .NET Core + /// runtimes. + /// For specification details see: . /// public bool RecordException { get; set; } -#endif internal static SqlConnectionDetails ParseDataSource(string dataSource) { diff --git a/test/OpenTelemetry.Instrumentation.SqlClient.Tests/SqlClientTests.cs b/test/OpenTelemetry.Instrumentation.SqlClient.Tests/SqlClientTests.cs index 7164ba8d18e..bf054001459 100644 --- a/test/OpenTelemetry.Instrumentation.SqlClient.Tests/SqlClientTests.cs +++ b/test/OpenTelemetry.Instrumentation.SqlClient.Tests/SqlClientTests.cs @@ -15,13 +15,11 @@ // using System; -using System.Collections; using System.Collections.Generic; using System.Data; using System.Diagnostics; using System.Linq; using Microsoft.Data.SqlClient; -using Moq; using OpenTelemetry.Instrumentation.SqlClient.Implementation; using OpenTelemetry.Tests; using OpenTelemetry.Trace; @@ -67,9 +65,7 @@ public void SqlClient_BadArgs() [Trait("CategoryName", "SqlIntegrationTests")] [SkipUnlessEnvVarFoundTheory(SqlConnectionStringEnvVarName)] [InlineData(CommandType.Text, "select 1/1", false)] -#if !NETFRAMEWORK [InlineData(CommandType.Text, "select 1/1", false, true)] -#endif [InlineData(CommandType.Text, "select 1/0", false, false, true)] [InlineData(CommandType.Text, "select 1/0", false, false, true, false, false)] [InlineData(CommandType.Text, "select 1/0", false, false, true, true, false)] @@ -84,6 +80,12 @@ public void SuccessfulCommandTest( bool recordException = false, bool shouldEnrich = true) { +#if NETFRAMEWORK + // Disable things not available on netfx + recordException = false; + shouldEnrich = false; +#endif + var sampler = new TestSampler(); var activities = new List(); using var tracerProvider = Sdk.CreateTracerProviderBuilder() @@ -94,10 +96,10 @@ public void SuccessfulCommandTest( #if !NETFRAMEWORK options.SetDbStatementForStoredProcedure = captureStoredProcedureCommandName; options.SetDbStatementForText = captureTextCommandContent; - options.RecordException = recordException; #else - options.SetDbStatement = captureStoredProcedureCommandName; + options.SetDbStatementForText = captureStoredProcedureCommandName || captureTextCommandContent; #endif + options.RecordException = recordException; if (shouldEnrich) { options.Enrich = ActivityEnrichment; @@ -105,11 +107,6 @@ public void SuccessfulCommandTest( }) .Build(); -#if NETFRAMEWORK - // RecordException not available on netfx - recordException = false; -#endif - using SqlConnection sqlConnection = new SqlConnection(SqlConnectionString); sqlConnection.Open(); diff --git a/test/OpenTelemetry.Instrumentation.SqlClient.Tests/SqlEventSourceTests.netfx.cs b/test/OpenTelemetry.Instrumentation.SqlClient.Tests/SqlEventSourceTests.netfx.cs index 0db32cfdd4e..007b42c2340 100644 --- a/test/OpenTelemetry.Instrumentation.SqlClient.Tests/SqlEventSourceTests.netfx.cs +++ b/test/OpenTelemetry.Instrumentation.SqlClient.Tests/SqlEventSourceTests.netfx.cs @@ -13,13 +13,13 @@ // See the License for the specific language governing permissions and // limitations under the License. // + #if NETFRAMEWORK using System; using System.Data; using System.Data.SqlClient; using System.Diagnostics; using System.Diagnostics.Tracing; -using System.Linq; using System.Threading.Tasks; using Moq; using OpenTelemetry.Instrumentation.SqlClient.Implementation; @@ -55,7 +55,7 @@ public async Task SuccessfulCommandTest(CommandType commandType, string commandT .AddProcessor(activityProcessor.Object) .AddSqlClientInstrumentation(options => { - options.SetDbStatement = captureText; + options.SetDbStatementForText = captureText; }) .Build(); @@ -112,7 +112,7 @@ public void EventSourceFakeTests( .AddProcessor(activityProcessor.Object) .AddSqlClientInstrumentation(options => { - options.SetDbStatement = captureText; + options.SetDbStatementForText = captureText; options.EnableConnectionLevelAttributes = enableConnectionLevelAttributes; }) .Build(); From 6f9e9a9fab8ca26febe5c97cae5b4e421d9c2342 Mon Sep 17 00:00:00 2001 From: Mikel Blanchard Date: Mon, 14 Nov 2022 10:31:59 -0800 Subject: [PATCH 2/5] CHANGELOG patch. --- src/OpenTelemetry.Instrumentation.SqlClient/CHANGELOG.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/OpenTelemetry.Instrumentation.SqlClient/CHANGELOG.md b/src/OpenTelemetry.Instrumentation.SqlClient/CHANGELOG.md index b487184a716..2d4f9f681c7 100644 --- a/src/OpenTelemetry.Instrumentation.SqlClient/CHANGELOG.md +++ b/src/OpenTelemetry.Instrumentation.SqlClient/CHANGELOG.md @@ -6,7 +6,7 @@ `netstandard2.0` targets. `SetDbStatement` has been removed. Use `SetDbStatementForText` to capture command text and stored procedure names on .NET Framework. - ([#XXXX](https://github.com/open-telemetry/opentelemetry-dotnet/pull/XXXX)) + ([#3900](https://github.com/open-telemetry/opentelemetry-dotnet/pull/3900)) ## 1.0.0-rc9.9 From 455d91181005bb01161ac0fbc086ad27ab1081f7 Mon Sep 17 00:00:00 2001 From: Mikel Blanchard Date: Mon, 14 Nov 2022 12:42:52 -0800 Subject: [PATCH 3/5] Code review. --- src/OpenTelemetry.Instrumentation.SqlClient/CHANGELOG.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/src/OpenTelemetry.Instrumentation.SqlClient/CHANGELOG.md b/src/OpenTelemetry.Instrumentation.SqlClient/CHANGELOG.md index 2d4f9f681c7..aa7938f49d3 100644 --- a/src/OpenTelemetry.Instrumentation.SqlClient/CHANGELOG.md +++ b/src/OpenTelemetry.Instrumentation.SqlClient/CHANGELOG.md @@ -5,7 +5,9 @@ * **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. + .NET Framework. Note: `Enrich`, `Filter`, `RecordException`, and + `SetDbStatementForStoredProcedure` options are NOT supported on .NET + Framework. ([#3900](https://github.com/open-telemetry/opentelemetry-dotnet/pull/3900)) ## 1.0.0-rc9.9 From 99bab96f004ad94c892d5a76caf0613e84b5ff0b Mon Sep 17 00:00:00 2001 From: Mikel Blanchard Date: Mon, 14 Nov 2022 12:57:13 -0800 Subject: [PATCH 4/5] README updates. --- .../README.md | 66 ++++++++----------- 1 file changed, 28 insertions(+), 38 deletions(-) diff --git a/src/OpenTelemetry.Instrumentation.SqlClient/README.md b/src/OpenTelemetry.Instrumentation.SqlClient/README.md index e91b59ef056..2e9d1ce346e 100644 --- a/src/OpenTelemetry.Instrumentation.SqlClient/README.md +++ b/src/OpenTelemetry.Instrumentation.SqlClient/README.md @@ -78,7 +78,7 @@ be used to configure how the [`db.statement`](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/semantic_conventions/database.md#call-level-attributes) attribute is captured upon execution of a query. -#### .NET Core - SetDbStatementForStoredProcedure and SetDbStatementForText +#### .NET & .NET Core On .NET Core, two properties are available: `SetDbStatementForStoredProcedure` and `SetDbStatementForText`. These properties control capturing of @@ -115,25 +115,16 @@ using var tracerProvider = Sdk.CreateTracerProviderBuilder() .Build(); ``` -#### .NET Framework - SetDbStatement +#### .NET Framework -For .NET Framework, `SetDbStatementForStoredProcedure` and -`SetDbStatementForText` are not available. Instead, a single `SetDbStatement` -property should be used to control whether this instrumentation should set the +On .NET Framework, the `SetDbStatementForText` property controls whether or not +this instrumentation will set the [`db.statement`](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/semantic_conventions/database.md#call-level-attributes) -attribute to the text of the `SqlCommand` being executed. This could either be a -name of a stored procedure or a full text of a `CommandType.Text` query. - -On .NET Framework, unlike .NET Core, the instrumentation capabilities for both -[`Microsoft.Data.SqlClient`](https://www.nuget.org/packages/Microsoft.Data.SqlClient/) -and `System.Data.SqlClient` are limited: - -* [`Microsoft.Data.SqlClient`](https://www.nuget.org/packages/Microsoft.Data.SqlClient/) - always exposes both the stored procedure name and the full query text but - doesn't allow for more granular control to turn either on/off depending on - `CommandType`. -* `System.Data.SqlClient` only exposes stored procedure names and not the full - query text. +attribute to the text of the `SqlCommand` being executed. This could either be +the name of a stored procedure (when `CommandType.StoredProcedure` is used) or +the full text of a `CommandType.Text` query. `SetDbStatementForStoredProcedure` +is ignored because on .NET Framework there is no way to determine the type of +command being executed. Since `CommandType.Text` might contain sensitive data, all SQL capturing is _disabled_ by default to protect against accidentally sending full query text to @@ -144,12 +135,12 @@ using the options like below: ```csharp using var tracerProvider = Sdk.CreateTracerProviderBuilder() .AddSqlClientInstrumentation( - options => options.SetDbStatement = true) + options => options.SetDbStatementForText = true) .AddConsoleExporter() .Build(); ``` -## EnableConnectionLevelAttributes +### EnableConnectionLevelAttributes - All runtimes By default, `EnabledConnectionLevelAttributes` is disabled and this instrumentation sets the `peer.service` attribute to the @@ -170,13 +161,12 @@ using var tracerProvider = Sdk.CreateTracerProviderBuilder() .Build(); ``` -## Enrich +### Enrich - .NET & .NET Core only -This option, available on .NET Core only, allows one to enrich the activity with -additional information from the raw `SqlCommand` object. The `Enrich` action is -called only when `activity.IsAllDataRequested` is `true`. It contains the -activity itself (which can be enriched), the name of the event, and the actual -raw object. +This option can be used to enrich the activity with additional information from +the raw `SqlCommand` object. The `Enrich` action is called only when +`activity.IsAllDataRequested` is `true`. It contains the activity itself (which +can be enriched), the name of the event, and the actual raw object. Currently there is only one event name reported, "OnCustom". The actual object is `Microsoft.Data.SqlClient.SqlCommand` for `Microsoft.Data.SqlClient` and @@ -205,10 +195,10 @@ general extensibility point to add additional properties to any activity. The `Enrich` option is specific to this instrumentation, and is provided to get access to `SqlCommand` object. -### RecordException +### RecordException - .NET & .NET Core only -This option, available on .NET Core only, can be set to instruct the -instrumentation to record SqlExceptions as Activity +This option can be set to instruct the instrumentation to record SqlExceptions +as Activity [events](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/semantic_conventions/exceptions.md). The default value is `false` and can be changed by the code like below. @@ -221,16 +211,16 @@ using var tracerProvider = Sdk.CreateTracerProviderBuilder() .Build(); ``` -## Filter +### Filter - .NET & .NET Core only -This option allows to filter out activities based on the properties of the -`SqlCommand` object being instrumented using a `Func`. -The function receives an instance of the raw `SqlCommand` and should return -`true` if the telemetry is to be collected, and `false` if it should not. -The parameter of the Func delegate is of type `object` and needs to -be cast to the appropriate type of `SqlCommand`, either -`Microsoft.Data.SqlClient.SqlCommand` or `System.Data.SqlClient.SqlCommand`. -The example below filters out all commands that are not stored procedures. +This option can be used to filter out activities based on the properties of the +`SqlCommand` object being instrumented using a `Func`. The +function receives an instance of the raw `SqlCommand` and should return `true` +if the telemetry is to be collected, and `false` if it should not. The parameter +of the Func delegate is of type `object` and needs to be cast to the appropriate +type of `SqlCommand`, either `Microsoft.Data.SqlClient.SqlCommand` or +`System.Data.SqlClient.SqlCommand`. The example below filters out all commands +that are not stored procedures. ```csharp using var traceProvider = Sdk.CreateTracerProviderBuilder() From 259b6c1aa5504e93a184dbf26899ccf06a43d7b9 Mon Sep 17 00:00:00 2001 From: Mikel Blanchard Date: Mon, 14 Nov 2022 13:59:47 -0800 Subject: [PATCH 5/5] README tweaks. --- .../README.md | 34 ++++++++++++------- 1 file changed, 22 insertions(+), 12 deletions(-) diff --git a/src/OpenTelemetry.Instrumentation.SqlClient/README.md b/src/OpenTelemetry.Instrumentation.SqlClient/README.md index 2e9d1ce346e..7d20c1976ee 100644 --- a/src/OpenTelemetry.Instrumentation.SqlClient/README.md +++ b/src/OpenTelemetry.Instrumentation.SqlClient/README.md @@ -71,18 +71,20 @@ For an ASP.NET application, adding instrumentation is typically done in the This instrumentation can be configured to change the default behavior by using `SqlClientInstrumentationOptions`. -### Capturing 'db.statement' +### Capturing database statements -The `SqlClientInstrumentationOptions` class exposes several properties that can -be used to configure how the +The `SqlClientInstrumentationOptions` class exposes two properties that can be +used to configure how the [`db.statement`](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/semantic_conventions/database.md#call-level-attributes) -attribute is captured upon execution of a query. +attribute is captured upon execution of a query but the behavior depends on the +runtime used. -#### .NET & .NET Core +#### .NET and .NET Core -On .NET Core, two properties are available: `SetDbStatementForStoredProcedure` -and `SetDbStatementForText`. These properties control capturing of -`CommandType.StoredProcedure` and `CommandType.Text` respectively. +On .NET and .NET Core, two properties are available: +`SetDbStatementForStoredProcedure` and `SetDbStatementForText`. These properties +control capturing of `CommandType.StoredProcedure` and `CommandType.Text` +respectively. `SetDbStatementForStoredProcedure` is _true_ by default and will set [`db.statement`](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/semantic_conventions/database.md#call-level-attributes) @@ -140,7 +142,9 @@ using var tracerProvider = Sdk.CreateTracerProviderBuilder() .Build(); ``` -### EnableConnectionLevelAttributes - All runtimes +### EnableConnectionLevelAttributes + +**Note:** EnableConnectionLevelAttributes is supported on all runtimes. By default, `EnabledConnectionLevelAttributes` is disabled and this instrumentation sets the `peer.service` attribute to the @@ -161,7 +165,9 @@ using var tracerProvider = Sdk.CreateTracerProviderBuilder() .Build(); ``` -### Enrich - .NET & .NET Core only +### Enrich + +**Note:** Enrich is supported on .NET and .NET Core runtimes only. This option can be used to enrich the activity with additional information from the raw `SqlCommand` object. The `Enrich` action is called only when @@ -195,7 +201,9 @@ general extensibility point to add additional properties to any activity. The `Enrich` option is specific to this instrumentation, and is provided to get access to `SqlCommand` object. -### RecordException - .NET & .NET Core only +### RecordException + +**Note:** RecordException is supported on .NET and .NET Core runtimes only. This option can be set to instruct the instrumentation to record SqlExceptions as Activity @@ -211,7 +219,9 @@ using var tracerProvider = Sdk.CreateTracerProviderBuilder() .Build(); ``` -### Filter - .NET & .NET Core only +### Filter + +**Note:** Filter is supported on .NET and .NET Core runtimes only. This option can be used to filter out activities based on the properties of the `SqlCommand` object being instrumented using a `Func`. The