NetEvolve.Http.Correlation

A comprehensive suite of NuGet packages for managing HTTP correlation IDs across distributed .NET applications. Enables request tracing and distributed logging using standard HTTP headers (X-Correlation-ID, or X-Request-ID if X-Correlation-ID is not present).

Overview

This library provides a complete solution for implementing correlation IDs in your .NET applications, making it easy to track requests across microservices, logs, and distributed systems. It follows industry best practices and supports modern .NET versions (8.0, 9.0, and 10.0).

Key Features

• Standard HTTP Headers: Support for X-Correlation-ID (primary) and X-Request-ID (fallback)
• ASP.NET Core Integration: Middleware for automatic correlation ID handling
• HTTP Client Integration: Automatic correlation ID forwarding in outgoing requests
• Flexible ID Generation: Pluggable providers (GUID, GUID V7, ULID, or custom)
• Test-Friendly: Dedicated test provider for predictable correlation IDs
• Modern .NET: Full support for .NET 8.0, 9.0, and 10.0
• Source Generators: Compile-time generation for optimal performance

Packages

Core Packages

NetEvolve.Http.Correlation.Abstractions

Core abstractions and interfaces for correlation ID management. Provides the foundational contracts (IHttpCorrelationIdProvider, IHttpCorrelationAccessor) and constants.

View Package Documentation →

NetEvolve.Http.Correlation.AspNetCore

ASP.NET Core middleware and services for handling correlation IDs in web applications. Automatically reads, generates, and propagates correlation IDs.

View Package Documentation →

NetEvolve.Http.Correlation.HttpClient

HTTP client delegating handler for forwarding correlation IDs in outgoing requests. Ensures correlation IDs flow through your distributed system.

View Package Documentation →

Provider Packages

NetEvolve.Http.Correlation.Ulid

ULID-based correlation ID provider. Provides sortable, globally unique identifiers that are more compact than GUIDs.

View Package Documentation →

NetEvolve.Http.Correlation.TestGenerator

Predictable correlation ID provider for testing scenarios. Generates sequential, deterministic IDs for reliable unit and integration tests.

View Package Documentation →

Quick Start

1. Install Packages

# Core ASP.NET Core package
dotnet add package NetEvolve.Http.Correlation.AspNetCore

# HTTP Client package (for outgoing requests)
dotnet add package NetEvolve.Http.Correlation.HttpClient

# Optional: ULID provider
dotnet add package NetEvolve.Http.Correlation.Ulid

2. Configure Services

Add correlation services to your Program.cs:

using NetEvolve.Http.Correlation;

var builder = WebApplication.CreateBuilder(args);

// Register correlation services
builder.Services.AddHttpCorrelation();

// Configure HTTP clients with correlation forwarding
builder.Services
    .AddHttpClient("MyApiClient")
    .WithHttpCorrelation();

var app = builder.Build();

// Add middleware to the pipeline (should be early)
app.UseHttpCorrelation();

app.MapControllers();
app.Run();

3. Access Correlation IDs

Inject IHttpCorrelationAccessor to access the current correlation ID:

public class OrderService
{
    private readonly IHttpCorrelationAccessor _correlationAccessor;
    private readonly ILogger<OrderService> _logger;

    public OrderService(
        IHttpCorrelationAccessor correlationAccessor,
        ILogger<OrderService> logger)
    {
        _correlationAccessor = correlationAccessor;
        _logger = logger;
    }

    public async Task ProcessOrderAsync(Order order)
    {
        var correlationId = _correlationAccessor.CorrelationId;
        _logger.LogInformation(
            "Processing order {OrderId} with correlation ID {CorrelationId}",
            order.Id,
            correlationId);

        // Your business logic here
    }
}

Advanced Configuration

Using ULID Provider

builder.Services
    .AddHttpCorrelation()
    .WithUlidGenerator();

Custom Provider

Implement IHttpCorrelationIdProvider for custom ID generation:

public class CustomCorrelationIdProvider : IHttpCorrelationIdProvider
{
    public string GenerateId()
    {
        return $"CUSTOM-{DateTime.UtcNow.Ticks}";
    }
}

// Register custom provider
builder.Services.AddHttpCorrelation();
builder.Services.AddSingleton<IHttpCorrelationIdProvider, CustomCorrelationIdProvider>();

Use Cases

Distributed Logging

Track requests across multiple services:

// Service A (Entry Point)
app.UseHttpCorrelation(); // Generates or reads correlation ID
_logger.LogInformation("Request received"); // Logs with correlation ID

// Service B (Called by Service A)
httpClient.GetAsync("/api/data"); // Correlation ID automatically forwarded
_logger.LogInformation("Data retrieved"); // Same correlation ID in logs

Microservices Tracing

Follow a single user request through your entire system:

User Request → API Gateway → Service A → Service B → Database
               [CorrelationId: abc123] flows through entire chain

Testing

Use predictable correlation IDs in tests:

builder.Services
    .AddHttpCorrelation()
    .WithTestGenerator(); // Generates predictable IDs

// Tests now have consistent correlation IDs

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

Licensed under the MIT License. See LICENSE for details.

Repository

• GitHub: dailydevops/http.correlation
• Issues: Report Issues
• Releases: View Releases