TrafficDoctor.AspNetCore 1.1.0

TrafficDoctor.AspNetCore

Professional HTTP traffic monitoring and debugging for ASP.NET Core applications

TrafficDoctor.AspNetCore provides a complete solution for monitoring, analyzing, and debugging HTTP traffic in your ASP.NET Core applications with just a single line of setup.

Features

• One-Line Setup - Just call app.UseTrafficDoctor() and you're done
• Real-Time Dashboard - Beautiful Blazor-based UI with live updates via SignalR
• Performance Analytics - Automatic bottleneck detection and recommendations
• Request Inspection - Full request/response details including headers and body
• Export Capabilities - Export to JSON, HAR (Chrome DevTools), and CSV formats
• Filtering & Search - Advanced filtering by method, status code, duration, and content
• Chart Visualization - Real-time performance charts powered by Chart.js
• Zero Configuration - Works out of the box with sensible defaults

Quick Start

Installation

dotnet add package TrafficDoctor.AspNetCore

Basic Setup

var builder = WebApplication.CreateBuilder(args);

// Add TrafficDoctor services
builder.Services.AddTrafficDoctor();

var app = builder.Build();

// Enable TrafficDoctor middleware and dashboard
app.UseTrafficDoctor();

app.Run();

That's it! Navigate to http://localhost:5000/trafficdoctor to see your dashboard.

Configuration

Configuration via appsettings.json

{
  "TrafficDoctor": {
    "Enabled": true,
    "MaxStoredRequests": 1000,
    "CaptureRequestBody": true,
    "CaptureResponseBody": true,
    "MaxBodySize": 1048576,
    "CaptureHeaders": true,
    "ExcludedPaths": ["/health", "/metrics"],
    "ExcludedHeaders": ["Authorization", "Cookie"],
    "EnableRealTimeUpdates": true,

    "Performance": {
      "HighResponseTimeThresholdMs": 1000,
      "MediumResponseTimeThresholdMs": 500,
      "MinRequestsForBottleneckDetection": 5
    },

    "Security": {
      "RequireAuthentication": false,
      "AllowedUsers": [],
      "AllowedRoles": [],
      "DashboardPath": "/trafficdoctor"
    },

    "RateLimiting": {
      "Enabled": true,
      "PermitLimit": 100,
      "WindowInSeconds": 60,
      "PerIpAddress": true,
      "PerUser": false
    }
  }
}

Configuration via Code

builder.Services.AddTrafficDoctor(options =>
{
    // Core Settings
    options.Enabled = true;
    options.MaxStoredRequests = 1000;

    // Capture Settings
    options.CaptureRequestBody = true;
    options.CaptureResponseBody = true;
    options.MaxBodySize = 1024 * 1024; // 1MB
    options.CaptureHeaders = true;

    // Filtering
    options.ExcludedPaths.Add("/health");
    options.ExcludedPaths.Add("/metrics");
    options.ExcludedHeaders.Add("Authorization");
    options.ExcludedHeaders.Add("Cookie");

    // Performance Thresholds
    options.Performance.HighResponseTimeThresholdMs = 2000;
    options.Performance.MediumResponseTimeThresholdMs = 1000;
    options.Performance.MinRequestsForBottleneckDetection = 10;

    // Security
    options.Security.RequireAuthentication = true;
    options.Security.AllowedRoles.Add("Admin");
    options.Security.DashboardPath = "/admin/traffic";

    // Rate Limiting
    options.RateLimiting.Enabled = true;
    options.RateLimiting.PermitLimit = 100;
    options.RateLimiting.WindowInSeconds = 60;
});

Configuration Options Reference

Core Options

Performance Options

Bottleneck Detection:

• Endpoints with average response time ≥ 1000ms → High Severity
• Endpoints with average response time ≥ 500ms → Medium Severity
• Only endpoints with ≥ 5 requests are analyzed (prevents false positives)

Security Options

Rate Limiting Options

Usage Examples

Example 1: Production Configuration

builder.Services.AddTrafficDoctor(options =>
{
    // Only enable in development
    options.Enabled = builder.Environment.IsDevelopment();

    // Limit memory usage
    options.MaxStoredRequests = 500;

    // Exclude health checks and metrics
    options.ExcludedPaths.Add("/health");
    options.ExcludedPaths.Add("/metrics");

    // Exclude sensitive headers
    options.ExcludedHeaders.Add("Authorization");
    options.ExcludedHeaders.Add("Cookie");
    options.ExcludedHeaders.Add("X-API-Key");

    // Stricter rate limiting in production
    options.RateLimiting.PermitLimit = 50;
    options.RateLimiting.WindowInSeconds = 60;
});

Example 2: Secure Admin Dashboard

builder.Services.AddTrafficDoctor(options =>
{
    // Require authentication
    options.Security.RequireAuthentication = true;

    // Only allow admin role
    options.Security.AllowedRoles.Add("Admin");

    // Custom dashboard path
    options.Security.DashboardPath = "/admin/monitoring";

    // Don't capture request/response bodies for security
    options.CaptureRequestBody = false;
    options.CaptureResponseBody = false;
});

Example 3: Microservice Performance Monitoring

builder.Services.AddTrafficDoctor(options =>
{
    // Focus on performance
    options.MaxStoredRequests = 2000;

    // Aggressive bottleneck detection for microservices
    options.Performance.HighResponseTimeThresholdMs = 500;
    options.Performance.MediumResponseTimeThresholdMs = 200;
    options.Performance.MinRequestsForBottleneckDetection = 20;

    // Exclude inter-service health checks
    options.ExcludedPaths.Add("/health");
    options.ExcludedPaths.Add("/ready");
    options.ExcludedPaths.Add("/live");
});

Example 4: Development Debugging

builder.Services.AddTrafficDoctor(options =>
{
    // Only in development
    options.Enabled = builder.Environment.IsDevelopment();

    // Capture everything for debugging
    options.CaptureRequestBody = true;
    options.CaptureResponseBody = true;
    options.MaxBodySize = 10 * 1024 * 1024; // 10MB

    // No rate limiting in dev
    options.RateLimiting.Enabled = false;

    // Low thresholds to catch all slow requests
    options.Performance.HighResponseTimeThresholdMs = 300;
    options.Performance.MediumResponseTimeThresholdMs = 100;
    options.Performance.MinRequestsForBottleneckDetection = 1;
});

Example 5: Environment-Specific Configuration

builder.Services.AddTrafficDoctor(options =>
{
    if (builder.Environment.IsDevelopment())
    {
        // Development: Full capture, no security
        options.CaptureRequestBody = true;
        options.CaptureResponseBody = true;
        options.Security.RequireAuthentication = false;
        options.RateLimiting.Enabled = false;
    }
    else if (builder.Environment.IsStaging())
    {
        // Staging: Moderate capture, basic security
        options.CaptureRequestBody = true;
        options.CaptureResponseBody = false;
        options.Security.RequireAuthentication = true;
        options.Security.AllowedRoles.Add("Developer");
        options.RateLimiting.PermitLimit = 100;
    }
    else // Production
    {
        // Production: Minimal capture, strict security
        options.CaptureRequestBody = false;
        options.CaptureResponseBody = false;
        options.Security.RequireAuthentication = true;
        options.Security.AllowedRoles.Add("Admin");
        options.ExcludedHeaders.Add("Authorization");
        options.ExcludedHeaders.Add("Cookie");
        options.RateLimiting.PermitLimit = 50;
    }
});

Dashboard Features

Real-Time Monitoring

• Live request capture via SignalR
• Auto-updating metrics (total requests, success rate, avg response time)
• Real-time performance charts

Performance Bottleneck Detection

• Automatic detection of slow endpoints
• Severity classification (High/Medium)
• Actionable recommendations
• Click to filter by bottleneck endpoint

Request/Response Inspection

• Full request details (method, URL, headers, body)
• Full response details (status, headers, body)
• Timing information (duration, throughput)
• Exception tracking

Advanced Filtering

• Search by URL, body content, or headers
• Filter by HTTP method (GET, POST, PUT, DELETE, PATCH)
• Filter by status code range (2xx, 3xx, 4xx, 5xx)
• Filter by response time range

Data Export

• JSON - Full structured data export
• HAR - HTTP Archive format (compatible with Chrome DevTools, Fiddler)
• CSV - Spreadsheet-friendly format

Request Replay

• Replay any captured request
• Modify URL, headers, or body before replay
• View response and timing

API Endpoints

TrafficDoctor exposes RESTful API endpoints for programmatic access:

GET /api/trafficdoctor/captures

Get paginated captures

• Query params: skip (default: 0), take (default: 50)

GET /api/trafficdoctor/captures/{id}

Get specific capture by ID

POST /api/trafficdoctor/captures/search

Search captures with criteria

• Body: TrafficSearchCriteria JSON

GET /api/trafficdoctor/statistics

Get aggregated statistics and bottleneck detection

GET /api/trafficdoctor/count

Get total capture count

POST /api/trafficdoctor/export/json

Export captures to JSON

POST /api/trafficdoctor/export/har

Export captures to HAR format

POST /api/trafficdoctor/export/csv

Export captures to CSV

DELETE /api/trafficdoctor/captures

Clear all captures

SignalR Hub

Real-time updates are available via SignalR hub at /trafficdoctor-hub

Events:

• NewCapture - Fired when a new request is captured
• StatisticsUpdate - Fired when statistics are updated
• CapturesCleared - Fired when captures are cleared

Performance Considerations

Memory Usage

• Circular buffer automatically evicts old requests when MaxStoredRequests is exceeded
• Average memory: ~50KB per request × MaxStoredRequests
• Default 1000 requests ≈ 50MB memory

CPU Overhead

• Middleware overhead: < 5ms per request
• Body capture overhead depends on body size
• Bottleneck detection runs only when statistics are requested

Best Practices

1. Production: Set Enabled = false or use environment-specific configuration
2. Memory: Adjust MaxStoredRequests based on your traffic volume
3. Security: Exclude sensitive headers (Authorization, Cookie, API keys)
4. Performance: Exclude high-frequency endpoints (/health, /metrics)
5. Body Size: Limit MaxBodySize to prevent memory issues with large payloads

Troubleshooting

Dashboard not accessible

• Check that app.UseTrafficDoctor() is called after app.UseRouting() and before app.MapControllers()
• Verify Enabled = true in configuration
• Check the dashboard path in configuration (DashboardPath)

No requests captured

• Ensure middleware is registered: app.UseTrafficDoctor()
• Check excluded paths configuration
• Verify middleware order (should be early in pipeline)

High memory usage

• Reduce MaxStoredRequests
• Reduce MaxBodySize
• Set CaptureRequestBody = false and CaptureResponseBody = false

SignalR connection issues

• Ensure SignalR is properly configured in your application
• Check firewall/proxy settings for WebSocket support
• Verify the hub path matches client configuration

Target Frameworks

• .NET 8.0
• .NET 9.0
• .NET 10.0

Dependencies

• Microsoft.AspNetCore.SignalR
• TrafficDoctor.Core

License

MIT License - See LICENSE file for details

Support

• Issues: Report bugs or request features
• Documentation: Full API documentation available in XML comments