When we build backend systems, especially APIs and microservices, debugging production issues is rarely about reading one log line.
A single request may pass through an API Gateway, an authentication service, an order service, a payment service, a message broker, and maybe a background worker.
Each component may generate logs.
But without a shared identifier, it becomes difficult to understand the full journey of that request.
This is where a Correlation ID becomes useful.
A Correlation ID is a unique value attached to a request so that every log entry created during that request can be connected together.
Instead of searching logs by timestamp, endpoint, or user report, we can search by one identifier and follow the request across the system.
In this article, I will explain:
- What a Correlation ID is
- Why it matters
- How it differs from a Trace ID
- How to implement it in ASP.NET Core
- How to add it to logs
- How to return it to the client
- How to propagate it to downstream APIs
- When to use a library instead of custom middleware
- Where personal preferences can start later
This article uses plain text diagrams so the examples render correctly in DEV.to and remain easy to copy, edit, and maintain.
The Problem
Imagine this flow:
Client
-> API Gateway
-> Orders API
-> Payments API
-> External Payment Provider
Now imagine the user says:
My payment failed, but I do not know why.
As backend engineers, we usually check the logs.
But the problem is that each service may have its own logs:
API Gateway logs
Orders API logs
Payments API logs
External integration logs
Without a shared identifier, we may need to search by:
Timestamp
Endpoint
User ID
Order ID
Payment ID
Error message
Server name
That can work, but it is not ideal.
It is slow.
It is unreliable.
It also becomes harder when multiple users are making similar requests at the same time.
A better approach is to attach one ID to the original request and keep passing it through the system.
Example:
X-Correlation-ID: 9f8b2c1e4a9d4e40a1fef03d1f2b7abc
Then every service logs the same value.
CorrelationId=9f8b2c1e4a9d4e40a1fef03d1f2b7abc
Now production debugging becomes much easier.
Instead of asking:
What happened around 10:42?
we can ask:
Show me everything for CorrelationId 9f8b2c1e4a9d4e40a1fef03d1f2b7abc.
That is a much better operational experience.
Request Flow Diagram
Here is the same idea as a simple text diagram:
Client
|
| X-Correlation-ID: 9f8b2c1e4a9d4e40a1fef03d1f2b7abc
v
API Gateway
|
| same X-Correlation-ID
v
Orders API
|
| same X-Correlation-ID
v
Payments API
|
| same X-Correlation-ID if appropriate
v
External Payment Provider
Each service can write logs to a centralized logging system:
API Gateway logs
-> CorrelationId=9f8b2c1e4a9d4e40a1fef03d1f2b7abc
Orders API logs
-> CorrelationId=9f8b2c1e4a9d4e40a1fef03d1f2b7abc
Payments API logs
-> CorrelationId=9f8b2c1e4a9d4e40a1fef03d1f2b7abc
Now we can search logs by one value:
CorrelationId = 9f8b2c1e4a9d4e40a1fef03d1f2b7abc
The important idea is not the specific services.
The important idea is this:
One request flow should have one shared correlation value.
What Is a Correlation ID?
A Correlation ID is a unique identifier used to connect related operations together.
In a backend API, it usually works like this:
1. The client sends a request.
2. The API checks if the request already contains a correlation header.
3. If the header exists, the API reuses it.
4. If the header does not exist, the API generates a new ID.
5. The API adds the ID to logs.
6. The API returns the ID in the response.
7. When calling another service, the API forwards the same ID.
The goal is simple:
All logs related to the same request should contain the same Correlation ID.
A Correlation ID does not need to contain business data.
It should not contain an email address.
It should not contain a phone number.
It should not contain a national ID.
It should not contain an access token.
It should usually be an opaque technical value.
Good examples:
9f8b2c1e4a9d4e40a1fef03d1f2b7abc
7b90d9a2c4b4472189a92ed0d4fb5d91
CID-8K2M9Q7X
Bad examples:
A Correlation ID is for operational debugging, not for identifying a user or exposing sensitive business data.
Correlation ID vs Trace ID
Correlation IDs and distributed tracing are related, but they are not exactly the same thing.
In modern .NET applications, distributed tracing uses System.Diagnostics.Activity.
A distributed trace usually has values like:
TraceId
SpanId
ParentSpanId
These values are useful for observability tools.
For example:
OpenTelemetry
Jaeger
Grafana Tempo
Azure Monitor
Application Insights
Datadog
New Relic
A custom X-Correlation-ID header is usually simpler.
It is often used as a readable request-level identifier that appears in logs and response headers.
A practical way to think about it is:
TraceId -> used by distributed tracing systems
SpanId -> identifies one operation inside a trace
CorrelationId -> used by humans to search and connect logs
In many production systems, both can exist together.
You can have:
TraceId=4bf92f3577b34da6a3ce929d0e0e4736
SpanId=00f067aa0ba902b7
CorrelationId=9f8b2c1e4a9d4e40a1fef03d1f2b7abc
The Trace ID helps your tracing system.
The Correlation ID helps engineers, support teams, and log searches.
They can be the same value in some systems, but they do not have to be.
Basic Architecture
A simple architecture looks like this:
Incoming HTTP Request
|
v
Check for X-Correlation-ID header
|
+-----------------------------+
| |
v v
Header exists Header missing
| |
v v
Reuse incoming ID Generate new ID
| |
+-------------+---------------+
|
v
Store ID in HttpContext.Items
|
v
Add ID to logging scope
|
v
Run application pipeline
|
+-----------+-----------+
| |
v v
Return ID in response Propagate ID to downstream APIs
The ASP.NET Core API is responsible for:
Reading the incoming ID
Creating one when missing
Making it available to the request pipeline
Adding it to logs
Returning it to the caller
Forwarding it to downstream APIs
Example log:
[Information] CorrelationId=9f8b2c1e4a9d4e40a1fef03d1f2b7abc Order created successfully
Now if an incident happens, we can search by:
9f8b2c1e4a9d4e40a1fef03d1f2b7abc
and see the full request flow.
Choosing a Header Name
There is no single universal header name that every system must use.
Common names include:
X-Correlation-ID
X-Request-ID
Correlation-ID
For this article, we will use:
X-Correlation-ID
The exact name is less important than consistency.
If your API Gateway uses X-Request-ID, then your internal services should probably reuse X-Request-ID.
If your company standard is X-Correlation-ID, then use that everywhere.
The worst option is having every service invent its own header name.
Implementing Correlation ID Middleware in ASP.NET Core
ASP.NET Core middleware is a good place to implement this because middleware runs as part of the HTTP request pipeline.
The middleware should do four basic things:
1. Read the incoming X-Correlation-ID header.
2. Generate a new ID if the header is missing.
3. Add the ID to the response headers.
4. Add the ID to the logging scope.
Let’s start with a clean, practical implementation.
This version uses the built-in ILogger.BeginScope() approach.
That makes the implementation provider-agnostic.
It can work with the default Microsoft logging abstractions and also with structured logging providers that support scopes.
Correlation ID Constants
First, define the names in one place.
namespace YourApp.Api.Observability;
public static class CorrelationIdConstants
{
public const string HeaderName = "X-Correlation-ID";
public const string LogPropertyName = "CorrelationId";
public const int MaxLength = 128;
}
This avoids hardcoding strings everywhere.
We now have:
HTTP header: X-Correlation-ID
Log property: CorrelationId
Maximum accepted length: 128
Correlation ID Middleware
Here is a simple middleware implementation.
using System.Diagnostics;
using Microsoft.Extensions.Primitives;
using YourApp.Api.Observability;
namespace YourApp.Api.Middleware;
/// <summary>
/// Ensures every HTTP request has a Correlation ID.
/// The ID is read from the incoming request when available,
/// otherwise a new one is generated.
/// </summary>
public sealed class CorrelationIdMiddleware
{
private readonly RequestDelegate _next;
private readonly ILogger<CorrelationIdMiddleware> _logger;
public CorrelationIdMiddleware(
RequestDelegate next,
ILogger<CorrelationIdMiddleware> logger)
{
_next = next;
_logger = logger;
}
public async Task InvokeAsync(HttpContext context)
{
var correlationId = GetOrCreateCorrelationId(context);
context.Items[CorrelationIdConstants.LogPropertyName] = correlationId;
context.Response.OnStarting(() =>
{
context.Response.Headers[CorrelationIdConstants.HeaderName] = correlationId;
return Task.CompletedTask;
});
using (_logger.BeginScope(new Dictionary<string, object>
{
[CorrelationIdConstants.LogPropertyName] = correlationId
}))
{
await _next(context);
}
}
private static string GetOrCreateCorrelationId(HttpContext context)
{
if (context.Request.Headers.TryGetValue(
CorrelationIdConstants.HeaderName,
out StringValues headerValue))
{
var correlationId = headerValue.FirstOrDefault();
if (IsValid(correlationId))
{
return correlationId!;
}
}
return Activity.Current?.TraceId.ToString()
?? Guid.NewGuid().ToString("N");
}
private static bool IsValid(string? correlationId)
{
if (string.IsNullOrWhiteSpace(correlationId))
return false;
if (correlationId.Length > CorrelationIdConstants.MaxLength)
return false;
return correlationId.All(c =>
char.IsLetterOrDigit(c) ||
c == '-' ||
c == '_' ||
c == '.');
}
}
There are a few important details here.
Reading the Incoming Header
This part checks whether the request already has a Correlation ID:
if (context.Request.Headers.TryGetValue(
CorrelationIdConstants.HeaderName,
out StringValues headerValue))
{
var correlationId = headerValue.FirstOrDefault();
if (IsValid(correlationId))
{
return correlationId!;
}
}
If the client or upstream service already sent the header, we reuse it.
That is important.
If every service creates a new ID, then we lose the full request chain.
Correct behavior:
API Gateway creates the Correlation ID
Orders API reuses it
Payments API reuses it
Incorrect behavior:
API Gateway creates ID A
Orders API creates ID B
Payments API creates ID C
The second version breaks correlation across services.
Generating a New ID
If the incoming header does not exist or is invalid, we generate a new value.
return Activity.Current?.TraceId.ToString()
?? Guid.NewGuid().ToString("N");
This uses the current Activity.TraceId when one exists.
That can be useful because ASP.NET Core and OpenTelemetry already use Activity for distributed tracing.
If there is no current activity, it falls back to a GUID without hyphens.
Example:
9f8b2c1e4a9d4e40a1fef03d1f2b7abc
This is a reasonable default.
Later in the article, I will show where personal preferences can change this behavior.
For example, some teams prefer GUIDs.
Some teams prefer W3C trace IDs.
Some teams prefer short human-readable IDs.
The important part is consistency.
Validating the Incoming Correlation ID
Request headers are user input.
That means we should not blindly trust them.
At minimum, we should reject:
Empty values
Very long values
Whitespace-only values
Unexpected characters
The middleware uses this validation:
private static bool IsValid(string? correlationId)
{
if (string.IsNullOrWhiteSpace(correlationId))
return false;
if (correlationId.Length > CorrelationIdConstants.MaxLength)
return false;
return correlationId.All(c =>
char.IsLetterOrDigit(c) ||
c == '-' ||
c == '_' ||
c == '.');
}
This keeps the implementation simple.
You can make the validation stricter if your system has a specific ID format.
For example, if you only allow GUID-like values, validate GUIDs.
If you only allow IDs starting with CID-, validate that pattern.
If you use the current trace ID, validate the expected trace ID length and format.
The main rule is:
Do not treat incoming headers as trusted data.
Registering the Middleware
Register the middleware early in the request pipeline.
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddControllers();
var app = builder.Build();
app.UseMiddleware<CorrelationIdMiddleware>();
app.MapControllers();
app.Run();
The middleware should run before the parts of the pipeline that need the Correlation ID.
For example, if you have request logging middleware, authentication, authorization, controllers, or exception handling, think carefully about where the Correlation ID should be available.
A common setup is:
var app = builder.Build();
app.UseMiddleware<CorrelationIdMiddleware>();
app.UseAuthentication();
app.UseAuthorization();
app.MapControllers();
app.Run();
If you use exception handling middleware, you may want correlation to happen early enough that exception logs also contain the ID.
Logging With the Correlation ID
The important part of the middleware is this block:
using (_logger.BeginScope(new Dictionary<string, object>
{
[CorrelationIdConstants.LogPropertyName] = correlationId
}))
{
await _next(context);
}
BeginScope() adds contextual data to logs created during that request.
That means your application code can stay clean.
For example:
_logger.LogInformation(
"Creating order for customer {CustomerId}",
customerId);
The log message does not manually include the Correlation ID.
But if your logging provider supports scopes, the log entry can still contain:
CorrelationId=9f8b2c1e4a9d4e40a1fef03d1f2b7abc
This is better than manually writing:
_logger.LogInformation(
"CorrelationId: {CorrelationId}, Creating order for customer {CustomerId}",
correlationId,
customerId);
Why?
Because we do not want to manually pass the Correlation ID into every log message.
That creates noisy code.
It also creates inconsistent logging.
Some log messages will include the ID.
Some will not.
A logging scope gives us one central place to attach the property.
Returning the Correlation ID to the Client
The middleware also returns the ID in the response:
context.Response.OnStarting(() =>
{
context.Response.Headers[CorrelationIdConstants.HeaderName] = correlationId;
return Task.CompletedTask;
});
This is useful because the frontend, API consumer, or support team can report the ID when something fails.
Example response:
HTTP/1.1 500 Internal Server Error
Content-Type: application/json
X-Correlation-ID: 9f8b2c1e4a9d4e40a1fef03d1f2b7abc
Now the support team can ask:
Please give us the Correlation ID from the failed response.
That is much better than only asking for screenshots, approximate times, or browser details.
Example Error Response
You may also include the Correlation ID in error responses.
For example:
{
"title": "An unexpected error occurred.",
"status": 500,
"correlationId": "9f8b2c1e4a9d4e40a1fef03d1f2b7abc"
}
This is optional, but it can be useful.
If you expose the ID in the response body, make sure it is not sensitive.
A Correlation ID should be safe to show to clients.
That is another reason not to use emails, user IDs, phone numbers, or tokens as Correlation IDs.
Propagating the Correlation ID to Downstream APIs
Adding the Correlation ID to the current API logs is useful.
But in distributed systems, we also need to send it to downstream services.
For example:
Orders API -> Payments API
If the Orders API receives this header:
X-Correlation-ID: 9f8b2c1e4a9d4e40a1fef03d1f2b7abc
then the outgoing request to the Payments API should include the same header:
X-Correlation-ID: 9f8b2c1e4a9d4e40a1fef03d1f2b7abc
One clean way to do that is with a DelegatingHandler.
Downstream Propagation Diagram
The downstream flow looks like this:
Client
|
| POST /orders
| X-Correlation-ID: abc123
v
Orders API
|
| Log: CorrelationId=abc123
|
| POST /payments
| X-Correlation-ID: abc123
v
Payments API
|
| Log: CorrelationId=abc123
|
v
Payment processing
Then the response travels back:
Payments API
|
| Payment response
v
Orders API
|
| Order response
| X-Correlation-ID: abc123
v
Client
This is the behavior we want.
The same ID follows the operation.
Registering the Delegating Handler
Register IHttpContextAccessor and the handler:
builder.Services.AddHttpContextAccessor();
builder.Services.AddTransient<CorrelationIdDelegatingHandler>();
Then attach the handler to a named HttpClient:
builder.Services
.AddHttpClient("PaymentsApi", client =>
{
client.BaseAddress = new Uri("https://payments-api.example.com");
})
.AddHttpMessageHandler<CorrelationIdDelegatingHandler>();
Now, when the API calls another service using that configured HttpClient, the same Correlation ID is sent with the request.
Example usage:
public sealed class PaymentsClient
{
private readonly HttpClient _httpClient;
public PaymentsClient(IHttpClientFactory httpClientFactory)
{
_httpClient = httpClientFactory.CreateClient("PaymentsApi");
}
public async Task<HttpResponseMessage> CreatePaymentAsync(
object request,
CancellationToken cancellationToken)
{
return await _httpClient.PostAsJsonAsync(
"/payments",
request,
cancellationToken);
}
}
The caller does not need to manually add the Correlation ID.
The handler does it automatically.
Testing the Behavior
We can test the behavior using curl.
Request Without a Correlation ID
curl -i https://localhost:5001/orders
Expected behavior:
HTTP/1.1 200 OK
X-Correlation-ID: generated-value
The API should generate a new value and return it in the response.
The logs should include the same generated value.
Request With a Correlation ID
curl -i https://localhost:5001/orders \
-H "X-Correlation-ID: test-correlation-id-123"
Expected behavior:
HTTP/1.1 200 OK
X-Correlation-ID: test-correlation-id-123
The API should reuse the incoming value.
The logs should include:
CorrelationId=test-correlation-id-123
Request With an Invalid Correlation ID
curl -i https://localhost:5001/orders \
-H "X-Correlation-ID: this-value-is-way-too-long-and-should-not-be-accepted-because-it-is-user-controlled-and-could-pollute-logs"
Expected behavior:
The API ignores the invalid value.
The API generates a new Correlation ID.
The API returns the generated value in the response.
This matters because headers are user input.
Do not let clients send unlimited values into your logs.
What Should Logs Look Like?
A good structured log event might contain properties like this:
{
"Timestamp": "2026-06-25T10:42:00.000Z",
"Level": "Information",
"Message": "Order created successfully",
"CorrelationId": "9f8b2c1e4a9d4e40a1fef03d1f2b7abc",
"TraceId": "4bf92f3577b34da6a3ce929d0e0e4736",
"SpanId": "00f067aa0ba902b7",
"RequestPath": "/orders",
"RequestMethod": "POST",
"StatusCode": 201
}
The exact shape depends on your logging provider and observability platform.
But the idea is the same.
The Correlation ID should be a structured property, not only text inside a message.
Prefer this:
CorrelationId=abc123
over this:
Message="Correlation ID is abc123"
Structured properties are easier to filter, search, group, and index.
Production Considerations
A simple Correlation ID implementation is useful, but production systems need a few extra considerations.
1. Validate Incoming Values
Do not blindly trust request headers.
A client could send:
A very large value
Unexpected characters
Whitespace
Control characters
A value designed to pollute logs
At minimum, set a reasonable maximum length.
public const int MaxLength = 128;
You can also enforce a specific format.
For example:
Only GUIDs
Only trace IDs
Only values that start with CID-
Only alphanumeric values plus a few safe separators
The stricter your format, the easier it is to reason about.
2. Do Not Store Sensitive Data in the Correlation ID
A Correlation ID should be an opaque technical identifier.
Avoid values like:
Email
Phone number
User ID
National ID
Access token
Refresh token
Session ID
Payment card data
Even if your logs are private, logs often move through many systems:
Application logs
Log collectors
Cloud logging tools
Alerting systems
Dashboards
Support tickets
Incident reports
Do not put sensitive data in a value that may appear everywhere.
3. Keep the Header Name Consistent
Pick one header name and use it everywhere.
Common examples:
X-Correlation-ID
X-Request-ID
The exact name is less important than consistency.
If your API Gateway, backend APIs, and workers all use different names, correlation becomes messy.
4. Do Not Generate a New ID in Every Service
This is one of the most common mistakes.
Incorrect:
Gateway creates ID A
Orders API creates ID B
Payments API creates ID C
Correct:
Gateway creates ID A
Orders API reuses ID A
Payments API reuses ID A
Only generate a new ID when there is no incoming ID or the incoming ID is invalid.
5. Think About Background Jobs and Messaging
HTTP is not the only place where correlation matters.
If your system uses:
RabbitMQ
Azure Service Bus
Kafka
Hangfire
MassTransit
Quartz
BackgroundService
Outbox pattern
you should also think about how to pass correlation metadata through messages.
Example:
HTTP request creates order
OrderCreated message is published
Background worker consumes message
Payment workflow starts
The Correlation ID should usually be added to the message metadata.
For example:
{
"messageId": "msg-123",
"correlationId": "9f8b2c1e4a9d4e40a1fef03d1f2b7abc",
"type": "OrderCreated"
}
The same idea applies:
One business operation -> one correlation value
6. Be Careful With Response Headers
Returning the Correlation ID in the response is useful.
But only return values that are safe to expose.
This is another reason why the ID should not contain sensitive data.
A response header like this is fine:
X-Correlation-ID: 9f8b2c1e4a9d4e40a1fef03d1f2b7abc
A response header like this is not fine:
7. Use Structured Logging
A Correlation ID is most useful when logs are structured.
This is useful:
{
"Message": "Payment failed",
"CorrelationId": "abc123",
"PaymentProvider": "ExamplePay"
}
This is less useful:
Payment failed. Correlation ID is abc123.
Plain text can still be searched, but structured logs are easier to filter and query.
A Simple End-to-End Setup
A minimal setup may look like this:
using YourApp.Api.Http;
using YourApp.Api.Middleware;
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddControllers();
builder.Services.AddHttpContextAccessor();
builder.Services.AddTransient<CorrelationIdDelegatingHandler>();
builder.Services
.AddHttpClient("PaymentsApi", client =>
{
client.BaseAddress = new Uri("https://payments-api.example.com");
})
.AddHttpMessageHandler<CorrelationIdDelegatingHandler>();
var app = builder.Build();
app.UseMiddleware<CorrelationIdMiddleware>();
app.MapControllers();
app.Run();
This gives us:
Incoming request correlation
Response header correlation
Logging scope correlation
Downstream HTTP propagation
That is a good baseline.
Where OpenTelemetry Fits
Correlation IDs help us connect logs.
But they are not a complete observability strategy.
For larger systems, we usually also want:
Metrics
Distributed traces
Structured logs
Dependency telemetry
Latency breakdowns
Error rates
Service maps
This is where OpenTelemetry becomes useful.
OpenTelemetry helps collect telemetry from your application and export it to observability tools.
A simple tracing setup in ASP.NET Core may look like this:
using OpenTelemetry.Resources;
using OpenTelemetry.Trace;
builder.Services
.AddOpenTelemetry()
.ConfigureResource(resource =>
{
resource.AddService(
serviceName: "orders-api",
serviceVersion: "1.0.0");
})
.WithTracing(tracing =>
{
tracing
.AddAspNetCoreInstrumentation()
.AddHttpClientInstrumentation()
.AddOtlpExporter();
});
This gives you distributed tracing for:
Incoming HTTP requests
Outgoing HTTP calls
TraceId
SpanId
Parent-child operation relationships
Correlation IDs and OpenTelemetry can work together.
A practical setup can include:
CorrelationId for log search
TraceId for distributed tracing
SpanId for individual operations
Should the Correlation ID Be the Same as the Trace ID?
Sometimes yes.
Sometimes no.
Using the current Activity.TraceId as the Correlation ID has a benefit:
Logs and traces share the same identifier.
That can make observability queries easier.
But a Trace ID is not always the best human-facing value.
It may be long.
It may be less friendly for support teams.
It may be tied to tracing implementation details.
Using a separate Correlation ID has a benefit:
You can choose a format optimized for humans and support workflows.
For example:
CID-8K2M9Q7X
There is no single perfect answer.
The right choice depends on your system.
A reasonable default is:
Use Activity.TraceId when available.
Use a generated GUID when not available.
Keep the value opaque and safe.
Later, if your team wants a shorter or more human-friendly format, you can change the generator.
Personal Preferences
This is where the article can move from the neutral baseline into personal engineering preferences.
The sections above explain the general concept and a practical default implementation.
The next sections are where I would add my own preferences.
These are not the only correct choices.
They are the choices I usually prefer when I own the backend observability design.
My Preference 1: Keep the Middleware Small
I like the middleware to have a very clear job:
Read the Correlation ID.
Generate one if missing.
Validate it.
Store it.
Return it.
Make it available to logs.
I do not want the middleware to become a general observability system.
I do not want it to know about business logic.
I do not want it to know about orders, payments, users, or tenants.
The middleware should stay boring.
Boring middleware is easier to test and reuse.
My Preference 2: Do Not Log Inside the Middleware
Some implementations do this:
_logger.LogInformation(
"Correlation ID created: {CorrelationId}",
correlationId);
I usually avoid that.
The middleware does not need to create a log event just to say that it created or reused an ID.
That often adds noise without much value.
What I actually want is this:
Every important log event during the request should automatically include CorrelationId.
So the middleware should enrich the logging context.
It should not produce unnecessary log lines.
This is the difference:
Bad goal:
Create one extra log line saying the Correlation ID exists.
Good goal:
Attach the Correlation ID to all useful logs created during the request.
My Preference 3: Use Structured Log Enrichment
In the baseline implementation, we used ILogger.BeginScope():
using (_logger.BeginScope(new Dictionary<string, object>
{
[CorrelationIdConstants.LogPropertyName] = correlationId
}))
{
await _next(context);
}
That is a good provider-agnostic approach.
If I am using Serilog, I usually prefer Serilog’s LogContext:
using (Serilog.Context.LogContext.PushProperty(
CorrelationIdConstants.LogPropertyName,
correlationId))
{
await _next(context);
}
The idea is the same.
The Correlation ID becomes a structured property attached to logs created during the request.
My Preference 4: Use Short Human-Readable IDs When They Help
GUIDs and trace IDs are valid.
Examples:
9f8b2c1e4a9d4e40a1fef03d1f2b7abc
4f8d5f6b-9f26-49f7-9e85-2a477c1dc9e4
00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-00
But sometimes I prefer shorter IDs like:
CID-8K2M9Q7X
CID-Q7P4A2MN
CID-X9TR5B1K
Why?
Because Correlation IDs are not only for machines.
They are also copied by humans.
Support engineers, QA engineers, backend engineers, and frontend engineers may copy the ID from:
API response headers
Error screens
Browser dev tools
Log dashboards
Support tickets
Slack messages
Incident reports
A shorter value can be easier to work with.
That said, this is a preference, not a rule.
For many systems, a GUID or Activity.TraceId is perfectly fine.
Example Short Correlation ID Generator
If you want a short human-readable format, you can generate random bytes and encode them using a safe alphabet.
Example:
using System.Buffers.Binary;
using System.Security.Cryptography;
namespace YourApp.Api.Observability;
public static class CorrelationIdGenerator
{
private const string Prefix = "CID-";
private const string Alphabet = "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
public static string Generate()
{
Span<byte> bytes = stackalloc byte[8];
RandomNumberGenerator.Fill(bytes);
var encoded = ToBase32(bytes);
return $"{Prefix}{encoded}";
}
private static string ToBase32(ReadOnlySpan<byte> bytes)
{
var value = BinaryPrimitives.ReadUInt64BigEndian(bytes);
Span<char> chars = stackalloc char[13];
for (var i = chars.Length - 1; i >= 0; i--)
{
chars[i] = Alphabet[(int)(value & 31)];
value >>= 5;
}
return new string(chars);
}
}
Example output:
CID-0Z8K2M9Q7X4TA
CID-1HF92TQ5M7P8K
CID-0A7QW4P9T2XMN
Important note:
Do not use this as a security token, authentication token, password reset token, or business identifier.
This is only for operational correlation.
My Preference 5: Use Serilog Request Logging for HTTP Completion Events
If I am using Serilog, I like using request completion logs.
The idea is to have one useful structured log event per HTTP request.
That event can include:
RequestMethod
RequestPath
StatusCode
Elapsed
CorrelationId
UserAgent
RequestHost
Example:
{
"RequestMethod": "POST",
"RequestPath": "/orders",
"StatusCode": 201,
"Elapsed": 142.55,
"CorrelationId": "CID-8K2M9Q7X",
"RequestHost": "api.example.com"
}
That is much more useful than many noisy framework logs.
A Serilog setup may include:
app.UseMiddleware<CorrelationIdMiddleware>();
app.UseSerilogRequestLogging(options =>
{
options.EnrichDiagnosticContext = (diagnosticContext, httpContext) =>
{
diagnosticContext.Set(
CorrelationIdConstants.LogPropertyName,
httpContext.Items[CorrelationIdConstants.LogPropertyName]?.ToString());
diagnosticContext.Set(
"RequestHost",
httpContext.Request.Host.Value);
diagnosticContext.Set(
"UserAgent",
httpContext.Request.Headers.UserAgent.ToString());
};
});
The order matters.
The Correlation ID middleware should run before request logging if the request logging middleware needs the Correlation ID.
My Preference 6: Use OpenTelemetry for Real Distributed Tracing
I do not want to build a tracing system manually with Correlation IDs.
Correlation IDs are useful for log search.
But distributed tracing needs more than one ID.
Tracing needs:
TraceId
SpanId
ParentSpanId
Timing
Dependencies
Status
Attributes
Service boundaries
So my preference is:
Use CorrelationId for human-friendly log correlation.
Use OpenTelemetry for distributed tracing.
Both can exist together.
That gives us:
Logs are searchable by CorrelationId.
Traces are explorable by TraceId.
Metrics show health and trends.
That is a better observability story.
Alternative: Use a Library Instead of Writing Middleware
Writing custom middleware is useful because it helps us understand the concept.
But in real projects, especially when many services need the same behavior, we may not want to copy the same middleware into every codebase.
One option is the CorrelationId NuGet package.
Install it:
dotnet add package CorrelationId
Example setup:
builder.Services.AddDefaultCorrelationId(options =>
{
options.AddToLoggingScope = true;
options.IncludeInResponse = true;
options.RequestHeader = "X-Correlation-ID";
options.ResponseHeader = "X-Correlation-ID";
});
Then register the middleware:
app.UseCorrelationId();
Another option is Correlate.AspNetCore.
Install it:
dotnet add package Correlate.AspNetCore
These libraries can be useful when you want a ready-made correlation solution.
But you should still understand the behavior.
Before adding any library, ask:
Does it use the header name we want?
Does it validate incoming values?
Does it add the ID to logs?
Does it include the ID in responses?
Does it propagate the ID to downstream calls?
Is it actively maintained?
Does it work with our .NET version?
Does it fit our OpenTelemetry setup?
A library is not automatically better than custom middleware.
Custom middleware is not automatically better than a library.
The right answer depends on your system.
Custom Middleware vs Library
Here is a practical rule:
If you are learning, write the middleware yourself once.
If you have one small service, custom middleware is fine.
If you have many services, use a shared internal package or a library.
If you need full tracing, use OpenTelemetry.
If I have many services, I prefer not to copy and paste middleware into every project.
Instead, I would create a shared internal package.
Example:
Company.Observability.Correlation
Then each service can use:
builder.Services.AddCompanyCorrelationId();
app.UseCompanyCorrelationId();
That gives us:
Shared behavior
Consistent header names
Consistent validation
Consistent logging property names
One place to update later
This is often better than copying the same middleware across many repositories.
Common Mistakes
Here are common mistakes to avoid.
Mistake 1: Generating a New ID in Every Service
This breaks the request chain.
Incorrect:
Gateway -> CorrelationId=A
Orders API -> CorrelationId=B
Payments API -> CorrelationId=C
Correct:
Gateway -> CorrelationId=A
Orders API -> CorrelationId=A
Payments API -> CorrelationId=A
Generate a new value only when there is no valid incoming value.
Mistake 2: Logging the ID Manually Everywhere
Avoid this pattern:
_logger.LogInformation(
"CorrelationId: {CorrelationId}, Creating order",
correlationId);
Prefer contextual logging:
using (_logger.BeginScope(new Dictionary<string, object>
{
["CorrelationId"] = correlationId
}))
{
await _next(context);
}
or, if using Serilog:
using (LogContext.PushProperty("CorrelationId", correlationId))
{
await _next(context);
}
The goal is to enrich useful logs automatically.
Mistake 3: Forgetting Downstream HTTP Calls
If the ID is not propagated to other services, the chain stops at the first API.
Use a DelegatingHandler with HttpClientFactory.
Mistake 4: Confusing Correlation IDs With Business IDs
A Correlation ID is not the same as:
OrderId
CustomerId
UserId
PaymentId
InvoiceId
Business IDs describe domain entities.
Correlation IDs describe request flow.
Sometimes logs should contain both.
Example:
{
"CorrelationId": "abc123",
"OrderId": "ord_789",
"Message": "Order payment failed"
}
But they are not the same concept.
Mistake 5: Putting Sensitive Data in Correlation IDs
Do not use:
Email
Phone number
Access token
Session ID
National ID
Customer name
Use an opaque technical value.
Mistake 6: Ignoring Distributed Tracing
Correlation IDs are useful, but they are not a complete observability strategy.
For larger systems, distributed tracing gives better visibility into:
Latency
Dependencies
Retries
Failures
Nested operations
Cross-service requests
Use OpenTelemetry when you need serious observability.
Final Recommended Flow
A good Correlation ID implementation should follow this flow:
Request enters API
|
v
Has valid X-Correlation-ID?
|
+-----------------------------+
| |
v v
Yes No
| |
v v
Reuse incoming ID Generate new ID
| |
+-------------+---------------+
|
v
Store in request context
|
v
Add to logging scope
|
v
Run application code
|
+-----------+-----------+
| |
v v
Return ID in response Forward ID downstream
|
v
Downstream service logs same ID
That is the core pattern.
Everything else is a design choice.
Final Thoughts
Correlation IDs are a small feature, but they can make production debugging much easier.
They help us answer questions like:
Where did this request fail?
Which services handled it?
Which logs belong to the same request?
What should support ask the client to provide?
For backend engineers, this is one of those practical patterns that improves observability without adding too much complexity.
A good implementation should:
Read an incoming Correlation ID.
Generate one if missing.
Validate incoming values.
Add the ID to logs.
Return the ID in the response.
Propagate it to downstream services.
Keep the behavior consistent across the system.
The neutral baseline is simple:
Use X-Correlation-ID.
Use middleware.
Use logging scopes.
Use a DelegatingHandler for downstream calls.
Use Activity.TraceId or GUID as a default generated value.
Then your personal preferences can improve the implementation:
Use short human-readable IDs if that helps your team.
Use Serilog LogContext if Serilog is your logging provider.
Use Serilog request logging for clean HTTP completion events.
Use OpenTelemetry for distributed tracing.
Move shared behavior into an internal package when you have many services.
The goal is not to create more logs.
The goal is to make the logs we already have easier to connect.
When a production issue happens, a good Correlation ID lets us move from:
Something failed around 10:42.
to:
Show me everything for this CorrelationId.
That difference matters.
SOCIAL SHARE CARD GENERATOR