Observability and Debugging

Language: English | Português (Brasil)

Observability and Debugging

When a SQL-focused test fails, DbSqlLikeMem gives you several ways to inspect what happened without immediately jumping to a real database server.

Start with the symptom

Symptom	Best first signal
Wrong rows or wrong SQL path	LastExecutionPlan or LastExecutionPlans
Need a retained artifact for CI or issue tracking	GetDebugTraceSnapshotJson() or GetLastDebugTraceSnapshotJson()
Need to assert event order	RecordingDbConnectionInterceptor
Need readable live output	LoggingDbConnectionInterceptor, TextWriterDbConnectionInterceptor, or ILoggerDbConnectionInterceptor
Need hooks for existing telemetry	DiagnosticListenerDbConnectionInterceptor or ActivitySourceDbConnectionInterceptor

Pick the right signal first

• Use LastExecutionPlan or LastExecutionPlans when you want a quick view of the executed test path.
• Use GetDebugTraceSnapshotText() or GetDebugTraceSnapshotJson() when you want retained traces for the whole batch.
• Use GetLastDebugTraceSnapshotText() or GetLastDebugTraceSnapshotJson() when you only need the most recent retained trace.
• Use RecordingDbConnectionInterceptor when you want an inspectable in-memory event log.
• Use LoggingDbConnectionInterceptor, TextWriterDbConnectionInterceptor, or ILoggerDbConnectionInterceptor when you want normalized event output.
• Use DiagnosticListenerDbConnectionInterceptor or ActivitySourceDbConnectionInterceptor when you want runtime-native hooks.
• Use MiniProfiler Integration when your team already profiles ADO.NET flows.

A fast debugging workflow

1. Re-run the failing test with the same provider mock.
2. Inspect LastExecutionPlan or LastExecutionPlans.
3. Export the retained debug trace as text or JSON.
4. Add recording or logging interception if the failure still needs more context.
5. Attach the text or JSON artifact to the failing test output or issue.

Common combinations

Dapper plus retained traces

using Dapper;

using var connection = new SqliteConnectionMock(new SqliteDbMock());
connection.Open();

connection.Query<int>("select 1").ToList();
var traceJson = connection.GetLastDebugTraceSnapshotJson();

Use this when the failure is already reproducible and you only need to inspect what was executed.

Recording plus logging interception

using var connection = new SqliteConnectionMock(new SqliteDbMock())
    .WithInterception(options =>
    {
        options.UseRecording();
        options.UseLogging(Console.WriteLine);
    });

Use this when you want both a human-readable stream and a retained recording of the same scenario.

Runtime-native diagnostics hooks

using var connection = new SqliteConnectionMock(new SqliteDbMock())
    .WithInterception(options =>
    {
        options.DiagnosticListener = new DiagnosticListener("DbSqlLikeMem.Tests");
        options.ActivitySource = new ActivitySource("DbSqlLikeMem.Tests");
    });

Use this when your host already consumes DiagnosticListener or ActivitySource events.

Good defaults

• Start with retained traces before adding more wrappers.
• Add RecordingDbConnectionInterceptor when you need assertions over the event stream.
• Add human-readable logging only in tests or fixtures where it adds debugging value.
• Keep production-performance analysis on the real provider.

Related pages

• Diagnostics and Execution Plans
• DbConnection Interception
• Dapper and Interception Walkthrough
• MiniProfiler Integration
• FAQ and Troubleshooting
• Performance of Test Suites