|
1 | 1 | # NetEvolve.Http.Correlation |
2 | | -Several NuGet packages to support and use a correlation ID based on HTTP header `X-Correlation-ID` or alternatively `X-Request-ID`. |
| 2 | + |
| 3 | +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). |
| 4 | + |
| 5 | +## Overview |
| 6 | + |
| 7 | +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). |
| 8 | + |
| 9 | +## Key Features |
| 10 | + |
| 11 | +- **Standard HTTP Headers**: Support for `X-Correlation-ID` (primary) and `X-Request-ID` (fallback) |
| 12 | +- **ASP.NET Core Integration**: Middleware for automatic correlation ID handling |
| 13 | +- **HTTP Client Integration**: Automatic correlation ID forwarding in outgoing requests |
| 14 | +- **Flexible ID Generation**: Pluggable providers (GUID, GUID V7, ULID, or custom) |
| 15 | +- **Test-Friendly**: Dedicated test provider for predictable correlation IDs |
| 16 | +- **Modern .NET**: Full support for .NET 8.0, 9.0, and 10.0 |
| 17 | +- **Source Generators**: Compile-time generation for optimal performance |
3 | 18 |
|
4 | 19 | ## Packages |
5 | 20 |
|
6 | | -### NetEvolve.Http.Correlation.Abstractions |
| 21 | +### Core Packages |
| 22 | + |
| 23 | +#### NetEvolve.Http.Correlation.Abstractions |
7 | 24 | [](https://www.nuget.org/packages/NetEvolve.Http.Correlation.Abstractions) |
8 | 25 |
|
9 | | -### NetEvolve.Http.Correlation.AspNetCore |
| 26 | +Core abstractions and interfaces for correlation ID management. Provides the foundational contracts (`IHttpCorrelationIdProvider`, `IHttpCorrelationAccessor`) and constants. |
| 27 | + |
| 28 | +**[View Package Documentation →](https://github.com/dailydevops/http.correlation/blob/main/src/NetEvolve.Http.Correlation.Abstractions/README.md)** |
| 29 | + |
| 30 | +#### NetEvolve.Http.Correlation.AspNetCore |
10 | 31 | [](https://www.nuget.org/packages/NetEvolve.Http.Correlation.AspNetCore) |
11 | 32 |
|
12 | | -### NetEvolve.Http.Correlation.HttpClient |
| 33 | +ASP.NET Core middleware and services for handling correlation IDs in web applications. Automatically reads, generates, and propagates correlation IDs. |
| 34 | + |
| 35 | +**[View Package Documentation →](https://github.com/dailydevops/http.correlation/blob/main/src/NetEvolve.Http.Correlation.AspNetCore/README.md)** |
| 36 | + |
| 37 | +#### NetEvolve.Http.Correlation.HttpClient |
13 | 38 | [](https://www.nuget.org/packages/NetEvolve.Http.Correlation.HttpClient) |
14 | 39 |
|
15 | | -### NetEvolve.Http.Correlation.TestGenerator |
16 | | -[](https://www.nuget.org/packages/NetEvolve.Http.Correlation.TestGenerator) |
| 40 | +HTTP client delegating handler for forwarding correlation IDs in outgoing requests. Ensures correlation IDs flow through your distributed system. |
| 41 | + |
| 42 | +**[View Package Documentation →](https://github.com/dailydevops/http.correlation/blob/main/src/NetEvolve.Http.Correlation.HttpClient/README.md)** |
17 | 43 |
|
18 | | -### NetEvolve.Http.Correlation.Ulid |
| 44 | +### Provider Packages |
| 45 | + |
| 46 | +#### NetEvolve.Http.Correlation.Ulid |
19 | 47 | [](https://www.nuget.org/packages/NetEvolve.Http.Correlation.Ulid) |
| 48 | + |
| 49 | +ULID-based correlation ID provider. Provides sortable, globally unique identifiers that are more compact than GUIDs. |
| 50 | + |
| 51 | +**[View Package Documentation →](https://github.com/dailydevops/http.correlation/blob/main/src/NetEvolve.Http.Correlation.Ulid/README.md)** |
| 52 | + |
| 53 | +#### NetEvolve.Http.Correlation.TestGenerator |
| 54 | +[](https://www.nuget.org/packages/NetEvolve.Http.Correlation.TestGenerator) |
| 55 | + |
| 56 | +Predictable correlation ID provider for testing scenarios. Generates sequential, deterministic IDs for reliable unit and integration tests. |
| 57 | + |
| 58 | +**[View Package Documentation →](https://github.com/dailydevops/http.correlation/blob/main/src/NetEvolve.Http.Correlation.TestGenerator/README.md)** |
| 59 | + |
| 60 | +## Quick Start |
| 61 | + |
| 62 | +### 1. Install Packages |
| 63 | + |
| 64 | +```bash |
| 65 | +# Core ASP.NET Core package |
| 66 | +dotnet add package NetEvolve.Http.Correlation.AspNetCore |
| 67 | + |
| 68 | +# HTTP Client package (for outgoing requests) |
| 69 | +dotnet add package NetEvolve.Http.Correlation.HttpClient |
| 70 | + |
| 71 | +# Optional: ULID provider |
| 72 | +dotnet add package NetEvolve.Http.Correlation.Ulid |
| 73 | +``` |
| 74 | + |
| 75 | +### 2. Configure Services |
| 76 | + |
| 77 | +Add correlation services to your `Program.cs`: |
| 78 | + |
| 79 | +```csharp |
| 80 | +using NetEvolve.Http.Correlation; |
| 81 | + |
| 82 | +var builder = WebApplication.CreateBuilder(args); |
| 83 | + |
| 84 | +// Register correlation services |
| 85 | +builder.Services.AddHttpCorrelation(); |
| 86 | + |
| 87 | +// Configure HTTP clients with correlation forwarding |
| 88 | +builder.Services |
| 89 | + .AddHttpClient("MyApiClient") |
| 90 | + .WithHttpCorrelation(); |
| 91 | + |
| 92 | +var app = builder.Build(); |
| 93 | + |
| 94 | +// Add middleware to the pipeline (should be early) |
| 95 | +app.UseHttpCorrelation(); |
| 96 | + |
| 97 | +app.MapControllers(); |
| 98 | +app.Run(); |
| 99 | +``` |
| 100 | + |
| 101 | +### 3. Access Correlation IDs |
| 102 | + |
| 103 | +Inject `IHttpCorrelationAccessor` to access the current correlation ID: |
| 104 | + |
| 105 | +```csharp |
| 106 | +public class OrderService |
| 107 | +{ |
| 108 | + private readonly IHttpCorrelationAccessor _correlationAccessor; |
| 109 | + private readonly ILogger<OrderService> _logger; |
| 110 | + |
| 111 | + public OrderService( |
| 112 | + IHttpCorrelationAccessor correlationAccessor, |
| 113 | + ILogger<OrderService> logger) |
| 114 | + { |
| 115 | + _correlationAccessor = correlationAccessor; |
| 116 | + _logger = logger; |
| 117 | + } |
| 118 | + |
| 119 | + public async Task ProcessOrderAsync(Order order) |
| 120 | + { |
| 121 | + var correlationId = _correlationAccessor.CorrelationId; |
| 122 | + _logger.LogInformation( |
| 123 | + "Processing order {OrderId} with correlation ID {CorrelationId}", |
| 124 | + order.Id, |
| 125 | + correlationId); |
| 126 | + |
| 127 | + // Your business logic here |
| 128 | + } |
| 129 | +} |
| 130 | +``` |
| 131 | + |
| 132 | +## Advanced Configuration |
| 133 | + |
| 134 | +### Using ULID Provider |
| 135 | + |
| 136 | +```csharp |
| 137 | +builder.Services |
| 138 | + .AddHttpCorrelation() |
| 139 | + .WithUlidGenerator(); |
| 140 | +``` |
| 141 | + |
| 142 | +### Custom Provider |
| 143 | + |
| 144 | +Implement `IHttpCorrelationIdProvider` for custom ID generation: |
| 145 | + |
| 146 | +```csharp |
| 147 | +public class CustomCorrelationIdProvider : IHttpCorrelationIdProvider |
| 148 | +{ |
| 149 | + public string GenerateId() |
| 150 | + { |
| 151 | + return $"CUSTOM-{DateTime.UtcNow.Ticks}"; |
| 152 | + } |
| 153 | +} |
| 154 | + |
| 155 | +// Register custom provider |
| 156 | +builder.Services.AddHttpCorrelation(); |
| 157 | +builder.Services.AddSingleton<IHttpCorrelationIdProvider, CustomCorrelationIdProvider>(); |
| 158 | +``` |
| 159 | + |
| 160 | +## Use Cases |
| 161 | + |
| 162 | +### Distributed Logging |
| 163 | + |
| 164 | +Track requests across multiple services: |
| 165 | + |
| 166 | +```csharp |
| 167 | +// Service A (Entry Point) |
| 168 | +app.UseHttpCorrelation(); // Generates or reads correlation ID |
| 169 | +_logger.LogInformation("Request received"); // Logs with correlation ID |
| 170 | +
|
| 171 | +// Service B (Called by Service A) |
| 172 | +httpClient.GetAsync("/api/data"); // Correlation ID automatically forwarded |
| 173 | +_logger.LogInformation("Data retrieved"); // Same correlation ID in logs |
| 174 | +``` |
| 175 | + |
| 176 | +### Microservices Tracing |
| 177 | + |
| 178 | +Follow a single user request through your entire system: |
| 179 | + |
| 180 | +``` |
| 181 | +User Request → API Gateway → Service A → Service B → Database |
| 182 | + [CorrelationId: abc123] flows through entire chain |
| 183 | +``` |
| 184 | + |
| 185 | +### Testing |
| 186 | + |
| 187 | +Use predictable correlation IDs in tests: |
| 188 | + |
| 189 | +```csharp |
| 190 | +builder.Services |
| 191 | + .AddHttpCorrelation() |
| 192 | + .WithTestGenerator(); // Generates predictable IDs |
| 193 | +
|
| 194 | +// Tests now have consistent correlation IDs |
| 195 | +``` |
| 196 | + |
| 197 | +## Contributing |
| 198 | + |
| 199 | +Contributions are welcome! Please feel free to submit a Pull Request. |
| 200 | + |
| 201 | +## License |
| 202 | + |
| 203 | +Licensed under the MIT License. See [LICENSE](https://github.com/dailydevops/http.correlation/blob/main/LICENSE) for details. |
| 204 | + |
| 205 | +## Repository |
| 206 | + |
| 207 | +- **GitHub**: [dailydevops/http.correlation](https://github.com/dailydevops/http.correlation) |
| 208 | +- **Issues**: [Report Issues](https://github.com/dailydevops/http.correlation/issues) |
| 209 | +- **Releases**: [View Releases](https://github.com/dailydevops/http.correlation/releases) |
0 commit comments