[SqlClient] Support query parameter attributes

martincostello · martincostello · commit b2c48e4ab59f · 2025-08-26T12:45:03.000+01:00
Add support for `db.query.parameter.<key>` for SqlClient and EFCore via new opt-in `SetDbQueryParameters` option. Resolves #2241.
diff --git a/src/OpenTelemetry.Instrumentation.EntityFrameworkCore/.publicApi/PublicAPI.Unshipped.txt b/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
diff --git a/src/OpenTelemetry.Instrumentation.EntityFrameworkCore/CHANGELOG.md b/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
 
diff --git a/src/OpenTelemetry.Instrumentation.EntityFrameworkCore/EntityFrameworkInstrumentationOptions.cs b/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>
diff --git a/src/OpenTelemetry.Instrumentation.EntityFrameworkCore/Implementation/EntityFrameworkDiagnosticListener.cs b/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
                         {
diff --git a/src/OpenTelemetry.Instrumentation.EntityFrameworkCore/OpenTelemetry.Instrumentation.EntityFrameworkCore.csproj b/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>
diff --git a/src/OpenTelemetry.Instrumentation.SqlClient/.publicApi/PublicAPI.Unshipped.txt b/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
diff --git a/src/OpenTelemetry.Instrumentation.SqlClient/CHANGELOG.md b/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
diff --git a/src/OpenTelemetry.Instrumentation.SqlClient/Implementation/SqlClientDiagnosticListener.cs b/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
diff --git a/src/OpenTelemetry.Instrumentation.SqlClient/OpenTelemetry.Instrumentation.SqlClient.csproj b/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>
diff --git a/src/OpenTelemetry.Instrumentation.SqlClient/SqlClientTraceInstrumentationOptions.cs b/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>
diff --git a/src/Shared/SqlParameterProcessor.cs b/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++;
+        }
+    }
+}
diff --git a/test/OpenTelemetry.Contrib.Shared.Tests/OpenTelemetry.Contrib.Shared.Tests.csproj b/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>
diff --git a/test/OpenTelemetry.Contrib.Shared.Tests/SqlParameterProcessorTests.cs b/test/OpenTelemetry.Contrib.Shared.Tests/SqlParameterProcessorTests.cs
diff --git a/test/OpenTelemetry.Instrumentation.EntityFrameworkCore.Tests/EntityFrameworkIntegrationTests.cs b/test/OpenTelemetry.Instrumentation.EntityFrameworkCore.Tests/EntityFrameworkIntegrationTests.cs
diff --git a/test/OpenTelemetry.Instrumentation.SqlClient.Tests/OpenTelemetry.Instrumentation.SqlClient.Tests.csproj b/test/OpenTelemetry.Instrumentation.SqlClient.Tests/OpenTelemetry.Instrumentation.SqlClient.Tests.csproj
diff --git a/test/OpenTelemetry.Instrumentation.SqlClient.Tests/SqlClientIntegrationTests.cs b/test/OpenTelemetry.Instrumentation.SqlClient.Tests/SqlClientIntegrationTests.cs

Original file line number	Diff line number	Diff line change
`@@ -125,9 +125,17 @@ public override void OnEventWritten(string name, object? payload)`
`125`	`125`	`return;`
`126`	`126`	`}`
`127`	`127`
	`128`	`+ object? command = null;`
	`129`	`+`
	`130`	`+ if (this.options.SetDbQueryParameters)`
	`131`	`+ {`
	`132`	`+ command = this.commandFetcher.Fetch(payload);`
	`133`	`+ SqlParameterProcessor.AddQueryParameters(activity, command);`
	`134`	`+ }`
	`135`	`+`
`128`	`136`	`if (activity.IsAllDataRequested)`
`129`	`137`	`{`
`130`		`- var command = this.commandFetcher.Fetch(payload);`
	`138`	`+ command ??= this.commandFetcher.Fetch(payload);`
`131`	`139`
`132`	`140`	`try`
`133`	`141`	`{`
Original file line number	Diff line number	Diff line change
`@@ -121,6 +121,11 @@ public override void OnEventWritten(string name, object? payload)`
`121`	`121`	`}`
`122`	`122`	`#endif`
`123`	`123`
	`124`	`+ if (options.SetDbQueryParameters)`
	`125`	`+ {`
	`126`	`+ SqlParameterProcessor.AddQueryParameters(activity, command);`
	`127`	`+ }`
	`128`	`+`
`124`	`129`	`if (activity.IsAllDataRequested)`
`125`	`130`	`{`
`126`	`131`	`try`