NetAmpowering.Observability.NHibernate 1.0.0

NetAmpowering.Observability.NHibernate

OpenTelemetry tracing for NHibernate 5.5.2+ (versions 5.5.0 and 5.5.1 are vulnerable, CVE-2024-39677: the package therefore requires 5.5.2 at minimum), on .NET Framework 4.7.2+ and .NET 8: one span per SQL command (query, execute, scalar; sync and async).

Install-Package NetAmpowering.Observability.NHibernate

var cfg = new Configuration().Configure();   // or DataBaseIntegration(...)
cfg.AddNetAmpoweringTracing();               // after Configure(), before BuildSessionFactory()
var factory = cfg.BuildSessionFactory();

How it works

NHibernate has no SQL execution hook: the package ships derived drivers that wrap the DbCommand (TracingDbCommand) through the CreateCommand() / UnwrapDbCommand() extension points of DriverBase. AddNetAmpoweringTracing() replaces connection.driver_class with the traced equivalent:

Any other driver (Oracle, PostgreSQL…): derive your own in three lines.

public class TracingMyDriver : MyDriver
{
    public override DbCommand CreateCommand() => TracingDbCommand.Wrap(base.CreateCommand());
    public override DbCommand UnwrapDbCommand(DbCommand command) => base.UnwrapDbCommand(TracingDbCommand.Unwrap(command));
}

DB query|execute|scalar span tags: db.system, db.name, db.operation, db.statement (without parameter values). Disable the SQL text: DatabaseTracing.Options.CaptureStatement = false;. Activity source: BlazorApp.Database.

Limitations

• Batching (adonet.batch_size): not verified. NHibernate may use internal SQL Server commands there that bypass CreateCommand(); check before relying on one span per batched INSERT.
• Tested with SqlClientDriver (SQL Server LocalDB) on .NET Framework 4.7.2; the SQLite and Microsoft.Data.SqlClient drivers compile but have not been run.

Privacy: no SQL parameter in the telemetry

• The span only contains the parameterized SQL text (@p0, @p__linq__0), never the values. Note: a value written as a literal in raw SQL ("... WHERE name = 'Smith'") is part of the text; disable CaptureStatement in that case.
• Database exception messages are masked: SqlException quotes values ("duplicate key value is (123)") and NHibernate.GenericADOException appends Name:p0 - Value:.... Message and stack text are replaced by "Database error (...): details hidden"; the exception type and frames are kept. This masking also applies to parent spans (HTTP request, MVC action, WebForms page, Blazor component, traced service).
• To capture everything (development only): DatabaseTracing.Options.CaptureExceptionDetails = true;.