Document metric naming changes

Author: roji

conceptual/Npgsql/diagnostics/metrics.md

@@ -3,6 +3,8 @@
 Npgsql supports reporting aggregated metrics which provide snapshots on its state and activities at a given point. These can be especially useful for diagnostics issues such as connection leaks, or doing general performance analysis Metrics are reported via the standard .NET System.Diagnostics.Metrics API; [see these docs](https://learn.microsoft.com/dotnet/core/diagnostics/metrics) for more details. The Npgsql metrics implement the experimental [OpenTelemetry semantic conventions for database metrics](https://opentelemetry.io/docs/specs/semconv/database/database-metrics/) - adding some additional useful ones - and will evolve as that specification stabilizes.
 
 > [!NOTE]
+> Npgsql 10.0 changed the metrics names to align with the OpenTelemetry standard. The names shown below reflect the Npgsql 10 counters.
+>
 > Npgsql versions before 8.0, as well as TFMs under net6.0, emit metrics via the older Event Counters API instead of the new OpenTelemetry ones.
 
 Metrics are usually collected and processed via tools such as [Prometheus](https://prometheus.io), and plotted on dashboards via tools such as [Grafana](https://grafana.com). Configuring .NET to emit metrics to these tools is beyond the scope of this documentation, but you can use the command-line tool `dotnet-counters` to quickly test Npgsql's support. To collect metrics via `dotnet-counters`, [install the `dotnet-counters` tool](https://docs.microsoft.com/dotnet/core/diagnostics/dotnet-counters). Then, find out your process PID, and run it as follows:
@@ -15,23 +17,23 @@ dotnet counters monitor Npgsql -p <PID>
 
 ```output
 [Npgsql]
-    db.client.commands.bytes_read (By / 1 sec)
-        pool.name=CustomersDB                                          1,020
-    db.client.commands.bytes_written (By / 1 sec)
-        pool.name=CustomersDB                                            710
-    db.client.commands.duration (s)
-        pool.name=CustomersDB,Percentile=50                                0.001
-        pool.name=CustomersDB,Percentile=95                                0.001
-        pool.name=CustomersDB,Percentile=99                                0.001
-    db.client.commands.executing ({command})
-        pool.name=CustomersDB                                              2
-    db.client.commands.prepared_ratio
-        pool.name=CustomersDB                                              0
-    db.client.connections.max ({connection})
-        pool.name=CustomersDB                                            100
-    db.client.connections.usage ({connection})
-        pool.name=CustomersDB,state=idle                                   3
-        pool.name=CustomersDB,state=used                                   2
+    db.client.operation.npgsql.bytes_read (By / 1 sec)
+        db.client.connection.pool.name=CustomersDB                                          1,020
+    db.client.operation.npgsql.bytes_written (By / 1 sec)
+        db.client.connection.pool.name=CustomersDB                                            710
+    db.client.operation.duration (s)
+        db.client.connection.pool.name=CustomersDB,Percentile=50                                0.001
+        db.client.connection.pool.name=CustomersDB,Percentile=95                                0.001
+        db.client.connection.pool.name=CustomersDB,Percentile=99                                0.001
+    db.client.operation.npgsql.executing ({command})
+        db.client.connection.pool.name=CustomersDB                                              2
+    db.client.operation.npgsql.prepared_ratio
+        db.client.connection.pool.name=CustomersDB                                              0
+    db.client.connection.max ({connection})
+        db.client.connection.pool.name=CustomersDB                                            100
+    db.client.connection.count ({connection})
+        db.client.connection.pool.name=CustomersDB,state=idle                                   3
+        db.client.connection.pool.name=CustomersDB,state=used                                   2
 ```
 
 Note that Npgsql emits multiple *dimensions* with the metrics, e.g. the connection states (idle or used). In addition, an identifier for the connection pool - or data source - is emitted with every metric, allowing you to separately track e.g. multiple databases accessed in the same applications. By default, the `pool.name` will be the connection string, but it can be useful to give your data sources a name for easier and more consistent tracking:

conceptual/Npgsql/release-notes/10.0.md

@@ -44,6 +44,7 @@ Thanks to [@kirkbrauer](https://github.com/kirkbrauer) for contributing this fea
 * Added support for `PGAPPNAME` environment variable. It's mapped to `ApplicationName` field of the connection string.
 * Added support for SHA3 hash algorithms with SASL authentication. Previously, Npgsql falled back to SCRAM-SHA-256 if the certificate, provided by the database, had SHA3 signature algorithm.
 * `NpgsqlConnection.Open` now wraps `SocketException` with `NpgsqlException` when hostname can't be resolved.
+* Metrics names are now more aligned to the OpenTelemetry standard (see breaking change note below).
 * The connection string now supports specifying `TargetSessionAttributes` when used with `NpgsqlDataSourceBuilder`. This means that code creating `NpgsqlDataSource` doesn't have to be aware that it's used with multiple hosts.
 
 ## Breaking changes
@@ -60,6 +61,10 @@ The PostgreSQL `date` and `time` types are now read as .NET [`DateOnly`](https:/
 
 With .NET 6 no longer supported by Npgsql, the PostgreSQL `cidr` type is now mapped to `IPNetwork` by default instead of `NpgsqlCidr`. In addition, `NpgsqlCidr` is now obsolete and will be removed in the future.
 
+### Metrics names have been changed to align with the OpenTelemetry standard
+
+Npgsql emits metrics that provide various numeric information about commands and connections. Since these metrics were designed when the OpenTelemetry specifications were in an earlier stage, they did not align with current standard naming. Npgsql 10 changes metrics names to better align with the standard, allowing Npgsql metrics to be tracked in dashboards just like other standards-conforming database drivers. If you already have a dashboard set up to consume Npgsql metrics, its configuration will need to change to accomodate the new naming.
+
 ### Only root CA certificate is used to validate TLS chain
 
 While establishing TLS connection with PostgreSQL, Npgsql will now only use the provided root CA certificate to validate TLS chain instead of using it in addition to the system CA store. This behaviour aligns with libpq and prevents establishing unintended connections.