DBLense Trace Replay — User Guide
Capture SQL Server Extended Events traces and re-execute them against a target instance using a multi-threaded engine that simulates concurrent user connections.
Overview
DBLense Trace Replay captures SQL Server Extended Events traces and replays them against a target server. It works with both on-premises SQL Server and Azure SQL Managed Instances.
Key Use Cases
- Reproduce production issues on a test server safely
- Test query performance improvements before deploying to production
- Compare execution results between environments (dev vs. staging vs. prod)
- Validate patches/upgrades by replaying a real workload against a new version
- Debug intermittent issues by replaying captured workloads
Getting Started
- Connect to Source Server — The connection dialog appears on startup. Enter the source SQL Server where you want to capture traces.
- Set Target Server — Click "Set Target Server" in the header bar to configure the replay destination.
All four authentication modes are supported: Windows, SQL Server, Azure Entra ID (Password), and Azure Entra ID (MFA).
Capture Tab
Creating a New Capture Session
- Enter a Session Name (default:
DBLenseTraceCapture) - (Optional) Set a Database Filter to capture only events from a specific database
- (Optional) Set a Min Duration filter (in microseconds) to skip fast queries
- Configure storage target:
- On-premises: Enter a File Target Path (e.g.,
C:\Traces\), or leave empty for ring_buffer - Azure MI: Use ring_buffer (default) or enter an Azure Blob Storage URL
- On-premises: Enter a File Target Path (e.g.,
- Click Create & Start to begin capturing
Captured Event Types
| Event | Purpose |
|---|---|
sqlserver.rpc_starting | Stored procedure calls (start) |
sqlserver.rpc_completed | Stored procedure calls (completed with metrics) |
sqlserver.sql_batch_starting | Ad-hoc SQL batches (start) |
sqlserver.sql_batch_completed | Ad-hoc SQL batches (completed with metrics) |
sqlserver.sql_transaction | Transaction begin/commit/rollback |
Each event captures: session_id, database_name, sql_text, username, client_hostname, duration, cpu_time, logical_reads, physical_reads, writes, row_count.
Stopping and Reading Events
- Execute your workload on the source server while capture is running
- Click Stop Capture when done
- Click Read Events to load captured events into the grid
Reading from Existing Sessions
If you already have an Extended Events session running, select it from the Existing XE Sessions dropdown and click Read From Selected Session.
Replay Tab
Configuration Options
| Option | Description | Default |
|---|---|---|
| Target Database | Override original database for all events | (use original) |
| Max Concurrent Threads | Number of simultaneous connections | 10 |
| Speed Factor | 0 = max speed, 1.0 = real-time, 2.0 = double speed | 0 |
| Command Timeout | Seconds before query times out | 120 |
| Max Errors | Stop after this many errors (0 = unlimited) | 100 |
| Dry Run | Wrap each query in a rolled-back transaction | Off |
| Preserve Session Order | Group events by SPID and replay in order | On |
| Skip System Queries | Filter out sp_reset_connection, SET commands, etc. | On |
Starting Replay
- Ensure you have captured/loaded events
- Ensure target server is configured
- Configure replay options
- Click Start Replay
Live Results
The replay grid shows results in real-time:
- Status: ✓ success or ✗ error
- Original vs. Replay duration: Compare performance
- Diff %: Green = faster, Red = slower, Amber = similar
- Thread: Which replay thread executed the query
- Error: Error details for failed queries
Click Export CSV to save all replay results.
Summary Tab
After replay completes:
- Total Events / Replayed / Errors / Success Rate
- Avg Original/Replay Duration — Performance comparison
- Overall Speedup — Positive = replay was faster
- Wall Clock — Total elapsed time
- Activity Log — Timestamped operation log
Azure SQL Managed Instance
The tool automatically detects Azure MI (Engine Edition = 8) and:
- Hides the local file target option
- Shows the Azure Blob Storage URL field
- Displays an informational banner about MI limitations
- Defaults to ring_buffer storage
Tips for Azure MI
- ring_buffer size: Increase to 128+ MB for heavy workloads
- Azure Blob Storage: Recommended for production-level capture volumes
Command-Line Arguments
DBLenseTraceReplay.exe [-s server] [-u user] [-p password] [-e]| Arg | Description |
|---|---|
-s, --server | Source server name |
-u, --user | SQL login username |
-p, --password | SQL login password |
-e | Use Windows Authentication |
Troubleshooting
| Issue | Solution |
|---|---|
| "Cannot create event session" | Ensure you have ALTER ANY EVENT SESSION permission |
| No events captured | Check the database filter; ensure workload is running |
| Azure MI file target error | Use ring_buffer or Azure Blob Storage URL |
| High error count during replay | Check target database exists; verify permissions; increase command timeout |
| Missing events in ring_buffer | ring_buffer has size limits; increase buffer or use file/blob target |
System Requirements
| Component | Requirement |
|---|---|
| OS | Windows 10/11 or Windows Server 2016+ |
| Runtime | .NET 8.0 (or self-contained package) |
| SQL Server | SQL Server 2012+ (for Extended Events) |
| Azure | Azure SQL Managed Instance (fully supported) |
| Permissions | ALTER ANY EVENT SESSION on source; appropriate permissions on target |
| Installation | None — single portable .exe |