A performance monitoring package for Entity Framework Core that tracks slow queries, execution times, and provides detailed analytics for query optimization.
A zero-impact, production-ready NuGet package for monitoring Entity Framework Core query performance with automatic slow query detection, execution plan analysis, and flexible reporting capabilities. Features built-in asynchronous queue processing that eliminates performance overhead on your main application.
🚀 Features
⚡ Zero Performance Impact - Built-in asynchronous queue processing moves all analysis to background threads
🔄 Background Processing - Query analysis, execution plan capture, and HTTP reporting happen asynchronously
🔍 Real-time Query Detection - Instantly detects slow queries without blocking your application
📊 Execution Plan Analysis - Captures and analyzes SQL Server execution plans for performance insights
🎯 Configurable Thresholds - Set custom slow query detection thresholds per environment
🗄️ Multi-database Support - Works with SQL Server, PostgreSQL, MySQL, Oracle, and SQLite
🏆 Production-Ready - Built-in queue architecture ensures your HTTP endpoints maintain full speed
📦 Installation
Install the package via NuGet Package Manager:
dotnet add package EFCore.QueryAnalyzer
Or via Package Manager Console:
Install-Package EFCore.QueryAnalyzer
🚀 Quick Start
1. Basic Setup with Dependency Injection
using EFCore.QueryAnalyzer.Extensions;
var builder = WebApplication.CreateBuilder(args);
// Add the query analyzer with configuration
builder.Services.AddEFCoreQueryAnalyzer(builder.Configuration);
// Configure your DbContext with the analyzer
builder.Services.AddDbContext<MyDbContext>((serviceProvider, options) =>
{
options.UseSqlServer(connectionString)
.AddQueryAnalyzer(serviceProvider);
});
var app = builder.Build();
✨ Performance Boost: The analyzer now processes all slow queries in the background, ensuring zero impact on your application performance! Your HTTP endpoints will maintain full speed while comprehensive query monitoring happens asynchronously.
That's it! The analyzer will now monitor your queries and report slow ones automatically in the background with zero performance impact on your application.
⚙️ Configuration Options
Option
Type
Default
Description
ThresholdMilliseconds
double
1000
Threshold in milliseconds for slow query detection
IsEnabled
bool
false
Whether the analyzer is enabled
CaptureStackTrace
bool
true
Capture stack traces for slow queries
CaptureExecutionPlan
bool
false
Capture database execution plans
MaxStackTraceLines
int
20
Maximum lines in captured stack traces
MaxQueryLength
int
10000
Maximum query text length to store
ApiEndpoint
string?
null
HTTP endpoint for reporting slow queries
ApiKey
string?
null
API key for authentication
ProjectId
string?
null
Project identifier sent as X-PROJECT-ID header
ApiTimeoutMs
int
5000
API request timeout in milliseconds
DatabaseProvider
DatabaseProvider
Auto
Database provider for execution plans
ExecutionPlanTimeoutSeconds
int
30
Timeout for execution plan capture
ConnectionString
string?
null
Connection string for execution plan capture
Note: All query analysis and reporting happens asynchronously in background threads, ensuring zero impact on your application's response times.
Authorization: Bearer {ApiKey} (when ApiKey is provided)
X-PROJECT-ID: {ProjectId} (when ProjectId is provided)
2. In-Memory Reporting (Testing/Development)
builder.Services.AddEFCoreQueryAnalyzerWithInMemory(options =>
{
options.ThresholdMilliseconds = 100;
options.CaptureStackTrace = true;
options.CaptureExecutionPlan = true;
});
// In tests, access the reports
var reportingService = serviceProvider.GetService<IQueryReportingService>()
as InMemoryQueryReportingService;
var reports = reportingService?.GetReports();
3. Custom Reporting Service
Create and register custom reporting services with flexible service lifetime options:
public class DatabaseReportingService : IQueryReportingService
{
private readonly IDbContextFactory<LoggingDbContext> _dbContextFactory;
private readonly ILogger<DatabaseReportingService> _logger;
public DatabaseReportingService(
IDbContextFactory<LoggingDbContext> dbContextFactory,
ILogger<DatabaseReportingService> logger)
{
_dbContextFactory = dbContextFactory;
_logger = logger;
}
public async Task ReportSlowQueryAsync(QueryTrackingContext context,
CancellationToken cancellationToken = default)
{
try
{
using var dbContext = _dbContextFactory.CreateDbContext();
var logEntry = new SlowQueryLog
{
QueryId = context.QueryId,
Query = context.CommandText,
ExecutionTimeMs = context.ExecutionTime.TotalMilliseconds,
Timestamp = context.StartTime,
ContextType = context.ContextType
};
dbContext.SlowQueryLogs.Add(logEntry);
await dbContext.SaveChangesAsync(cancellationToken);
_logger.LogInformation("Logged slow query {QueryId} to database", context.QueryId);
}
catch (Exception ex)
{
_logger.LogError(ex, "Failed to log slow query {QueryId} to database", context.QueryId);
}
}
}
// Register custom service with default (Transient) lifetime
builder.Services.AddEFCoreQueryAnalyzerWithCustomReporting<DatabaseReportingService>(
options =>
{
options.ThresholdMilliseconds = 750;
options.CaptureStackTrace = true;
options.CaptureExecutionPlan = true;
});
// Register with specific service lifetime (Singleton for performance)
builder.Services.AddEFCoreQueryAnalyzerWithCustomReporting<DatabaseReportingService>(
options => options.ThresholdMilliseconds = 500,
ServiceLifetime.Singleton);
// Register with Scoped lifetime for database operations
builder.Services.AddEFCoreQueryAnalyzerWithCustomReporting<DatabaseReportingService>(
options => options.ThresholdMilliseconds = 1000,
ServiceLifetime.Scoped);
Service Lifetime Considerations:
Transient (default): New instance per slow query report - safest option
Scoped: One instance per request scope - good for database operations
Singleton: Single instance for the application - best performance, ensure thread safety
4. Inline Configuration (No DI)
var options = new DbContextOptionsBuilder<MyDbContext>()
.UseSqlServer(connectionString)
.AddQueryAnalyzer(analyzerOptions =>
{
analyzerOptions.ThresholdMilliseconds = 500;
analyzerOptions.CaptureExecutionPlan = true;
})
.Options;
using var context = new MyDbContext(options);
🚀 Performance & Background Processing
Zero Performance Impact Architecture
EFCore.QueryAnalyzer v1.1+ features a revolutionary built-in queue processing system that eliminates performance overhead:
Instant Detection: Slow queries are detected in microseconds
Background Processing: All analysis, execution plan capture, and HTTP reporting happen asynchronously
No Blocking: Your HTTP endpoints maintain full speed regardless of analyzer activity
Automatic: No configuration required - queue processing is built-in and always enabled
Graceful Shutdown: Processes remaining queries during application shutdown
How It Works
graph LR
A[Query Execution] --> B[Interceptor Detection]
B --> C["Queue Item (μs)"]
C --> D[Background Service]
D --> E[Execution Plan Capture]
D --> F[HTTP Reporting]
D --> G[Analysis Complete]
Query executes normally - No performance impact
Interceptor detects slow query - Takes microseconds to enqueue
Background service processes - All heavy operations happen asynchronously
Your application continues - Full speed maintained
Backward Compatibility
Existing users get automatic benefits - no code changes required! Simply update your package version and enjoy zero-impact monitoring.
📊 Report Format
When a slow query is detected, a comprehensive JSON report is generated:
{
"queryId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"rawQuery": "SELECT u.Id, u.Email FROM Users u WHERE u.Email LIKE @p0",
"parameters": {
"@p0": "%john%"
},
"executionTimeMs": 1250.5,
"stackTrace": [
"at MyApp.Controllers.UserController.GetUsers() in UserController.cs:line 45",
"at MyApp.Services.UserService.FindByEmail() in UserService.cs:line 23"
],
"timestamp": "2024-01-15T10:30:00Z",
"contextType": "MyApp.Data.ApplicationDbContext",
"environment": "Development",
"applicationName": "MyApplication",
"version": "1.0.0",
"executionPlan": {
"databaseProvider": "SqlServer",
"planFormat": {
"contentType": "application/xml",
"fileExtension": ".sqlplan",
"description": "SQL Server XML Execution Plan"
},
"content": "<ShowPlanXML xmlns=\"...\">...</ShowPlanXML>"
}
}
🔍 Execution Plan Analysis
The analyzer can capture and analyze database execution plans for deep performance insights:
EFCore.QueryAnalyzer now includes advanced parameterized query handling for more accurate execution plans:
The Problem
SQL Server's SET SHOWPLAN_XML ON doesn't work well with parameterized queries because the query optimizer needs actual values to make cost estimations and generate accurate execution plans.
The Solution
The analyzer automatically converts parameterized queries to use literal values when capturing execution plans:
// Original parameterized query
SELECT * FROM Users WHERE Age > @p0 AND City = @p1
// Automatically converted to literal values for execution plan
SELECT * FROM Users WHERE Age > 25 AND City = 'New York'
Benefits
More Accurate Plans: SQL Server optimizer sees actual values, not parameter placeholders
Better Cost Estimates: Execution plans show realistic cost calculations
Improved Analysis: Index usage recommendations are more precise
Automatic Processing: No configuration needed - works transparently
Data Type Support
The literal value conversion handles all common data types safely:
public class SmartReportingService : IQueryReportingService
{
public async Task ReportSlowQueryAsync(QueryTrackingContext context,
CancellationToken cancellationToken)
{
// Only report critical context queries
if (context.ContextType.Contains("CriticalDbContext"))
{
await _urgentReporter.ReportAsync(context);
}
// Different handling for different query types
if (context.CommandText.Contains("SELECT") &&
context.ExecutionTime.TotalSeconds > 5)
{
await _selectQueryReporter.ReportAsync(context);
}
}
}
Performance Analysis
public class PerformanceAnalysisService : IQueryReportingService
{
public async Task ReportSlowQueryAsync(QueryTrackingContext context,
CancellationToken cancellationToken)
{
// Analyze execution plan if available
if (context.ExecutionPlan?.Content != null)
{
var analysis = await AnalyzeExecutionPlan(context.ExecutionPlan);
await RecommendOptimizations(context, analysis);
}
// Pattern-based analysis
if (context.CommandText.Contains("SELECT *"))
{
await AlertSelectStarUsage(context);
}
}
}
🚨 Best Practices
1. Production Confidence
With built-in queue processing, you can now confidently enable the analyzer in production:
// Production-safe configuration with zero performance impact
builder.Services.AddEFCoreQueryAnalyzer(options =>
{
options.ThresholdMilliseconds = 1000;
options.CaptureExecutionPlan = true; // Even heavy operations are safe
options.ApiEndpoint = "https://monitoring.company.com/api/queries";
});
This ensures your production logs stay clean while maintaining operational visibility.
6. Testing Integration
// Test setup - background processing works in tests too
services.AddEFCoreQueryAnalyzerWithInMemory(options =>
{
options.ThresholdMilliseconds = 1; // Capture all queries in tests
});
// Test assertions
var reports = inMemoryReporter.GetReports();
Assert.Contains(reports, r => r.RawQuery.Contains("Users"));
🐛 Troubleshooting
Common Issues
Issue
Cause
Solution
API authentication errors
Invalid API key
Verify ApiKey configuration
Missing stack traces
Stack trace capture disabled
Set CaptureStackTrace = true
High memory usage
Large query texts/stack traces
Reduce MaxQueryLength and MaxStackTraceLines
Execution plan timeouts
Database connection issues
Increase ExecutionPlanTimeoutSeconds
Background processing not working
Service not registered
Ensure you're using the provided extension methods
