Adds .NET distributed tracing instrumentation & metrics.

docs/otel.md

@@ -0,0 +1,80 @@
+# OpenTelemetry Integration
+
+The Firebird ADO.NET provider includes built-in support for [OpenTelemetry](https://opentelemetry.io/) distributed tracing and metrics using the native .NET `System.Diagnostics` APIs. No dependency on the OpenTelemetry SDK is required in the provider itself — your application opts in by configuring the appropriate listeners.
+
+## Distributed Tracing
+
+The provider emits `Activity` spans for database command execution using `System.Diagnostics.ActivitySource`.
+
+### Enabling Traces
+
+```csharp
+using OpenTelemetry.Trace;
+
+var tracerProvider = Sdk.CreateTracerProviderBuilder()
+    .AddSource(FirebirdSql.Data.FirebirdClient.FbTelemetry.ActivitySourceName)
+    .AddConsoleExporter() // or any other exporter
+    .Build();
+```
+
+The `ActivitySource` name is `"FirebirdSql.Data"`, also available as the constant `FbTelemetry.ActivitySourceName`.
+
+### Span Attributes
+
+Spans follow the [OTel Database Client Semantic Conventions](https://opentelemetry.io/docs/specs/semconv/database/database-spans/):
+
+| Attribute | Description |
+|-----------|-------------|
+| `db.system.name` | Always `"firebirdsql"` |
+| `db.namespace` | The database name from the connection |
+| `db.operation.name` | The SQL verb (`SELECT`, `INSERT`, etc.) or `EXECUTE PROCEDURE` |
+| `db.collection.name` | The table name (for `TableDirect` commands) |
+| `db.stored_procedure.name` | The stored procedure name (for `StoredProcedure` commands) |
+| `db.query.summary` | A low-cardinality summary of the operation |
+| `db.query.text` | The full SQL text (**opt-in**, see below) |
+| `db.query.parameter.*` | Parameter values (**opt-in**, see below) |
+| `server.address` | The database server hostname |
+| `server.port` | The database server port (only when non-default, i.e. != 3050) |
+| `error.type` | The SQLSTATE code (for `FbException`) or exception type name |
+
+### Opt-In Sensitive Attributes
+
+By default, `db.query.text` and `db.query.parameter.*` are **not** collected, as they may contain sensitive data. Enable them explicitly:
+
+```csharp
+using FirebirdSql.Data.Logging;
+
+// Enable SQL text in traces
+FbLogManager.EnableQueryTextTracing();
+
+// Enable parameter values in traces (and logs)
+FbLogManager.EnableParameterLogging();
+```
+
+## Metrics
+
+The provider emits metrics via `System.Diagnostics.Metrics.Meter`.
+
+### Enabling Metrics
+
+```csharp
+using OpenTelemetry.Metrics;
+
+var meterProvider = Sdk.CreateMeterProviderBuilder()
+    .AddMeter(FirebirdSql.Data.FirebirdClient.FbTelemetry.MeterName)
+    .AddConsoleExporter() // or any other exporter
+    .Build();
+```
+
+The `Meter` name is `"FirebirdSql.Data"`, also available as the constant `FbTelemetry.MeterName`.
+
+### Available Metrics
+
+Metrics follow the [OTel Database Client Metrics Semantic Conventions](https://opentelemetry.io/docs/specs/semconv/database/database-metrics/):
+
+| Metric | Type | Unit | Description |
+|--------|------|------|-------------|
+| `db.client.operation.duration` | Histogram | `s` | Duration of database client operations |
+| `db.client.connection.create_time` | Histogram | `s` | Time to create a new connection |
+| `db.client.connection.count` | ObservableUpDownCounter | `{connection}` | Current connection count by state (`idle`/`used`) |
+| `db.client.connection.max` | ObservableUpDownCounter | `{connection}` | Maximum number of open connections allowed |

src/FirebirdSql.Data.FirebirdClient.Tests/FbTransactionTests.cs

@@ -139,4 +139,22 @@ public async Task SnapshotAtNumber()
 			}
 		}
 	}
+
+	[Test]
+	public async Task CanGetTransactionId()
+	{
+		if (!EnsureServerVersionAtLeast(new Version(2, 5, 0, 0)))
+			return;
+
+		await using (var transaction1 = await Connection.BeginTransactionAsync())
+		{
+			var idFromInfo = await new FbTransactionInfo(transaction1).GetTransactionIdAsync();
+			Assert.NotZero(idFromInfo);
+
+			var command = new FbCommand("SELECT current_transaction FROM rdb$database", Connection, transaction1);
+			var idFromSql = await command.ExecuteScalarAsync();
+
+			Assert.AreEqual(idFromInfo, idFromSql);
+		}
+	}
 }

src/FirebirdSql.Data.FirebirdClient/Common/IscHelper.cs

@@ -206,6 +206,10 @@ public static List<object> ParseTransactionInfo(byte[] buffer, Charset charset)
 				case IscCodes.isc_info_error:
 					throw FbException.Create("Received error response.");
 
+				case IscCodes.isc_info_tra_id:
+					info.Add(VaxInteger(buffer, pos, length));
+					break;
+
 				case IscCodes.fb_info_tra_snapshot_number:
 					info.Add(VaxInteger(buffer, pos, length));
 					break;

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

@@ -20,11 +20,14 @@
 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.Metrics;
+using FirebirdSql.Data.Trace;
 using Microsoft.Extensions.Logging;
 
 namespace FirebirdSql.Data.FirebirdClient;
@@ -50,6 +53,8 @@ public sealed class FbCommand : DbCommand, IFbPreparedCommand, IDescriptorFiller
 	private int? _commandTimeout;
 	private int _fetchSize;
 	private Type[] _expectedColumnTypes;
+	private Activity _currentActivity;
+	private long _startedAtTicks;
 
 	#endregion
 
@@ -1064,7 +1069,10 @@ internal void Release()
 			_statement.Dispose2();
 			_statement = null;
 		}
+
+		TraceCommandStop();
 	}
+
 	Task IFbPreparedCommand.ReleaseAsync(CancellationToken cancellationToken) => ReleaseAsync(cancellationToken);
 	internal async Task ReleaseAsync(CancellationToken cancellationToken = default)
 	{
@@ -1082,6 +1090,8 @@ internal async Task ReleaseAsync(CancellationToken cancellationToken = default)
 			await _statement.Dispose2Async(cancellationToken).ConfigureAwait(false);
 			_statement = null;
 		}
+
+		TraceCommandStop();
 	}
 
 	void IFbPreparedCommand.TransactionCompleted() => TransactionCompleted();
@@ -1302,6 +1312,48 @@ 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);
+
+		_startedAtTicks = FbMetricsStore.CommandStart();
+	}
+
+	private void TraceCommandStop()
+	{
+		Debug.Assert(_startedAtTicks > 0 || _currentActivity == null, "TraceCommandStop called without TraceCommandStart");
+
+		if (_currentActivity != null)
+		{
+			// Do not set status to Ok: https://opentelemetry.io/docs/concepts/signals/traces/#span-status
+			_currentActivity.Dispose();
+			_currentActivity = null;
+		}
+
+		FbMetricsStore.CommandStop(_startedAtTicks, Connection);
+		_startedAtTicks = 0;
+	}
+
+	private void TraceCommandException(Exception e)
+	{
+		Debug.Assert(_startedAtTicks > 0 || _currentActivity == null, "TraceCommandException called without TraceCommandStart");
+
+		if (_currentActivity != null)
+		{
+			FbActivitySource.CommandException(_currentActivity, e);
+			_currentActivity = null;
+		}
+
+		FbMetricsStore.CommandStop(_startedAtTicks, Connection);
+		_startedAtTicks = 0;
+	}
+
+	#endregion Tracing
+
 	#region Private Methods
 
 	private void Prepare(bool returnsSet)
@@ -1446,57 +1498,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/FirebirdClient/FbConnection.cs

@@ -16,13 +16,15 @@
 //$Authors = Carlos Guzman Alvarez, Jiri Cincura (jiri@cincura.net)
 
 using System;
+using System.Collections.Generic;
 using System.ComponentModel;
 using System.Data;
 using System.Data.Common;
 using System.Threading;
 using System.Threading.Tasks;
 using FirebirdSql.Data.Common;
 using FirebirdSql.Data.Logging;
+using FirebirdSql.Data.Metrics;
 using Microsoft.Extensions.Logging;
 
 namespace FirebirdSql.Data.FirebirdClient;
@@ -190,6 +192,13 @@ public override string ConnectionString
 				_options = new ConnectionString(value);
 				_options.Validate();
 				_connectionString = value;
+
+				MetricsConnectionAttributes = [
+					new("db.system.name", "firebirdsql"),
+					new("db.namespace", _options.Database),
+					new("server.address", _options.DataSource),
+					new("server.port", _options.Port),
+				];
 			}
 		}
 	}
@@ -270,6 +279,8 @@ internal bool IsClosed
 		get { return _state == ConnectionState.Closed; }
 	}
 
+	internal KeyValuePair<string, object>[] MetricsConnectionAttributes = [];
+
 	#endregion
 
 	#region Protected Properties
@@ -524,6 +535,7 @@ public override async Task ChangeDatabaseAsync(string databaseName, Cancellation
 	public override void Open()
 	{
 		LogMessages.ConnectionOpening(Log, this);
+		var startedAtTicks = FbMetricsStore.ConnectionOpening();
 
 		if (string.IsNullOrEmpty(_connectionString))
 		{
@@ -616,10 +628,13 @@ public override void Open()
 		}
 
 		LogMessages.ConnectionOpened(Log, this);
+		FbMetricsStore.ConnectionOpened(startedAtTicks, this._options.NormalizedConnectionString);
 	}
+
 	public override async Task OpenAsync(CancellationToken cancellationToken)
 	{
 		LogMessages.ConnectionOpening(Log, this);
+		var startedAtTicks = FbMetricsStore.ConnectionOpening();
 
 		if (string.IsNullOrEmpty(_connectionString))
 		{
@@ -712,6 +727,7 @@ public override async Task OpenAsync(CancellationToken cancellationToken)
 		}
 
 		LogMessages.ConnectionOpened(Log, this);
+		FbMetricsStore.ConnectionOpened(startedAtTicks, this._options.NormalizedConnectionString);
 	}
 
 	public override void Close()