feat(flow-php/symfony-telemetry-bundle): align DBAL and PostgreSQL database instrumentatio

- transaction spans (grouped/per_operation/off) that nest query spans as
children
- DBAL query spans gain semconv names + full db.*/server.* attributes
and bound parameters
- DBAL emits db.client.operation.duration and
db.client.response.returned_rows metrics
- metrics tagged with low-cardinality attributes only (no query text,
params or savepoint)
- config: trace_transactions bool replaced by transaction_spans enum,
drop dbal.log_sql, add collect_metrics/include_parameters
- complete open transaction spans on close/destruct to avoid leaks

Author: norberttech

documentation/components/bridges/symfony-postgresql-bundle.md

@@ -113,7 +113,7 @@ flow_postgresql:
         service_id: "flow.telemetry"         # Required: Telemetry service ID
         clock_service_id: null               # Optional: PSR-20 clock service (defaults to SystemClock)
         trace_queries: true                  # Record query execution in traces
-        trace_transactions: true             # Record transaction boundaries
+        transaction_spans: grouped           # grouped | per_operation | off
         collect_metrics: true                # Collect query metrics (duration, row count)
         log_queries: false                   # Log all queries
         max_query_length: 1000               # Truncate queries longer than this (chars)
@@ -905,7 +905,7 @@ flow_postgresql:
       telemetry:
         service_id: "flow.telemetry"
         trace_queries: true
-        trace_transactions: true
+        transaction_spans: grouped
         collect_metrics: true
         log_queries: false
         max_query_length: 1000

documentation/components/bridges/symfony-telemetry-bundle.md

@@ -1388,8 +1388,12 @@ flow_telemetry:
   instrumentation:
     dbal:
       enabled: true
-      log_sql: true           # Include SQL in span attributes
-      max_sql_length: 1000    # Max SQL length (0 = no limit)
+      max_sql_length: 1000          # Max db.query.text length (0 = no limit)
+      collect_metrics: true         # Emit db.client.operation.duration + db.client.response.returned_rows
+      include_parameters: false     # Include bound statement parameters (security consideration)
+      max_parameters: 10            # Max parameters to include when include_parameters is enabled
+      max_parameter_length: 100     # Max length per included parameter value
+      transaction_spans: grouped    # grouped (one span per transaction) | per_operation | off
       exclude_connections:
         - 'legacy'
         - '/^test_.*/'
@@ -1416,7 +1420,7 @@ flow_telemetry:
 
 A cache pool backed by `cache.adapter.doctrine_dbal` defers writes and flushes them from the pool's own
 commit path at process shutdown — outside any request/message span. Each such write then surfaces as an
-orphan `doctrine.dbal.*` trace (`statement.prepare`/`execute`, `transaction.begin`/`commit`), one per query.
+orphan `doctrine.dbal.*` trace (a `BEGIN TRANSACTION` span wrapping `statement.prepare`/`execute`), one per query.
 
 `flush_deferred: true` drains those deferred writes at request/command termination and after each consumed
 message, inside a single `cache.flush` span, so they group under one trace instead of orphaning (and the pool
@@ -2001,7 +2005,6 @@ flow_telemetry:
       trace: true
     dbal:
       enabled: true
-      log_sql: true
       max_sql_length: 500
     cache:
       enabled: true

documentation/components/libs/postgresql/client-telemetry.md

@@ -46,14 +46,16 @@ Configure telemetry behavior with `postgresql_telemetry_options()`:
 ```php
 <?php
 
+use Flow\PostgreSql\Client\Telemetry\TransactionSpanMode;
+
 use function Flow\PostgreSql\DSL\{postgresql_telemetry_config, postgresql_telemetry_options};
 
 $config = postgresql_telemetry_config(
     $telemetry,
     $clock,
     postgresql_telemetry_options(
         traceQueries: true,       // Create spans for queries
-        traceTransactions: true,  // Create spans for transactions
+        transactionSpans: TransactionSpanMode::GROUPED, // grouped | per_operation | off
         collectMetrics: true,     // Record duration and row count histograms
         logQueries: false,        // Log executed queries
         maxQueryLength: 1000,     // Truncate query text (null = unlimited)
@@ -69,7 +71,7 @@ $config = postgresql_telemetry_config(
 | Option              | Default | Description                                                                 |
 |---------------------|---------|-----------------------------------------------------------------------------|
 | `traceQueries`      | `true`  | Create spans for each query operation                                       |
-| `traceTransactions` | `true`  | Create spans for transaction lifecycle (BEGIN, COMMIT, ROLLBACK)            |
+| `transactionSpans`  | `TransactionSpanMode::GROUPED` | `GROUPED` = one span per transaction; `PER_OPERATION` = a span per BEGIN/COMMIT/ROLLBACK; `OFF` = none |
 | `collectMetrics`    | `true`  | Record duration and row count histograms                                    |
 | `logQueries`        | `false` | Log executed queries via the telemetry logger                               |
 | `maxQueryLength`    | `1000`  | Maximum query text length in span attributes (`null` = unlimited)           |
@@ -84,11 +86,13 @@ Options can be configured fluently:
 ```php
 <?php
 
+use Flow\PostgreSql\Client\Telemetry\TransactionSpanMode;
+
 use function Flow\PostgreSql\DSL\postgresql_telemetry_options;
 
 $options = postgresql_telemetry_options()
     ->traceQueries(true)
-    ->traceTransactions(true)
+    ->transactionSpans(TransactionSpanMode::GROUPED)
     ->collectMetrics(true)
     ->logQueries(true)
     ->maxQueryLength(500)
@@ -219,6 +223,8 @@ Number of rows returned by database operations.
 ```php
 <?php
 
+use Flow\PostgreSql\Client\Telemetry\TransactionSpanMode;
+
 use function Flow\PostgreSql\DSL\{
     pgsql_client,
     pgsql_connection,
@@ -323,7 +329,7 @@ $client = traceable_postgresql_client(
         $clock,
         postgresql_telemetry_options(
             traceQueries: false,
-            traceTransactions: false,
+            transactionSpans: TransactionSpanMode::OFF,
             collectMetrics: true,
         ),
     ),

documentation/upgrading.md

@@ -83,6 +83,44 @@ An excluded path now attaches the OpenTelemetry suppression key for the request'
 orphan root spans (e.g. the `/_wdt` toolbar fetch writing an audit row after its response). If you relied on
 those child spans being recorded for an excluded path, remove the path from `exclude_paths`.
 
+### 7) `flow-php/postgresql`, `flow-php/symfony-postgresql-bundle` - `traceTransactions` bool replaced by
+`transactionSpans` mode
+
+| Before                                                         | After                                                                          |
+|----------------------------------------------------------------|--------------------------------------------------------------------------------|
+| `postgresql_telemetry_options(traceTransactions: true)`        | `postgresql_telemetry_options(transactionSpans: TransactionSpanMode::GROUPED)` |
+| `postgresql_telemetry_options(traceTransactions: false)`       | `postgresql_telemetry_options(transactionSpans: TransactionSpanMode::OFF)`     |
+| `PostgreSqlTelemetryOptions` 2nd arg `bool $traceTransactions` | `TransactionSpanMode $transactionSpans`                                        |
+| `$options->traceTransactions(false)`                           | `$options->transactionSpans(TransactionSpanMode::OFF)`                         |
+| `$options->traceTransactions` (property)                       | `$options->transactionSpans` (`TransactionSpanMode`)                           |
+| config `telemetry.trace_transactions: true`                    | config `telemetry.transaction_spans: grouped`                                  |
+| config `telemetry.trace_transactions: false`                   | config `telemetry.transaction_spans: off`                                      |
+
+`TransactionSpanMode::PER_OPERATION` emits a short span per `BEGIN`/`COMMIT`/`ROLLBACK`; `GROUPED` (default) keeps
+the single long-lived transaction span.
+
+The `db.client.operation.duration` metric now uses only low-cardinality dimensions: queries are tagged with
+`db.system.name`, `db.namespace`, `db.operation.name`, `db.collection.name`; transactions with `db.system.name`,
+`db.namespace`, `db.operation.name` (`begin`/`commit`/`rollback`), `db.transaction.nesting_level`. `db.query.text`,
+`db.query.parameter.*`, `server.address` and `db.transaction.savepoint` are no longer metric dimensions.
+
+### 8) `flow-php/symfony-telemetry-bundle` - DBAL spans, metrics and config aligned with the PostgreSQL client
+
+| Before                                                           | After                                                                                      |
+|------------------------------------------------------------------|--------------------------------------------------------------------------------------------|
+| `doctrine.dbal.transaction.begin`/`.commit`/`.rollback` (always) | one `BEGIN TRANSACTION` span per transaction (`grouped`)                                   |
+| `doctrine.dbal.connection.exec`/`.query` span names              | semconv `{db.operation.name} {db.collection.name}` (e.g. `SELECT users`)                   |
+| `doctrine.dbal.statement.execute`/`.prepare` span names          | semconv `{db.operation.name} {db.collection.name}`                                         |
+| config `instrumentation.dbal.log_sql`                            | removed — `db.query.text` is always recorded (bounded by `max_sql_length`)                 |
+| —                                                                | config `instrumentation.dbal.transaction_spans`: `grouped` (default)/`per_operation`/`off` |
+| —                                                                | config `instrumentation.dbal.collect_metrics` (default `true`)                             |
+| —                                                                | config `instrumentation.dbal.include_parameters`/`max_parameters`/`max_parameter_length`   |
+
+Query spans now carry `db.system.name`, `db.namespace`, `server.address`, `server.port`, `db.operation.name`,
+`db.collection.name`, `db.response.returned_rows` and (on error) `db.response.status_code`, and the instrumentation
+emits `db.client.operation.duration` and `db.client.response.returned_rows` metrics. If you matched DBAL spans by
+their `doctrine.dbal.*` names, switch to the semantic names above.
+
 ---
 
 ## Upgrading from 0.40.x to 0.41.x

src/bridge/symfony/postgresql-bundle/src/Flow/Bridge/Symfony/PostgreSqlBundle/FlowPostgreSqlBundle.php

@@ -31,6 +31,7 @@
 use Flow\PostgreSql\Client\Telemetry\PostgreSqlTelemetryConfig;
 use Flow\PostgreSql\Client\Telemetry\PostgreSqlTelemetryOptions;
 use Flow\PostgreSql\Client\Telemetry\TraceableClient;
+use Flow\PostgreSql\Client\Telemetry\TransactionSpanMode;
 use Flow\PostgreSql\Migrations\Configuration as MigrationsConfiguration;
 use Flow\PostgreSql\Migrations\Executor\MigrationExecutor;
 use Flow\PostgreSql\Migrations\Generator\DiffMigrationGenerator;
@@ -188,8 +189,10 @@ public function configure(DefinitionConfigurator $definition): void
             ->booleanNode('trace_queries')
             ->defaultTrue()
             ->end()
-            ->booleanNode('trace_transactions')
-            ->defaultTrue()
+            ->enumNode('transaction_spans')
+            ->info('How transactions are traced: "grouped" (one span holding the queries), "per_operation" (a short span per BEGIN/COMMIT/ROLLBACK), or "off" (no transaction spans)')
+            ->values(['grouped', 'per_operation', 'off'])
+            ->defaultValue('grouped')
             ->end()
             ->booleanNode('collect_metrics')
             ->defaultTrue()
@@ -495,7 +498,7 @@ public function configure(DefinitionConfigurator $definition): void
     }
 
     /**
-     * @param array{connections: array<string, array{dsn: string, dbname: ?string, host: ?string, port: ?int, user: ?string, password: ?string, dbname_suffix: string, test_transaction_rollback: bool, lazy: bool, context?: array<string, mixed>, telemetry?: array{service_id: string, clock_service_id: ?string, trace_queries: bool, trace_transactions: bool, collect_metrics: bool, log_queries: bool, max_query_length: int, include_parameters: bool, max_parameters: int, max_parameter_length: int}, profiler?: bool}>, messenger: array{enabled: bool, table_name: string, schema: string}, cache: array{pools?: array<string, array{connection: ?string, table_name: string, schema: string, id_col: string, data_col: string, lifetime_col: string, time_col: string, namespace: string, default_lifetime: int, marshaller_service_id: ?string, share_connection: bool}>}, session: array{enabled: bool, connection: ?string, table_name: string, schema: string, id_col: string, data_col: string, lifetime_col: string, time_col: string, lock_mode: string, ttl: ?int, share_connection: bool}, migrations: array{enabled: bool, connection: ?string, directory: string, namespace: string, table_name: string, table_schema: string, migration_file_name: string, rollback_file_name: string, all_or_nothing: bool, generate_rollback: bool, drop_if_exists: bool, context?: array<string, mixed>, exclude?: list<array{schema: ?string, table: ?string, exact: ?string, starts_with: ?string, ends_with: ?string, pattern: ?string, policy_id: ?string, type: ?string, for_schema: ?string}>}, catalog_providers: list<array{catalog_provider_id: ?string, catalog: ?array<string, mixed>}>, profiler?: array{enabled?: bool|null, include_parameters?: bool, migrations?: bool}} $config
+     * @param array{connections: array<string, array{dsn: string, dbname: ?string, host: ?string, port: ?int, user: ?string, password: ?string, dbname_suffix: string, test_transaction_rollback: bool, lazy: bool, context?: array<string, mixed>, telemetry?: array{service_id: string, clock_service_id: ?string, trace_queries: bool, transaction_spans: 'grouped'|'per_operation'|'off', collect_metrics: bool, log_queries: bool, max_query_length: int, include_parameters: bool, max_parameters: int, max_parameter_length: int}, profiler?: bool}>, messenger: array{enabled: bool, table_name: string, schema: string}, cache: array{pools?: array<string, array{connection: ?string, table_name: string, schema: string, id_col: string, data_col: string, lifetime_col: string, time_col: string, namespace: string, default_lifetime: int, marshaller_service_id: ?string, share_connection: bool}>}, session: array{enabled: bool, connection: ?string, table_name: string, schema: string, id_col: string, data_col: string, lifetime_col: string, time_col: string, lock_mode: string, ttl: ?int, share_connection: bool}, migrations: array{enabled: bool, connection: ?string, directory: string, namespace: string, table_name: string, table_schema: string, migration_file_name: string, rollback_file_name: string, all_or_nothing: bool, generate_rollback: bool, drop_if_exists: bool, context?: array<string, mixed>, exclude?: list<array{schema: ?string, table: ?string, exact: ?string, starts_with: ?string, ends_with: ?string, pattern: ?string, policy_id: ?string, type: ?string, for_schema: ?string}>}, catalog_providers: list<array{catalog_provider_id: ?string, catalog: ?array<string, mixed>}>, profiler?: array{enabled?: bool|null, include_parameters?: bool, migrations?: bool}} $config
      */
     #[Override]
     public function loadExtension(array $config, ContainerConfigurator $configurator, ContainerBuilder $container): void
@@ -750,7 +753,7 @@ private function registerCatalogProviders(array $catalogProviders, ContainerBuil
     }
 
     /**
-     * @param array{dsn: string, dbname: ?string, host: ?string, port: ?int, user: ?string, password: ?string, dbname_suffix: string, test_transaction_rollback: bool, lazy: bool, context?: array<string, mixed>, telemetry?: array{service_id: string, clock_service_id: ?string, trace_queries: bool, trace_transactions: bool, collect_metrics: bool, log_queries: bool, max_query_length: int, include_parameters: bool, max_parameters: int, max_parameter_length: int}, profiler?: bool} $connectionConfig
+     * @param array{dsn: string, dbname: ?string, host: ?string, port: ?int, user: ?string, password: ?string, dbname_suffix: string, test_transaction_rollback: bool, lazy: bool, context?: array<string, mixed>, telemetry?: array{service_id: string, clock_service_id: ?string, trace_queries: bool, transaction_spans: 'grouped'|'per_operation'|'off', collect_metrics: bool, log_queries: bool, max_query_length: int, include_parameters: bool, max_parameters: int, max_parameter_length: int}, profiler?: bool} $connectionConfig
      */
     private function registerConnection(
         string $name,
@@ -1141,13 +1144,13 @@ private function registerStaticConnection(string $name, ContainerBuilder $contai
     }
 
     /**
-     * @param array{service_id: string, clock_service_id: ?string, trace_queries: bool, trace_transactions: bool, collect_metrics: bool, log_queries: bool, max_query_length: int, include_parameters: bool, max_parameters: int, max_parameter_length: int} $telemetryConfig
+     * @param array{service_id: string, clock_service_id: ?string, trace_queries: bool, transaction_spans: 'grouped'|'per_operation'|'off', collect_metrics: bool, log_queries: bool, max_query_length: int, include_parameters: bool, max_parameters: int, max_parameter_length: int} $telemetryConfig
      */
     private function registerTelemetry(string $name, array $telemetryConfig, ContainerBuilder $container): void
     {
         $optionsDef = new Definition(PostgreSqlTelemetryOptions::class, [
             $telemetryConfig['trace_queries'],
-            $telemetryConfig['trace_transactions'],
+            TransactionSpanMode::from($telemetryConfig['transaction_spans']),
             $telemetryConfig['collect_metrics'],
             $telemetryConfig['log_queries'],
             $telemetryConfig['max_query_length'],

src/bridge/symfony/postgresql-bundle/tests/Flow/Bridge/Symfony/PostgreSqlBundle/Tests/Integration/FlowPostgreSqlExtensionTest.php

@@ -25,6 +25,7 @@
 use Flow\PostgreSql\Client\Context;
 use Flow\PostgreSql\Client\Telemetry\PostgreSqlTelemetryOptions;
 use Flow\PostgreSql\Client\Telemetry\TraceableClient;
+use Flow\PostgreSql\Client\Telemetry\TransactionSpanMode;
 use Flow\PostgreSql\Migrations\Configuration as MigrationsConfiguration;
 use Flow\PostgreSql\Migrations\Executor\MigrationExecutor;
 use Flow\PostgreSql\Migrations\Generator\DiffMigrationGenerator;
@@ -1721,7 +1722,7 @@ public function test_telemetry_options_propagated_to_config(): void
         static::assertTrue($options->includeParameters);
         static::assertSame(500, $options->maxQueryLength);
         static::assertTrue($options->traceQueries);
-        static::assertTrue($options->traceTransactions);
+        static::assertSame(TransactionSpanMode::GROUPED, $options->transactionSpans);
         static::assertTrue($options->collectMetrics);
     }
 }

src/bridge/symfony/postgresql-bundle/tests/Flow/Bridge/Symfony/PostgreSqlBundle/Tests/Unit/DependencyInjection/ConfigurationTest.php

@@ -725,7 +725,7 @@ public function test_telemetry_with_custom_options(): void
                         'service_id' => 'my.telemetry',
                         'clock_service_id' => 'my.clock',
                         'trace_queries' => false,
-                        'trace_transactions' => false,
+                        'transaction_spans' => 'off',
                         'collect_metrics' => false,
                         'log_queries' => true,
                         'max_query_length' => 500,
@@ -741,7 +741,7 @@ public function test_telemetry_with_custom_options(): void
         static::assertSame('my.telemetry', $telemetry['service_id']);
         static::assertSame('my.clock', $telemetry['clock_service_id']);
         static::assertFalse($telemetry['trace_queries']);
-        static::assertFalse($telemetry['trace_transactions']);
+        static::assertSame('off', $telemetry['transaction_spans']);
         static::assertFalse($telemetry['collect_metrics']);
         static::assertTrue($telemetry['log_queries']);
         static::assertSame(500, $telemetry['max_query_length']);
@@ -767,7 +767,7 @@ public function test_telemetry_with_defaults(): void
         static::assertSame('flow.telemetry', $telemetry['service_id']);
         static::assertNull($telemetry['clock_service_id']);
         static::assertTrue($telemetry['trace_queries']);
-        static::assertTrue($telemetry['trace_transactions']);
+        static::assertSame('grouped', $telemetry['transaction_spans']);
         static::assertTrue($telemetry['collect_metrics']);
         static::assertFalse($telemetry['log_queries']);
         static::assertSame(1000, $telemetry['max_query_length']);