The correlation ID is distributed tracing mechanism meant to be used to help Admin trace what was happening at the time of an error/request. It is only valuable as an interactive tool to help the Admin track down your error. An Admin uses the correlation ID as "breadcrumbs" to retrace a requests or processes in the Logging System to find what leads up to and causes a problem.
Install Crip.Extensions.Correlation NuGet package, or GitHub package
Configure services:
services.AddHttpContextAccessor(); // package requires that HTTP context accessor is available
services.AddCorrelation();
Configure pipeline:
// Add middlewares as early as possible
app.UseCorrelation();
// or
app.UseMiddleware<CorrelationIdMiddleware>();
app.UseMiddleware<CorrelationIdLoggingMiddleware>();
Correlation makes sense only when entire system is using same Correlation ID. To do so, you can use "traced" HTTP client witch will automatically add header to all outgoing requests.
services.AddTracedHttpClient<TClient, TImplementation>(((provider, client) =>
{
var config = provider.GetRequiredService<IOptions<TClientOptions>>().Value;
client.BaseAddress = new Uri(config.BaseUrl);
}));
To simplify managing correlation contexts, the ICorrelationManager
can be used. It takes care of the logic to create
the context properly. This is especially useful when running background tasks, console apps, Windows services, etc.
which need to interact with external services. Think of message broker handlers, scheduled task runners, etc.
public class MyBackgroundService : BackgroundService
{
private readonly ILogger<MyBackgroundService> _logger;
private readonly ICorrelationManager _correlation;
private readonly ITestControllerClient _client;
public MyBackgroundService(
ILogger<MyBackgroundService> logger,
ICorrelationManager correlation,
ITestControllerClient client)
{
_logger = logger;
_correlation = correlation;
_client = client;
}
protected override async Task ExecuteAsync(CancellationToken stoppingToken)
{
_logger.LogDebug("Background task before use"); // No correlation context logged
await _correlation.Use("some-test-correlation-001", async () =>
{
_logger.LogDebug("Background task after set");
var result = await _client.Test();
_logger.LogDebug("response: {@Result}", result);
});
_logger.LogDebug("Background task after use");
}
}
You can customize correlation by providing custom options:
services.Configure<CorrelationIdOptions>(options =>
{
options.Cookie = "X-Correlation-Id"; // name of the cookie key to use as correlation identifier
options.Header = "X-Correlation-Id"; // name of the HTTP request/response header
options.PropertyName = "CorrelationId"; // name of the loggable property
options.IncludeInResponse = true; // include correlation identifier header in responses
});
Please consider that .NET Core 3.1 and up now has built-in support for W3C TraceContext (blog) and that there are other distributed tracing libraries with more functionality: