Configuring Service Defaults for Health Checks and OpenTelemetry

1. O que são os Service Defaults?

Em uma arquitetura de microsserviços, muitas preocupações são transversais (cross-cutting concerns): como os serviços emitem logs? Como eles expõem seu estado de saúde? Como coletamos métricas e traces? Sem uma abordagem padronizada, cada serviço pode acabar com sua própria implementação, levando a inconsistências e a uma grande quantidade de código repetitivo (boilerplate).

O projeto ServiceDefaults do Aspire resolve exatamente isso. Ele é uma biblioteca de classes compartilhada que contém um conjunto opinativo, mas customizável, de configurações para:

• Observabilidade (OpenTelemetry): Habilita logs, métricas e tracing distribuído.
• Health Checks: Expõe endpoints padronizados para que sistemas de orquestração possam monitorar a saúde do serviço.
• Resiliência (Polly): Configura políticas de retry e circuit breaker para chamadas HTTP (abordaremos em uma lição futura).
• Service Discovery: Permite que os serviços se encontrem na rede (também em uma lição futura).

Ao adicionar uma única linha, builder.AddServiceDefaults(), ao Program.cs de um serviço, você o "inscreve" nesse conjunto de convenções.

2. Habilitando Health Checks Padronizados

Health checks são endpoints simples que informam a um orquestrador (como o Aspire localmente, ou Kubernetes em produção) se uma aplicação está funcionando corretamente. Existem dois tipos principais:

• Liveness (/alive): "A aplicação está rodando?". Se este endpoint falhar, significa que a aplicação travou e precisa ser reiniciada.
• Readiness (/health): "A aplicação está pronta para receber tráfego?". Este endpoint verifica não apenas se a aplicação está rodando, mas também se suas dependências (banco de dados, outros serviços) estão acessíveis. Se falhar, o orquestrador para de enviar tráfego para a instância, mas não a reinicia, dando tempo para que ela se recupere.

Como o Aspire implementa Health Checks

Vamos olhar o código. No seu projeto ServiceDefaults, abra o arquivo Extensions.cs. Você encontrará dois métodos importantes: AddDefaultHealthChecks e MapDefaultEndpoints.

1. AddDefaultHealthChecks:

   public static TBuilder AddDefaultHealthChecks<TBuilder>(this TBuilder builder) 
       where TBuilder : IHostApplicationBuilder
   {
       builder.Services.AddHealthChecks()
           // Add a default liveness check to ensure app is responsive
           .AddCheck("self", () => HealthCheckResult.Healthy(), ["live"]);
       return builder;
   }
   

   Este método registra o serviço de health checks do ASP.NET Core e adiciona um primeiro check chamado "self". Note a tag ["live"], que o identifica como um check de liveness.

2. MapDefaultEndpoints:

   public static WebApplication MapDefaultEndpoints(this WebApplication app)
   {
       // ...
       app.MapHealthChecks("/health");
       app.MapHealthChecks("/alive", new HealthCheckOptions
       {
           Predicate = r => r.Tags.Contains("live")
       });
       // ...
   }
   

   Este método mapeia os endpoints HTTP. /health executa todos os health checks (readiness), enquanto /alive executa apenas aqueles com a tag "live" (liveness).

O mais poderoso é que, quando você adiciona componentes Aspire (como um banco de dados ou cache), eles automaticamente adicionam seus próprios health checks, que são incluídos no endpoint /health.

Aplicação Prática

Vamos aplicar isso ao projeto MyAspireApp.ApiService que você criou na lição anterior.

1. Verifique se o seu MyAspireApp.ApiService/Program.cs tem as seguintes linhas:

   // No topo do arquivo
   builder.AddServiceDefaults();
   
   // ... antes de app.Run()
   app.MapDefaultEndpoints();
   

2. Inicie a aplicação Aspire a partir do diretório do AppHost:

   cd MyAspireApp.AppHost
   dotnet run
   

3. Quando o dashboard abrir, encontre o endpoint do seu apiservice. Se ele estiver rodando, por exemplo, em https://localhost:7001, abra novas abas e navegue para:
   • https://localhost:7001/alive -> Você verá a resposta "Healthy".
   • https://localhost:7001/health -> Você também verá "Healthy".

No dashboard, o status do seu serviço apiservice deve aparecer como "Running".

3. Habilitando Observabilidade com OpenTelemetry

Observabilidade é a capacidade de entender o estado interno de um sistema a partir de seus outputs externos. OpenTelemetry (OTel) é um padrão aberto para instrumentar, gerar, coletar e exportar dados de telemetria, que se baseiam em três pilares:

• Logs: Eventos discretos que aconteceram, úteis para depuração.
• Traces: Representam o fluxo de uma única requisição através de múltiplos serviços (tracing distribuído). Essencial para identificar gargalos e entender interações.
• Metrics: Medições numéricas agregadas ao longo do tempo (ex: número de requisições por segundo, uso de CPU).

A configuração manual do OpenTelemetry pode ser complexa. O Aspire Service Defaults torna isso trivial.

Como o Aspire implementa OpenTelemetry

No mesmo arquivo Extensions.cs, você encontrará o método ConfigureOpenTelemetry.

public static TBuilder ConfigureOpenTelemetry<TBuilder>(this TBuilder builder) 
    where TBuilder : IHostApplicationBuilder
{
    builder.Logging.AddOpenTelemetry(...); // 1. Conecta os logs ao OTel

    builder.Services.AddOpenTelemetry()
        .WithMetrics(metrics => ...)      // 2. Configura as métricas
        .WithTracing(tracing => ...);     // 3. Configura os traces

    builder.AddOpenTelemetryExporters();  // 4. Configura para onde enviar os dados
    
    return builder;
}

A parte mais importante para o desenvolvimento local é o método AddOpenTelemetryExporters. Ele verifica por uma variável de ambiente, OTEL_EXPORTER_OTLP_ENDPOINT. O App Host do Aspire define automaticamente essa variável para cada serviço, apontando para um endpoint no próprio Aspire Dashboard. É assim que toda a telemetria flui para o dashboard sem nenhuma configuração manual.

Aplicação Prática: Explorando a Observabilidade

Como AddServiceDefaults já chama ConfigureOpenTelemetry, tudo está pronto.

1. Com sua aplicação rodando, acesse um endpoint da sua apiservice algumas vezes (por exemplo, https://localhost:7001/weatherforecast).
2. Vá para o Aspire Dashboard e clique na linha do seu apiservice.
3. Explore as abas à esquerda:
   • Structured Logs: Você verá os logs da sua aplicação, não como texto puro, mas como dados estruturados. Você pode filtrar por propriedades, como RequestId, para ver todos os logs de uma única requisição.
   • Traces: Aqui está a mágica do tracing distribuído. Você verá cada chamada HTTP que você fez. Ao clicar em uma, você verá uma "cascata" (waterfall) mostrando a duração de cada etapa interna da sua requisição. Se seu serviço chamasse outro, você veria essa chamada como parte da mesma trace.
   • Metrics: Explore as métricas que o Aspire coleta por padrão. Você pode ver gráficos para aspnetcore_requests_total (total de requisições) ou http_client_request_duration_seconds (duração de chamadas HTTP feitas pelo seu serviço).

Conclusão

Nesta lição, você desvendou o projeto ServiceDefaults e viu como ele é essencial para construir aplicações robustas com .NET Aspire. Com uma única linha de código, você obteve um sistema padronizado de health checks e uma infraestrutura completa de observabilidade.

Principais Pontos:

• O projeto ServiceDefaults centraliza configurações transversais para garantir consistência entre os serviços.
• Health Checks (/alive e /health) são cruciais para a resiliência e são habilitados pelos métodos AddDefaultHealthChecks e MapDefaultEndpoints.
• OpenTelemetry fornece os três pilares da observabilidade: Logs, Traces e Métricas.
• AddServiceDefaults() habilita tudo isso, e o App Host configura automaticamente os serviços para enviarem telemetria para o Aspire Dashboard, proporcionando uma experiência de desenvolvimento local rica e perspicaz.

Na próxima lição, faremos um tour mais aprofundado pelo Aspire Dashboard. Agora que você sabe como os dados chegam lá, vamos nos concentrar em como usar o dashboard de forma eficaz para monitorar, diagnosticar e depurar suas aplicações distribuídas.