Correlation IDs

Correlation IDs help you track requests as they flow through different services, components, and layers of your application. This makes debugging distributed systems much easier.

What are Correlation IDs?

A correlation ID is a unique identifier that follows a request throughout its entire lifecycle, allowing you to:

Track requests across microservices
Debug issues in distributed systems
Monitor request flow and performance
Correlate logs from different components

Basic Usage

Use the fluent syntax with WithCorrelationId():

// Set correlation ID for a log entry
Log.WithCorrelationId("operation-123").Info("Payment process started");

// Use with different log levels
Log.WithCorrelationId("req-456").Debug("Processing user request");
Log.WithCorrelationId("req-456").Error("Request failed", errorContext, ex);

// Generate unique correlation IDs
var correlationId = Guid.NewGuid().ToString("N")[..12];
Log.WithCorrelationId(correlationId).Info("Order processing started");

Fluent Syntax

ByteHide Logger uses a fluent API that allows method chaining:

// Chain correlation ID with logging methods
Log.WithCorrelationId("req-123").Info("Request started");
Log.WithCorrelationId("req-123").Debug("Processing data");
Log.WithCorrelationId("req-123").Error("Request failed", context, ex);

// Generate and use correlation IDs in services
public class OrderService
{
    public async Task<Order> CreateOrderAsync(CreateOrderRequest request)
    {
        var correlationId = Guid.NewGuid().ToString("N")[..8];
        
        Log.WithCorrelationId(correlationId).Info("Order creation started");
        
        try
        {
            var order = await ProcessOrderAsync(request);
            Log.WithCorrelationId(correlationId).Info("Order created successfully");
            return order;
        }
        catch (Exception ex)
        {
            Log.WithCorrelationId(correlationId).Error("Order creation failed", new { RequestData = request }, ex);
            throw;
        }
    }
}

Practical Examples

Request Flow Tracking

[ApiController]
public class OrdersController : ControllerBase
{
    [HttpPost]
    public async Task<IActionResult> CreateOrder(CreateOrderRequest request)
    {
        var correlationId = Guid.NewGuid().ToString("N")[..8];
        
        Log.WithCorrelationId(correlationId).Info("Order creation started");
        
        try
        {
            var order = await _orderService.CreateOrderAsync(request);
            Log.WithCorrelationId(correlationId).Info("Order created successfully");
            return Ok(order);
        }
        catch (Exception ex)
        {
            Log.WithCorrelationId(correlationId).Error("Order creation failed", new { RequestData = request }, ex);
            return StatusCode(500);
        }
    }
}

Service Layer Correlation

public class PaymentService
{
    public async Task<PaymentResult> ProcessPaymentAsync(PaymentRequest request, string correlationId)
    {
        Log.WithCorrelationId(correlationId).Info("Processing payment");
        
        try
        {
            var result = await CallPaymentApiAsync(request);
            Log.WithCorrelationId(correlationId).Info("Payment processed successfully");
            return result;
        }
        catch (Exception ex)
        {
            Log.WithCorrelationId(correlationId).Error("Payment processing failed", new { Amount = request.Amount }, ex);
            throw;
        }
    }
}

Best Practices

Correlation ID Best Practices

Use short IDs: 8-12 characters are usually sufficient (e.g., a1b2c3d4e5f6)
Use fluent syntax: Take advantage of method chaining with WithCorrelationId()
Pass IDs between services: Include correlation IDs when calling other services
Generate unique IDs: Use Guid.NewGuid().ToString("N")[..8] for unique identifiers
Log at boundaries: Always log when entering/exiting services or operations

Next Steps

Global Properties - Add consistent context to all logs
User Identification - Associate logs with users
Tags - Organize and categorize logs
Metadata & Context - Add context to individual logs