[SqlClient] Support query parameter attributes

Add support for `db.query.parameter.<key>` for SqlClient and EFCore via new opt-in `SetDbQueryParameters` option.

Resolves #2241.

src/OpenTelemetry.Instrumentation.EntityFrameworkCore/.publicApi/PublicAPI.Unshipped.txt

@@ -2,6 +2,8 @@ OpenTelemetry.Instrumentation.EntityFrameworkCore.EntityFrameworkInstrumentation
 OpenTelemetry.Instrumentation.EntityFrameworkCore.EntityFrameworkInstrumentationOptions.EntityFrameworkInstrumentationOptions() -> void
 OpenTelemetry.Instrumentation.EntityFrameworkCore.EntityFrameworkInstrumentationOptions.Filter.get -> System.Func<string?, System.Data.IDbCommand!, bool>?
 OpenTelemetry.Instrumentation.EntityFrameworkCore.EntityFrameworkInstrumentationOptions.Filter.set -> void
+OpenTelemetry.Instrumentation.EntityFrameworkCore.EntityFrameworkInstrumentationOptions.SetDbQueryParameters.get -> bool
+OpenTelemetry.Instrumentation.EntityFrameworkCore.EntityFrameworkInstrumentationOptions.SetDbQueryParameters.set -> void
 OpenTelemetry.Instrumentation.EntityFrameworkCore.EntityFrameworkInstrumentationOptions.SetDbStatementForStoredProcedure.get -> bool
 OpenTelemetry.Instrumentation.EntityFrameworkCore.EntityFrameworkInstrumentationOptions.SetDbStatementForStoredProcedure.set -> void
 OpenTelemetry.Instrumentation.EntityFrameworkCore.EntityFrameworkInstrumentationOptions.SetDbStatementForText.get -> bool

src/OpenTelemetry.Instrumentation.EntityFrameworkCore/CHANGELOG.md

@@ -15,6 +15,9 @@
 * Extend `db.system.name` values to identity additional providers related to Couchbase,
   DB2, MongoDB, MySQL, Oracle, PostgreSQL and SQLite.
   ([#3025](https://github.com/open-telemetry/opentelemetry-dotnet-contrib/pull/3025))
+* Add `db.query.parameter.<key>` attribute(s) to query spans if opted into using
+  the `SetDbQueryParameters` option.
+  ([#3015](https://github.com/open-telemetry/opentelemetry-dotnet-contrib/pull/3015))
 
 ## 1.12.0-beta.2
 

src/OpenTelemetry.Instrumentation.EntityFrameworkCore/EntityFrameworkInstrumentationOptions.cs

@@ -68,6 +68,20 @@ internal EntityFrameworkInstrumentationOptions(IConfiguration configuration)
     /// </remarks>
     public Func<string?, IDbCommand, bool>? Filter { get; set; }
 
+    /// <summary>
+    /// Gets or sets a value indicating whether or not the <see cref="EntityFrameworkInstrumentation"/>
+    /// should add the names and values of query parameters as the <c>db.query.parameter.{key}</c> tag.
+    /// Default value: <see langword="false"/>.
+    /// </summary>
+    /// <remarks>
+    /// <para>
+    /// <b>WARNING: SetDbQueryParameters will capture the raw
+    /// <c>Value</c>. Make sure your query parameters never
+    /// contain any sensitive data.</b>
+    /// </para>
+    /// </remarks>
+    public bool SetDbQueryParameters { get; set; }
+
     /// <summary>
     /// Gets or sets a value indicating whether the old database attributes should be emitted.
     /// </summary>

src/OpenTelemetry.Instrumentation.EntityFrameworkCore/Implementation/EntityFrameworkDiagnosticListener.cs

@@ -125,9 +125,17 @@ public override void OnEventWritten(string name, object? payload)
                         return;
                     }
 
+                    object? command = null;
+
+                    if (this.options.SetDbQueryParameters)
+                    {
+                        command = this.commandFetcher.Fetch(payload);
+                        SqlParameterProcessor.AddQueryParameters(activity, command);
+                    }
+
                     if (activity.IsAllDataRequested)
                     {
-                        var command = this.commandFetcher.Fetch(payload);
+                        command ??= this.commandFetcher.Fetch(payload);
 
                         try
                         {

src/OpenTelemetry.Instrumentation.EntityFrameworkCore/OpenTelemetry.Instrumentation.EntityFrameworkCore.csproj

@@ -32,6 +32,7 @@
     <Compile Include="$(RepoRoot)\src\Shared\PropertyFetcher.cs" Link="Includes\PropertyFetcher.cs" />
     <Compile Include="$(RepoRoot)\src\Shared\SemanticConventions.cs" Link="Includes\SemanticConventions.cs" />
     <Compile Include="$(RepoRoot)\src\Shared\SqlConnectionDetails.cs" Link="Includes\SqlConnectionDetails.cs" />
+    <Compile Include="$(RepoRoot)\src\Shared\SqlParameterProcessor.cs" Link="Includes\SqlParameterProcessor.cs" />
   </ItemGroup>
 
 </Project>

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

@@ -6,6 +6,8 @@ OpenTelemetry.Instrumentation.SqlClient.SqlClientTraceInstrumentationOptions.Fil
 OpenTelemetry.Instrumentation.SqlClient.SqlClientTraceInstrumentationOptions.Filter.set -> void
 OpenTelemetry.Instrumentation.SqlClient.SqlClientTraceInstrumentationOptions.RecordException.get -> bool
 OpenTelemetry.Instrumentation.SqlClient.SqlClientTraceInstrumentationOptions.RecordException.set -> void
+OpenTelemetry.Instrumentation.SqlClient.SqlClientTraceInstrumentationOptions.SetDbQueryParameters.get -> bool
+OpenTelemetry.Instrumentation.SqlClient.SqlClientTraceInstrumentationOptions.SetDbQueryParameters.set -> void
 OpenTelemetry.Instrumentation.SqlClient.SqlClientTraceInstrumentationOptions.SetDbStatementForText.get -> bool
 OpenTelemetry.Instrumentation.SqlClient.SqlClientTraceInstrumentationOptions.SetDbStatementForText.set -> void
 OpenTelemetry.Instrumentation.SqlClient.SqlClientTraceInstrumentationOptions.SqlClientTraceInstrumentationOptions() -> void

src/OpenTelemetry.Instrumentation.SqlClient/CHANGELOG.md

@@ -25,6 +25,10 @@ Released 2025-Jul-15
     (see [SET CONTEXT_INFO](https://learn.microsoft.com/en-us/sql/t-sql/statements/set-context-info-transact-sql?view=sql-server-ver16)).
     Note that this option incurs an additional round-trip to the database.
 
+* Add `db.query.parameter.<key>` attribute(s) to query spans if opted into using
+  the `SetDbQueryParameters` option. Not supported on .NET Framework.
+  ([#3015](https://github.com/open-telemetry/opentelemetry-dotnet-contrib/pull/3015))
+
 ## 1.12.0-beta.1
 
 Released 2025-May-06

src/OpenTelemetry.Instrumentation.SqlClient/Implementation/SqlClientDiagnosticListener.cs

@@ -121,6 +121,11 @@ public override void OnEventWritten(string name, object? payload)
                     }
 #endif
 
+                    if (options.SetDbQueryParameters)
+                    {
+                        SqlParameterProcessor.AddQueryParameters(activity, command);
+                    }
+
                     if (activity.IsAllDataRequested)
                     {
                         try

src/OpenTelemetry.Instrumentation.SqlClient/OpenTelemetry.Instrumentation.SqlClient.csproj

@@ -28,12 +28,13 @@
     <Compile Include="$(RepoRoot)\src\Shared\PropertyFetcher.cs" Link="Includes\PropertyFetcher.cs" />
     <Compile Include="$(RepoRoot)\src\Shared\SemanticConventions.cs" Link="Includes\SemanticConventions.cs" />
     <Compile Include="$(RepoRoot)\src\Shared\SqlConnectionDetails.cs" Link="Includes\SqlConnectionDetails.cs" />
+    <Compile Include="$(RepoRoot)\src\Shared\SqlParameterProcessor.cs" Link="Includes\SqlParameterProcessor.cs" />
     <Compile Include="$(RepoRoot)\src\Shared\SqlProcessor.cs" Link="Includes\SqlProcessor.cs" />
     <Compile Include="$(RepoRoot)\src\Shared\SqlStatementInfo.cs" Link="Includes\SqlStatementInfo.cs" />
   </ItemGroup>
 
   <ItemGroup>
-    <PackageReference Include="Microsoft.Extensions.Configuration" Version="$(MicrosoftExtensionsConfigurationPkgVer)"/>
+    <PackageReference Include="Microsoft.Extensions.Configuration" Version="$(MicrosoftExtensionsConfigurationPkgVer)" />
     <PackageReference Include="Microsoft.Extensions.Options" Version="$(MicrosoftExtensionsOptionsPkgVer)" />
     <PackageReference Include="OpenTelemetry.Api.ProviderBuilderExtensions" Version="$(OpenTelemetryCoreLatestVersion)" />
   </ItemGroup>

src/OpenTelemetry.Instrumentation.SqlClient/SqlClientTraceInstrumentationOptions.cs

@@ -50,9 +50,8 @@ internal SqlClientTraceInstrumentationOptions(IConfiguration configuration)
     }
 
     /// <summary>
-    /// Gets or sets a value indicating whether or not the <see
-    /// cref="SqlClientInstrumentation"/> should add the text of commands as
-    /// the <see cref="SemanticConventions.AttributeDbStatement"/> tag.
+    /// Gets or sets a value indicating whether or not the <see cref="SqlClientInstrumentation"/>
+    /// should add the text of commands as the <see cref="SemanticConventions.AttributeDbStatement"/> tag.
     /// Default value: <see langword="false"/>.
     /// </summary>
     /// <remarks>
@@ -134,6 +133,23 @@ internal SqlClientTraceInstrumentationOptions(IConfiguration configuration)
     /// </remarks>
     public bool RecordException { get; set; }
 
+    /// <summary>
+    /// Gets or sets a value indicating whether or not the <see cref="SqlClientInstrumentation"/>
+    /// should add the names and values of query parameters as the <c>db.query.parameter.{key}</c> tag.
+    /// Default value: <see langword="false"/>.
+    /// </summary>
+    /// <remarks>
+    /// <para>
+    /// <b>WARNING: SetDbQueryParameters will capture the raw
+    /// <c>Value</c>. Make sure your query parameters never
+    /// contain any sensitive data.</b>
+    /// </para>
+    /// <para>
+    /// <b>SetDbQueryParameters is only supported on .NET and .NET Core runtimes.</b>
+    /// </para>
+    /// </remarks>
+    public bool SetDbQueryParameters { get; set; }
+
     /// <summary>
     /// Gets or sets a value indicating whether the old database attributes should be emitted.
     /// </summary>

src/Shared/SqlParameterProcessor.cs

@@ -0,0 +1,36 @@
+// Copyright The OpenTelemetry Authors
+// SPDX-License-Identifier: Apache-2.0
+
+using System.Data;
+using System.Diagnostics;
+using System.Globalization;
+
+namespace OpenTelemetry.Instrumentation;
+
+internal static class SqlParameterProcessor
+{
+    public static void AddQueryParameters(Activity activity, object? command)
+    {
+        if (command is not IDbCommand { Parameters.Count: > 0 } dbCommand)
+        {
+            return;
+        }
+
+        int index = 0;
+
+        foreach (var parameter in dbCommand.Parameters)
+        {
+            if (parameter is IDbDataParameter dbDataParameter)
+            {
+                // If a query parameter has no name and instead is referenced only by index, then {key} SHOULD be the 0-based index.
+                var key = string.IsNullOrEmpty(dbDataParameter.ParameterName)
+                    ? index.ToString(CultureInfo.InvariantCulture)
+                    : dbDataParameter.ParameterName;
+
+                activity.SetTag($"db.query.parameter.{key}", dbDataParameter.Value);
+            }
+
+            index++;
+        }
+    }
+}

test/OpenTelemetry.Contrib.Shared.Tests/OpenTelemetry.Contrib.Shared.Tests.csproj

@@ -25,6 +25,7 @@
     <Compile Include="$(RepoRoot)\src\Shared\RequestDataHelper.cs" Link="Includes\RequestDataHelper.cs" />
     <Compile Include="$(RepoRoot)\src\Shared\SemanticConventions.cs" Link="Includes\SemanticConventions.cs" />
     <Compile Include="$(RepoRoot)\src\Shared\SqlConnectionDetails.cs" Link="Includes\SqlConnectionDetails.cs" />
+    <Compile Include="$(RepoRoot)\src\Shared\SqlParameterProcessor.cs" Link="Includes\SqlParameterProcessor.cs" />
     <Compile Include="$(RepoRoot)\src\Shared\SqlProcessor.cs" Link="Includes\SqlProcessor.cs" />
     <Compile Include="$(RepoRoot)\src\Shared\SqlStatementInfo.cs" Link="Includes\SqlStatementInfo.cs" />
   </ItemGroup>