Adds .NET distributed tracing instrumentation.

src/FirebirdSql.Data.FirebirdClient/FirebirdClient/FbCommand.cs

@@ -20,11 +20,13 @@
 using System.ComponentModel;
 using System.Data;
 using System.Data.Common;
+using System.Diagnostics;
 using System.Text;
 using System.Threading;
 using System.Threading.Tasks;
 using FirebirdSql.Data.Common;
 using FirebirdSql.Data.Logging;
+using FirebirdSql.Data.Trace;
 using Microsoft.Extensions.Logging;
 
 namespace FirebirdSql.Data.FirebirdClient;
@@ -50,6 +52,7 @@ public sealed class FbCommand : DbCommand, IFbPreparedCommand, IDescriptorFiller
 	private int? _commandTimeout;
 	private int _fetchSize;
 	private Type[] _expectedColumnTypes;
+	private Activity _currentActivity;
 
 	#endregion
 
@@ -1064,6 +1067,13 @@ internal void Release()
 			_statement.Dispose2();
 			_statement = null;
 		}
+
+		if (_currentActivity != null)
+		{
+			// Do not set status to Ok: https://opentelemetry.io/docs/concepts/signals/traces/#span-status
+			_currentActivity.Dispose();
+			_currentActivity = null;
+		}
 	}
 	Task IFbPreparedCommand.ReleaseAsync(CancellationToken cancellationToken) => ReleaseAsync(cancellationToken);
 	internal async Task ReleaseAsync(CancellationToken cancellationToken = default)
@@ -1082,6 +1092,13 @@ internal async Task ReleaseAsync(CancellationToken cancellationToken = default)
 			await _statement.Dispose2Async(cancellationToken).ConfigureAwait(false);
 			_statement = null;
 		}
+
+		if (_currentActivity != null)
+		{
+			// Do not set status to Ok: https://opentelemetry.io/docs/concepts/signals/traces/#span-status
+			_currentActivity.Dispose();
+			_currentActivity = null;
+		}
 	}
 
 	void IFbPreparedCommand.TransactionCompleted() => TransactionCompleted();
@@ -1302,6 +1319,26 @@ private async ValueTask UpdateParameterValuesAsync(Descriptor descriptor, Cancel
 
 	#endregion
 
+	#region Tracing
+
+	private void TraceCommandStart()
+	{
+		Debug.Assert(_currentActivity == null);
+		if (FbActivitySource.Source.HasListeners())
+			_currentActivity = FbActivitySource.CommandStart(this);
+	}
+
+	private void TraceCommandException(Exception e)
+	{
+		if (_currentActivity != null)
+		{
+			FbActivitySource.CommandException(_currentActivity, e);
+			_currentActivity = null;
+		}
+	}
+
+	#endregion Tracing
+
 	#region Private Methods
 
 	private void Prepare(bool returnsSet)
@@ -1446,57 +1483,73 @@ private async Task PrepareAsync(bool returnsSet, CancellationToken cancellationT
 	private void ExecuteCommand(CommandBehavior behavior, bool returnsSet)
 	{
 		LogMessages.CommandExecution(Log, this);
+		TraceCommandStart();
+		try
+		{
+			Prepare(returnsSet);
 
-		Prepare(returnsSet);
+			if ((behavior & CommandBehavior.SequentialAccess) == CommandBehavior.SequentialAccess ||
+				(behavior & CommandBehavior.SingleResult) == CommandBehavior.SingleResult ||
+				(behavior & CommandBehavior.SingleRow) == CommandBehavior.SingleRow ||
+				(behavior & CommandBehavior.CloseConnection) == CommandBehavior.CloseConnection ||
+				behavior == CommandBehavior.Default)
+			{
+				// Set the fetch size
+				_statement.FetchSize = _fetchSize;
 
-		if ((behavior & CommandBehavior.SequentialAccess) == CommandBehavior.SequentialAccess ||
-			(behavior & CommandBehavior.SingleResult) == CommandBehavior.SingleResult ||
-			(behavior & CommandBehavior.SingleRow) == CommandBehavior.SingleRow ||
-			(behavior & CommandBehavior.CloseConnection) == CommandBehavior.CloseConnection ||
-			behavior == CommandBehavior.Default)
-		{
-			// Set the fetch size
-			_statement.FetchSize = _fetchSize;
+				// Set if it's needed the Records Affected information
+				_statement.ReturnRecordsAffected = _connection.ConnectionOptions.ReturnRecordsAffected;
 
-			// Set if it's needed the Records Affected information
-			_statement.ReturnRecordsAffected = _connection.ConnectionOptions.ReturnRecordsAffected;
+				// Validate input parameter count
+				if (_namedParameters.Count > 0 && !HasParameters)
+				{
+					throw FbException.Create("Must declare command parameters.");
+				}
 
-			// Validate input parameter count
-			if (_namedParameters.Count > 0 && !HasParameters)
-			{
-				throw FbException.Create("Must declare command parameters.");
+				// Execute
+				_statement.Execute(CommandTimeout * 1000, this);
 			}
-
-			// Execute
-			_statement.Execute(CommandTimeout * 1000, this);
+		}
+		catch (Exception e)
+		{
+			TraceCommandException(e);
+			throw;
 		}
 	}
 	private async Task ExecuteCommandAsync(CommandBehavior behavior, bool returnsSet, CancellationToken cancellationToken = default)
 	{
 		LogMessages.CommandExecution(Log, this);
+		TraceCommandStart();
+		try
+		{
+			await PrepareAsync(returnsSet, cancellationToken).ConfigureAwait(false);
 
-		await PrepareAsync(returnsSet, cancellationToken).ConfigureAwait(false);
+			if ((behavior & CommandBehavior.SequentialAccess) == CommandBehavior.SequentialAccess ||
+				(behavior & CommandBehavior.SingleResult) == CommandBehavior.SingleResult ||
+				(behavior & CommandBehavior.SingleRow) == CommandBehavior.SingleRow ||
+				(behavior & CommandBehavior.CloseConnection) == CommandBehavior.CloseConnection ||
+				behavior == CommandBehavior.Default)
+			{
+				// Set the fetch size
+				_statement.FetchSize = _fetchSize;
 
-		if ((behavior & CommandBehavior.SequentialAccess) == CommandBehavior.SequentialAccess ||
-			(behavior & CommandBehavior.SingleResult) == CommandBehavior.SingleResult ||
-			(behavior & CommandBehavior.SingleRow) == CommandBehavior.SingleRow ||
-			(behavior & CommandBehavior.CloseConnection) == CommandBehavior.CloseConnection ||
-			behavior == CommandBehavior.Default)
-		{
-			// Set the fetch size
-			_statement.FetchSize = _fetchSize;
+				// Set if it's needed the Records Affected information
+				_statement.ReturnRecordsAffected = _connection.ConnectionOptions.ReturnRecordsAffected;
 
-			// Set if it's needed the Records Affected information
-			_statement.ReturnRecordsAffected = _connection.ConnectionOptions.ReturnRecordsAffected;
+				// Validate input parameter count
+				if (_namedParameters.Count > 0 && !HasParameters)
+				{
+					throw FbException.Create("Must declare command parameters.");
+				}
 
-			// Validate input parameter count
-			if (_namedParameters.Count > 0 && !HasParameters)
-			{
-				throw FbException.Create("Must declare command parameters.");
+				// Execute
+				await _statement.ExecuteAsync(CommandTimeout * 1000, this, cancellationToken).ConfigureAwait(false);
 			}
-
-			// Execute
-			await _statement.ExecuteAsync(CommandTimeout * 1000, this, cancellationToken).ConfigureAwait(false);
+		}
+		catch (Exception e)
+		{
+			TraceCommandException(e);
+			throw;
 		}
 	}
 

src/FirebirdSql.Data.FirebirdClient/FirebirdSql.Data.FirebirdClient.csproj

@@ -52,6 +52,7 @@
 	    <PrivateAssets>all</PrivateAssets>
 	    <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
 	  </PackageReference>
+	  <PackageReference Include="System.Diagnostics.DiagnosticSource" Version="8.0.1" />
 	</ItemGroup>
 	<Import Project="..\FirebirdSql.Data.External\FirebirdSql.Data.External.projitems" Label="Shared" />
 </Project>

src/FirebirdSql.Data.FirebirdClient/Trace/FbActivitySource.cs

@@ -0,0 +1,137 @@
+using System;
+using System.ComponentModel;
+using System.Data;
+using System.Diagnostics;
+using FirebirdSql.Data.FirebirdClient;
+
+namespace FirebirdSql.Data.Trace
+{
+	internal static class FbActivitySource
+	{
+		internal static readonly ActivitySource Source = new("FirebirdSql.Data", "1.0.0");
+
+		internal static Activity CommandStart(FbCommand command)
+		{
+			// Reference: https://github.com/open-telemetry/semantic-conventions/blob/main/docs/database/database-spans.md
+			var dbName = command.Connection.Database;
+
+			string dbOperationName = null;
+			string dbCollectionName = null;
+			string activityName;
+
+			switch (command.CommandType)
+			{
+				case CommandType.StoredProcedure:
+					dbOperationName = "EXECUTE PROCEDURE";
+					activityName = $"{dbOperationName} {command.CommandText}";
+					break;
+
+				case CommandType.TableDirect:
+					dbOperationName = "SELECT";
+					dbCollectionName = command.CommandText;
+					activityName = $"{dbOperationName} {dbCollectionName}";
+					break;
+
+				case CommandType.Text:
+					activityName = dbName;
+					break;
+
+				default:
+					throw new InvalidEnumArgumentException($"Invalid value for 'System.Data.CommandType' ({(int)command.CommandType}).");
+			}
+
+			var activity = Source.StartActivity(activityName, ActivityKind.Client);
+			if (activity.IsAllDataRequested)
+			{
+				activity.SetTag("db.system", "firebird");
+
+				if (dbCollectionName != null)
+				{
+					activity.SetTag("db.collection.name", dbCollectionName);
+				}
+
+				// db.namespace
+
+				if (dbOperationName != null)
+				{
+					activity.SetTag("db.operation.name", dbOperationName);
+				}
+
+				// db.response.status_code
+
+				// error.type (handled by RecordException)
+
+				// server.port
+
+				// db.operation.batch.size
+
+				// db.query_summary
+
+				activity.SetTag("db.query.text", command.CommandText);
+
+				// network.peer.address
+
+				// network.peer.port
+
+				if (command.Connection.DataSource != null)
+				{
+					activity.SetTag("server.address", command.Connection.DataSource);
+				}
+
+				foreach (FbParameter p in command.Parameters)
+				{
+					var name = p.ParameterName;
+					var value = NormalizeDbNull(p.InternalValue);
+					activity.SetTag($"db.query.parameter.{name}", value);
+
+				}
+
+				// Only for explicit transactions.
+				if (command.Transaction != null)
+				{
+					FbTransactionInfo fbInfo = new FbTransactionInfo(command.Transaction);
+
+					var transactionId = fbInfo.GetTransactionId();
+					activity.SetTag($"db.transaction_id", transactionId);
+
+					// TODO: Firebird 4+ only (or remove?)
+					/*
+					var snapshotId = fbInfo.GetTransactionSnapshotNumber();
+					if (snapshotId != 0)
+					{
+						activity.SetTag($"db.snapshot_id", snapshotId);
+					}
+					*/
+				}
+			}
+
+			return activity;
+		}
+
+		internal static void CommandException(Activity activity, Exception exception, bool escaped = true)
+		{
+			// Reference: https://github.com/open-telemetry/semantic-conventions/blob/main/docs/exceptions/exceptions-spans.md
+			activity.AddEvent(
+				new("exception", tags: new()
+				{
+					{ "exception.message", exception.Message },
+					{ "exception.type", exception.GetType().FullName },
+					{ "exception.escaped", escaped },
+					{ "exception.stacktrace", exception.ToString() },
+				})
+			);
+
+			string errorDescription = exception is FbException fbException
+				? fbException.SQLSTATE
+				: exception.Message;
+
+			activity.SetStatus(ActivityStatusCode.Error, errorDescription);
+			activity.Dispose();
+		}
+
+		private static object NormalizeDbNull(object value) =>
+			value == DBNull.Value || value == null
+				? null
+				: value;
+	}
+}