Refactor benchmarks

.gitignore

@@ -6,3 +6,4 @@ bin
 obj
 out/
 .idea
+/BenchmarkDotNet.Artifacts

docs/benchmark.md

@@ -0,0 +1,128 @@
+# Benchmarks
+
+The benchmark project (`FirebirdSql.Data.FirebirdClient.Benchmarks`) measures performance of the Firebird .NET provider using [BenchmarkDotNet](https://benchmarkdotnet.org/).
+
+## Prerequisites
+
+- A running Firebird server accessible at `localhost` (default configuration)
+- .NET 10 SDK
+
+## Running Benchmarks
+
+Use the convenience script from the repository root:
+
+```powershell
+.\run-benchmark.ps1
+```
+
+By default this runs `CommandBenchmark`. To select a different benchmark class:
+
+```powershell
+.\run-benchmark.ps1 -Benchmark ConnectionBenchmark
+.\run-benchmark.ps1 -Benchmark LargeFetchBenchmark
+```
+
+### Advanced Options
+
+Enable JIT disassembly output:
+
+```powershell
+.\run-benchmark.ps1 -Disasm
+```
+
+Enable ETW profiling (Windows only):
+
+```powershell
+.\run-benchmark.ps1 -Profile
+```
+
+Options can be combined:
+
+```powershell
+.\run-benchmark.ps1 -Benchmark LargeFetchBenchmark -Disasm
+```
+
+### Running Directly with BenchmarkDotNet
+
+For full control over BenchmarkDotNet options, pass arguments directly after `--`:
+
+```powershell
+dotnet run --project src\FirebirdSql.Data.FirebirdClient.Benchmarks\FirebirdSql.Data.FirebirdClient.Benchmarks.csproj --configuration Release -- --list flat
+dotnet run --project src\FirebirdSql.Data.FirebirdClient.Benchmarks\FirebirdSql.Data.FirebirdClient.Benchmarks.csproj --configuration Release -- --filter "*Fetch*"
+```
+
+## Connection String
+
+By default the benchmark connects to:
+
+```
+database=localhost:benchmark.fdb;user=sysdba;password=masterkey
+```
+
+Override this with the `FIREBIRD_BENCHMARK_CS` environment variable:
+
+```powershell
+$env:FIREBIRD_BENCHMARK_CS = "database=myhost:benchmark.fdb;user=sysdba;password=masterkey"
+.\run-benchmark.ps1
+```
+
+## Configuration
+
+All benchmarks share a common configuration (`BenchmarkConfig`):
+
+- **Baseline job** (`NuGet100`): `ReleaseNuGet` build configuration — references a pinned released `FirebirdSql.Data.FirebirdClient` NuGet package (currently `10.3.1`, set in the benchmark `.csproj`).
+- **Candidate job** (`Core100`): `Release` build configuration — references the local project source.
+- **Runtime**: .NET 10
+- **Diagnostics**: Memory allocations (`MemoryDiagnoser`)
+- **Export**: GitHub-flavored Markdown table (written to `BenchmarkDotNet.Artifacts/`)
+- **Ordering**: Fastest to slowest
+
+The NuGet baseline lets you compare the locally built (unreleased) provider against the **last released version**, so a regression introduced on a branch shows up before it ships. The baseline version is intentionally pinned for reproducible results — bump it to the newest stable release when cutting a release, so "regression vs. last release" stays meaningful.
+
+## Interpreting results
+
+For the fetch and connection benchmarks the **`Mean` is dominated by network/server I/O and is noisy** (look at `StdDev` — it is often a large fraction of the mean). Small or even moderate `Mean` differences between the baseline and candidate jobs are frequently just noise.
+
+The **`Allocated` column (and `Alloc Ratio` vs. the baseline) is the primary signal** for provider-side regressions: managed allocations are deterministic and independent of I/O timing. When comparing the `Core100` (local) job against the `NuGet100` (released) baseline, an `Alloc Ratio` well above `1.00` means the local code allocates more than the last release.
+
+Worked example — issue [#1272](https://github.com/FirebirdSQL/NETProvider/issues/1272): fetching `CHAR(255) CHARACTER SET UTF8` regressed from `369.8 MB` to `4339 MB` allocated (≈11.7×). The allocation column shows the regression far more sharply and reliably than the I/O-bound `Mean` — which is why string/UTF8 `CHAR` types are part of the suite.
+
+## Available Benchmarks
+
+### `CommandBenchmark`
+
+Measures command execution over three data types (`BIGINT`, `VARCHAR(10) CHARACTER SET UTF8`, `CHAR(100) CHARACTER SET UTF8`). The fixed-length `CHAR ... UTF8` type exercises the per-code-point rune handling on both the read (fetch) and write (parameter validate) paths:
+
+| Benchmark | Description |
+|-----------|-------------|
+| `Execute` / `ExecuteAsync` | Inserts 100 rows using `ExecuteNonQuery` / `ExecuteNonQueryAsync` |
+| `Fetch` / `FetchAsync` | Reads 100 rows using `ExecuteReader` / `ExecuteReaderAsync` |
+
+### `ConnectionBenchmark`
+
+Measures connection pool throughput:
+
+| Benchmark | Description |
+|-----------|-------------|
+| `OpenClose` / `OpenCloseAsync` | Opens and closes a pooled connection |
+
+### `LargeFetchBenchmark`
+
+Measures bulk read throughput for 100,000 rows across five data types:
+
+| Data Type | Notes |
+|-----------|-------|
+| `BIGINT` | Fixed-size integer |
+| `CHAR(255) CHARACTER SET UTF8` | Fixed-length string |
+| `CHAR(255) CHARACTER SET OCTETS` | Fixed-length binary |
+| `BLOB SUB_TYPE TEXT CHARACTER SET UTF8` | Text blob |
+| `BLOB SUB_TYPE BINARY` | Binary blob |
+
+## Results
+
+BenchmarkDotNet writes results to `BenchmarkDotNet.Artifacts/` in the repository root. This directory is listed in `.gitignore`. Each run produces:
+
+- A summary table in the console
+- A GitHub-flavored Markdown file (`.md`) suitable for pasting into issues or pull requests
+- An HTML report
+- CSV data

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 |

run-benchmark.ps1

@@ -0,0 +1,23 @@
+param(
+	[ValidateSet('CommandBenchmark','ConnectionBenchmark','LargeFetchBenchmark')]
+	$Benchmark = 'CommandBenchmark',
+
+	[switch]$Disasm,
+	[switch]$Profile
+)
+
+$ErrorActionPreference = 'Stop'
+
+$projectFile = '.\src\FirebirdSql.Data.FirebirdClient.Benchmarks\FirebirdSql.Data.FirebirdClient.Benchmarks.csproj'
+
+$extraArgs = @()
+if ($Disasm) { $extraArgs += '--disasm' }
+if ($Profile) { $extraArgs += '--profiler', 'ETW' }
+
+# Run selected benchmark
+dotnet run `
+    --project $projectFile `
+    --configuration 'Release' `
+    -- `
+    --filter "*$($Benchmark)*" `
+    @extraArgs

src/FirebirdSql.Data.FirebirdClient.Benchmarks/BenchmarkBase.cs

@@ -0,0 +1,41 @@
+/*
+ *    The contents of this file are subject to the Initial
+ *    Developer's Public License Version 1.0 (the "License");
+ *    you may not use this file except in compliance with the
+ *    License. You may obtain a copy of the License at
+ *    https://github.com/FirebirdSQL/NETProvider/raw/master/license.txt.
+ *
+ *    Software distributed under the License is distributed on
+ *    an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, either
+ *    express or implied. See the License for the specific
+ *    language governing rights and limitations under the License.
+ *
+ *    All Rights Reserved.
+ */
+
+//$Authors = Jiri Cincura (jiri@cincura.net)
+
+using System;
+using BenchmarkDotNet.Attributes;
+
+namespace FirebirdSql.Data.FirebirdClient.Benchmarks;
+
+public abstract class BenchmarkBase
+{
+	const string DefaultConnectionString = "database=localhost:benchmark.fdb;user=sysdba;password=masterkey";
+
+	protected static readonly string ConnectionString =
+		Environment.GetEnvironmentVariable("FIREBIRD_BENCHMARK_CS") ?? DefaultConnectionString;
+
+	protected static void CreateDatabase(int pageSize = 16 * 1024)
+	{
+		FbConnection.CreateDatabase(ConnectionString, pageSize, false, true);
+	}
+
+	[GlobalCleanup]
+	public void GlobalCleanup()
+	{
+		FbConnection.ClearAllPools();
+		FbConnection.DropDatabase(ConnectionString);
+	}
+}

src/FirebirdSql.Data.FirebirdClient.Benchmarks/BenchmarkConfig.cs

@@ -0,0 +1,64 @@
+/*
+ *    The contents of this file are subject to the Initial
+ *    Developer's Public License Version 1.0 (the "License");
+ *    you may not use this file except in compliance with the
+ *    License. You may obtain a copy of the License at
+ *    https://github.com/FirebirdSQL/NETProvider/raw/master/license.txt.
+ *
+ *    Software distributed under the License is distributed on
+ *    an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, either
+ *    express or implied. See the License for the specific
+ *    language governing rights and limitations under the License.
+ *
+ *    All Rights Reserved.
+ */
+
+//$Authors = Jiri Cincura (jiri@cincura.net)
+
+using BenchmarkDotNet.Configs;
+using BenchmarkDotNet.Diagnosers;
+using BenchmarkDotNet.Exporters;
+using BenchmarkDotNet.Jobs;
+using BenchmarkDotNet.Order;
+using BenchmarkDotNet.Toolchains;
+using BenchmarkDotNet.Toolchains.CsProj;
+using BenchmarkDotNet.Toolchains.DotNetCli;
+using BenchmarkDotNet.Validators;
+
+namespace FirebirdSql.Data.FirebirdClient.Benchmarks;
+
+class BenchmarkConfig : ManualConfig
+{
+	static readonly IToolchain Net100Toolchain =
+		CsProjCoreToolchain.From(new NetCoreAppSettings("net10.0", null, ".NET 10"));
+
+	public BenchmarkConfig()
+	{
+		var baseJob = Job.Default
+			.WithWarmupCount(3);
+
+		AddJob(
+			baseJob
+				.WithToolchain(Net100Toolchain)
+				.WithCustomBuildConfiguration("ReleaseNuGet")
+				.WithId("NuGet100")
+				.AsBaseline()
+		);
+
+		AddJob(
+			baseJob
+				.WithToolchain(Net100Toolchain)
+				.WithCustomBuildConfiguration("Release")
+				.WithId("Core100")
+		);
+
+		AddDiagnoser(MemoryDiagnoser.Default);
+
+		AddExporter(MarkdownExporter.GitHub);
+
+		Orderer = new DefaultOrderer(SummaryOrderPolicy.FastestToSlowest);
+
+		AddValidator(BaselineValidator.FailOnError);
+		AddValidator(JitOptimizationsValidator.FailOnError);
+	}
+}