plan-forge observability.instructions.md

.NET Observability Patterns

Structured Logging

Source-Generated Logging (Recommended)

public partial class OrderService
{
    [LoggerMessage(Level = LogLevel.Information, Message = "Order {OrderId} placed for tenant {TenantId}")]
    partial void LogOrderPlaced(string orderId, string tenantId);

    [LoggerMessage(Level = LogLevel.Error, Message = "Order processing failed for {OrderId}")]
    partial void LogOrderFailed(string orderId, Exception ex);
}

Logging Guidelines

// ✅ Structured parameters (not string interpolation)
logger.LogInformation("Processing order {OrderId} for tenant {TenantId}", orderId, tenantId);

// ❌ String interpolation (not queryable)
logger.LogInformation($"Processing order {orderId} for tenant {tenantId}");

OpenTelemetry Setup

Registration

builder.Services.AddOpenTelemetry()
    .WithTracing(tracing => tracing
        .AddSource("MyApp")
        .AddAspNetCoreInstrumentation()
        .AddHttpClientInstrumentation()
        .AddNpgsql()
        .AddOtlpExporter())
    .WithMetrics(metrics => metrics
        .AddMeter("MyApp")
        .AddAspNetCoreInstrumentation()
        .AddHttpClientInstrumentation()
        .AddOtlpExporter());

Custom Traces

private static readonly ActivitySource Activity = new("MyApp.Orders");

public async Task<Order> PlaceOrderAsync(OrderRequest request, CancellationToken ct)
{
    using var activity = Activity.StartActivity("PlaceOrder");
    activity?.SetTag("tenant.id", request.TenantId);
    activity?.SetTag("order.type", request.Type);

    var order = await _repository.SaveAsync(request, ct);
    activity?.SetTag("order.id", order.Id);
    return order;
}

Custom Metrics

private static readonly Meter Meter = new("MyApp.Orders");
private static readonly Counter<long> OrdersPlaced = Meter.CreateCounter<long>("orders.placed");
private static readonly Histogram<double> OrderProcessingTime = Meter.CreateHistogram<double>("orders.processing_ms");

public async Task ProcessAsync(Order order, CancellationToken ct)
{
    var sw = Stopwatch.StartNew();
    // ... process
    OrdersPlaced.Add(1, new KeyValuePair<string, object?>("tenant", order.TenantId));
    OrderProcessingTime.Record(sw.Elapsed.TotalMilliseconds);
}