Nabs.Launchpad.Core.ServiceDefaults 10.0.181-rc3

Nabs Launchpad Core Service Defaults Library

The Nabs Launchpad Core Service Defaults library provides standardized observability, health checks, service discovery, and HTTP resilience configuration for all Launchpad applications. This library implements best practices for distributed applications based on .NET Aspire patterns.

Key Features

• OpenTelemetry Integration: Comprehensive logging, metrics, and distributed tracing
• Health Checks: Built-in health and liveness endpoints for container orchestration
• Service Discovery: Automatic service resolution and load balancing
• HTTP Resilience: Standard retry, timeout, and circuit breaker patterns
• Metrics Collection: ASP.NET Core, HTTP client, and runtime metrics
• Distributed Tracing: Request correlation across services
• OTLP Export: OpenTelemetry Protocol support for observability platforms

Core Components

ProjectExtensions

Provides extension methods for configuring service defaults on IHostApplicationBuilder and WebApplication.

Usage Examples

Basic Service Setup

using Nabs.Launchpad.Core.ServiceDefaults;

var builder = WebApplication.CreateBuilder(args);

// Add all service defaults (telemetry, health checks, service discovery, resilience)
builder.AddServiceDefaults();

// Your service configuration
builder.Services.AddControllers();

var app = builder.Build();

// Map health check endpoints
app.MapDefaultEndpoints();

app.MapControllers();

await app.RunAsync();

Custom OpenTelemetry Configuration

var builder = WebApplication.CreateBuilder(args);

// Configure only OpenTelemetry (without other defaults)
builder.ConfigureOpenTelemetry();

// Add custom metrics
builder.Services.AddOpenTelemetry()
    .WithMetrics(metrics =>
    {
        metrics.AddMeter("MyApp.CustomMetrics");
    });

var app = builder.Build();

Health Checks Only

var builder = WebApplication.CreateBuilder(args);

// Add only health checks
builder.AddDefaultHealthChecks();

// Add custom health checks
builder.Services.AddHealthChecks()
    .AddCheck<DatabaseHealthCheck>("database")
    .AddCheck<CacheHealthCheck>("cache", tags: new[] { "ready" });

var app = builder.Build();
app.MapDefaultEndpoints();

Aspire AppHost Integration

// In your AppHost project
var builder = DistributedApplication.CreateBuilder(args);

// Service defaults are automatically applied to all projects
var apiService = builder.AddProject<Projects.MyApi>("api-service");

var webApp = builder.AddProject<Projects.MyWebApp>("web-app")
    .WithReference(apiService);

builder.Build().Run();

API Reference

AddServiceDefaults<TBuilder>

public static TBuilder AddServiceDefaults<TBuilder>(this TBuilder builder) 
    where TBuilder : IHostApplicationBuilder

Adds all service defaults including:

• OpenTelemetry configuration
• Health checks
• Service discovery
• HTTP client resilience

Returns: The builder for method chaining

Usage:

builder.AddServiceDefaults();

ConfigureOpenTelemetry<TBuilder>

public static TBuilder ConfigureOpenTelemetry<TBuilder>(this TBuilder builder) 
    where TBuilder : IHostApplicationBuilder

Configures OpenTelemetry for logging, metrics, and tracing.

Includes:

• Formatted message logging with scopes
• ASP.NET Core metrics and instrumentation
• HTTP client metrics and instrumentation
• Runtime metrics (GC, thread pool, exceptions)
• Distributed tracing with activity correlation
• OTLP exporter (when OTEL_EXPORTER_OTLP_ENDPOINT is configured)

Returns: The builder for method chaining

AddDefaultHealthChecks<TBuilder>

public static TBuilder AddDefaultHealthChecks<TBuilder>(this TBuilder builder) 
    where TBuilder : IHostApplicationBuilder

Adds default health checks including a self-check tagged as "live".

Returns: The builder for method chaining

Usage:

builder.AddDefaultHealthChecks();

// Add custom health checks
builder.Services.AddHealthChecks()
    .AddCheck<MyCustomHealthCheck>("my-check");

MapDefaultEndpoints

public static WebApplication MapDefaultEndpoints(this WebApplication app)

Maps health check endpoints (development environment only for security).

Endpoints:

• /health - All health checks must pass (readiness)
• /alive - Only "live" tagged checks must pass (liveness)

Returns: The WebApplication for method chaining

Usage:

var app = builder.Build();
app.MapDefaultEndpoints();

OpenTelemetry Configuration

Metrics

Automatically collected metrics include:

ASP.NET Core Metrics:

• Request duration
• Request rate
• Active requests
• Failed requests

HTTP Client Metrics:

• Request duration by endpoint
• Success/failure rates
• Active connections

Runtime Metrics:

• GC collections
• Heap size
• Thread pool statistics
• Exception counts

Tracing

Automatically instrumented traces:

ASP.NET Core Tracing:

• HTTP request spans
• Automatic span hierarchy
• Exception tracking
• Excludes health check endpoints

HTTP Client Tracing:

• Outbound HTTP request spans
• Service dependency mapping
• Request/response details

Logging

Enhanced logging features:

• Formatted Messages: Full message formatting included
• Scopes: Log scopes preserved for context
• Structured Logging: JSON-structured logs
• OpenTelemetry Integration: Logs correlated with traces

Health Checks

Default Health Checks

The library provides a "self" health check tagged as "live":

.AddCheck("self", () => HealthCheckResult.Healthy(), ["live"])

Health Check Endpoints

/health (Readiness)

• All registered health checks must pass
• Used by orchestrators to determine if pod should receive traffic
• Returns 200 OK when healthy, 503 Service Unavailable otherwise

/alive (Liveness)

• Only health checks tagged with "live" must pass
• Used by orchestrators to determine if pod should be restarted
• Returns 200 OK when alive, 503 Service Unavailable otherwise

Custom Health Checks

// Register custom health check
builder.Services.AddHealthChecks()
    .AddCheck<DatabaseHealthCheck>("database", tags: new[] { "ready" })
    .AddCheck<CacheHealthCheck>("cache", tags: new[] { "ready" })
    .AddCheck("api-dependency", () => 
    {
        // Check external API
        return HealthCheckResult.Healthy();
    }, tags: new[] { "ready" });

// Health check implementation
public class DatabaseHealthCheck : IHealthCheck
{
    private readonly IDbConnection _connection;
    
    public DatabaseHealthCheck(IDbConnection connection)
    {
        _connection = connection;
    }
    
    public async Task<HealthCheckResult> CheckHealthAsync(
        HealthCheckContext context, 
        CancellationToken cancellationToken = default)
    {
        try
        {
            await _connection.OpenAsync(cancellationToken);
            return HealthCheckResult.Healthy("Database is accessible");
        }
        catch (Exception ex)
        {
            return HealthCheckResult.Unhealthy("Database is not accessible", ex);
        }
    }
}

Service Discovery

Automatic Service Resolution

HTTP clients automatically resolve service names:

// Service registration (no hardcoded URLs)
builder.Services.AddHttpClient<IOrdersService, OrdersService>(client =>
{
    client.BaseAddress = new Uri("http://orders-service");  // Service name, not URL
});

// Usage
public class OrdersService : IOrdersService
{
    private readonly HttpClient _httpClient;
    
    public OrdersService(HttpClient httpClient)
    {
        _httpClient = httpClient;  // Automatically configured with service discovery
    }
    
    public async Task<Order> GetOrderAsync(int id)
    {
        // Service name resolves to actual endpoint
        return await _httpClient.GetFromJsonAsync<Order>($"/api/orders/{id}");
    }
}

Service Discovery Configuration

// Optional: Restrict allowed schemes
builder.Services.Configure<ServiceDiscoveryOptions>(options =>
{
    options.AllowedSchemes = ["https"];  // Only allow HTTPS endpoints
});

HTTP Resilience

Standard Resilience Handler

Automatically applied to all HTTP clients:

Includes:

• Retry Policy: Exponential backoff with jitter
• Timeout Policy: Request and overall timeout
• Circuit Breaker: Prevents cascading failures
• Rate Limiter: Controls request rate

Configuration

// HTTP client with standard resilience
builder.Services.AddHttpClient<IMyService, MyService>(client =>
{
    client.BaseAddress = new Uri("http://my-service");
})
.AddStandardResilienceHandler();  // Already added by service defaults

// Custom resilience configuration
builder.Services.AddHttpClient<IMyService, MyService>()
    .AddStandardResilienceHandler(options =>
    {
        options.Retry.MaxRetryAttempts = 5;
        options.CircuitBreaker.SamplingDuration = TimeSpan.FromSeconds(30);
    });

OTLP Export Configuration

Environment Variables

Configure OTLP exporter using standard environment variables:

# OTLP endpoint (enables exporter when set)
OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4317

# Optional: Configure protocol (grpc or http/protobuf)
OTEL_EXPORTER_OTLP_PROTOCOL=grpc

# Optional: Configure headers (for authentication)
OTEL_EXPORTER_OTLP_HEADERS=api-key=your-api-key

appsettings.json Configuration

{
  "OTEL_EXPORTER_OTLP_ENDPOINT": "http://localhost:4317",
  "OTEL_EXPORTER_OTLP_PROTOCOL": "grpc"
}

Supported Backends

Works with any OpenTelemetry-compatible backend:

• Jaeger: Distributed tracing
• Prometheus: Metrics collection
• Grafana: Visualization
• Azure Monitor: Azure Application Insights
• AWS X-Ray: AWS observability
• Google Cloud Trace: GCP observability

Container Orchestration

Kubernetes Integration

apiVersion: v1
kind: Pod
metadata:
  name: my-service
spec:
  containers:
  - name: my-service
    image: my-service:latest
    livenessProbe:
      httpGet:
        path: /alive
        port: 8080
      initialDelaySeconds: 10
      periodSeconds: 30
    readinessProbe:
      httpGet:
        path: /health
        port: 8080
      initialDelaySeconds: 5
      periodSeconds: 10

Docker Compose

version: '3.8'
services:
  my-service:
    image: my-service:latest
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8080/alive"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s

Best Practices

Service Defaults

1. Always Use: Call AddServiceDefaults() in every service
2. Order Matters: Call before other service registrations
3. Map Endpoints: Always call MapDefaultEndpoints() for health checks

Health Checks

1. Tag Appropriately: Use "live" for liveness, "ready" for readiness
2. Fast Checks: Keep health checks lightweight (< 1 second)
3. Avoid Cascading: Don't check downstream services in liveness checks
4. Include Dependencies: Check critical dependencies in readiness checks

Observability

1. Environment-Specific: Use OTLP in production, console in development
2. Sampling: Configure appropriate trace sampling in production
3. Sensitive Data: Avoid logging sensitive information
4. Custom Metrics: Add application-specific metrics when needed

HTTP Clients

1. Named Clients: Use typed or named HTTP clients
2. Service Names: Use service names instead of URLs for discovery
3. Resilience: Trust the standard resilience handler
4. Timeouts: Configure appropriate timeouts for your scenarios

Security Considerations

Health Check Endpoints

• Only exposed in development by default
• Consider authentication for production environments
• Avoid exposing sensitive information in health check responses

Observability Data

• Sanitize sensitive data before logging
• Use appropriate retention policies
• Secure OTLP endpoints with authentication
• Consider data privacy regulations (GDPR, HIPAA, etc.)

Dependencies

• Microsoft.Extensions.Http.Resilience: HTTP resilience patterns
• Microsoft.Extensions.ServiceDiscovery: Service discovery client
• OpenTelemetry.Exporter.OpenTelemetryProtocol: OTLP exporter
• OpenTelemetry.Extensions.Hosting: OpenTelemetry hosting integration
• OpenTelemetry.Instrumentation.AspNetCore: ASP.NET Core instrumentation
• OpenTelemetry.Instrumentation.Http: HTTP client instrumentation
• OpenTelemetry.Instrumentation.Runtime: .NET runtime instrumentation

Related Libraries

• Nabs.Launchpad.Core.Gateway: Gateway service using service defaults
• Nabs.Launchpad.Core.Silo: Orleans silo with service defaults
• Nabs.Launchpad.Core.Portal: Blazor portal with service defaults

Target Framework

• .NET 10