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).

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).

• 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, standard ULID, strictly monotonic ByteAether 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

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

View Package Documentation →

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

View Package Documentation →

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

View Package Documentation →

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

View Package Documentation →

Monotonic ULID correlation ID provider powered by ByteAether.Ulid. Guarantees strict lexicographical ordering even for multiple correlation IDs generated within the exact same millisecond.

View Package Documentation →

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

View Package Documentation →

# 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: Standard ULID provider
dotnet add package NetEvolve.Http.Correlation.Ulid

# Optional: Monotonic ULID provider (ByteAether)
dotnet add package NetEvolve.Http.Correlation.Ulid.ByteAether

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();

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
    }
}

Both standard and ByteAether ULID providers use the same extension method (.WithUlidGenerator()). The active generator depends on which NuGet package and namespace you import:

// Standard ULID Generator (random ordering within the same millisecond)
// Requires: dotnet add package NetEvolve.Http.Correlation.Ulid
using NetEvolve.Http.Correlation.Ulid;

// OR: Monotonic ByteAether ULID Generator (strictly ordered within the same millisecond)
// Requires: dotnet add package NetEvolve.Http.Correlation.Ulid.ByteAether
using NetEvolve.Http.Correlation.Ulid.ByteAether;

// Registration remains identical for both providers:
builder.Services
    .AddHttpCorrelation()
    .WithUlidGenerator();

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>();

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

Follow a single user request through your entire system:

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

Use predictable correlation IDs in tests:

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

// Tests now have consistent correlation IDs

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

Licensed under the MIT License. See LICENSE for details.

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