Skip to content
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 13 additions & 2 deletions conceptual/Npgsql/release-notes/10.0.md
Original file line number Diff line number Diff line change
Expand Up @@ -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).
Expand Down Expand Up @@ -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

Expand Down