diff --git a/conceptual/Npgsql/release-notes/10.0.md b/conceptual/Npgsql/release-notes/10.0.md index c8cbd6b0..088e46c6 100644 --- a/conceptual/Npgsql/release-notes/10.0.md +++ b/conceptual/Npgsql/release-notes/10.0.md @@ -7,6 +7,17 @@ Npgsql version 10.0 is now in development, preview versions are available on [nu While this is a relatively minor release in terms of changes, it does contain new features and improvements. Notable changes: +## Tracing and metrics improvements + +Npgsql 10.0 brings multiple observability improvements: + +* Command tracing has been changed to align with [the stable OpenTelemetry tracing semantic conventions](https://opentelemetry.io/docs/specs/semconv/database/database-spans/). This allows tracing any database driver using the same span and tags. +* Metrics support has also been changed to conform to the [OpenTelemetry metrics semantic conventions](https://opentelemetry.io/docs/specs/semconv/database/database-metrics/). The stable `db.client.operation.duration` metric is now emitted, as well as the non-stable `db.client.connection.count`, `db.client.connection.max`. The remaining Npgsql-specific metrics have been renamed for consistency. +* COPY operations (binary, text and raw import/export) are now fully traced. Thanks to [@manandre](https://github.com/manandre) for contributing this feature! +* The opening of physical connections is now also traced, allowing you to observe and identify performance issues. + +Note that these changes modify the metric names and tracing span tags, and so are breaking to anyone currently consuming Npgsql tracing/metrics. + ## GSSAPI session encryption GSSAPI session encryption is an alternative to SSL/TLS session encryption, where special temporary tokens are used to encrypt traffic between the client and the server (MIT Kerberos is one of the GSSAPI providers that can be used for that), unlike SSL/TLS, where SSL certificate is used for the same purpose. You can use the `GssEncryptionMode` connection string parameter to control whether GSS session encryption is used; the default is `Prefer`, which will enable the feature if possible but proceed if it's not available. To learn more, see PostgreSQL [docs](https://www.postgresql.org/docs/current/gssapi-enc.html). @@ -61,9 +72,9 @@ 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 +### Tracing and metrics 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. +Npgsql emits metrics and tracing data that provide various information about commands and connections. Since these were designed when the OpenTelemetry specifications were in an earlier stage, they did not align with current standard naming. Npgsql 10 changes metrics names and tracing span tags to better align with the standard, allowing Npgsql observability data to be tracked in dashboards just like other standards-conforming database drivers. If you already have a dashboard set up to consume Npgsql observability data, its configuration will need to change to accomodate the new naming. ### Only root CA certificate is used to validate TLS chain