dotnet-observability

.NET Observability Standards

.NET-specific observability practices for ASP.NET Core APIs. For general observability principles, see engineering-principles.mdc. For strategy-level guidance, see dotnet-architecture.mdc.

Conflict resolution: Where this file provides .NET-specific guidance that differs from engineering-architecture.mdc, this file takes precedence for .cs, .csproj, .json, .yaml, and .yml files.

---

Structured logging

Use ILogger<T> with message templates; never use string interpolation in log messages — it destroys structured field indexing.

// Correct — fields are indexed and queryable
_logger.LogInformation("Order {OrderId} placed for customer {CustomerId}", order.Id, order.CustomerId);

// Incorrect — fields are lost; only raw string is stored
_logger.LogInformation($"Order {order.Id} placed for customer {order.CustomerId}");

• Log at Information for significant state transitions (order placed, payment processed)
• Log at Warning for recoverable business rule violations (retry exhausted, fallback used)
• Log at Error for unhandled exceptions and infrastructure failures; always include the exception object
• Log at Debug for diagnostic detail; never log sensitive fields (PAN, passwords, tokens) at any level

// Error with exception — always pass exception as the last parameter
_logger.LogError(ex, "Failed to persist order {OrderId}", command.OrderId);

---

Correlation IDs

Propagate a correlation ID through every request. Accept from the X-Correlation-Id header if present; generate one if absent. Add to response headers and to the logging scope.

public class CorrelationIdMiddleware(RequestDelegate next)
{
    private const string HeaderName = "X-Correlation-Id";

    public async Task InvokeAsync(HttpContext context)
    {
        var correlationId = context.Request.Headers[HeaderName].FirstOrDefault()
                            ?? Guid.NewGuid().ToString();

        context.Response.Headers[HeaderName] = correlationId;

        using (_logger.BeginScope(new Dictionary<string, object>
               { ["CorrelationId"] = correlationId }))
        {
            await next(context);
        }
    }
}