Automatic Telemetry in Aspire

O Padrão da Indústria: OpenTelemetry

A automação da observabilidade no Aspire não é uma solução proprietária; ela é construída sobre um padrão aberto e robusto chamado OpenTelemetry (OTel). Entender o OTel é a chave para entender como o Aspire funciona.

Em essência, OpenTelemetry é um framework e um conjunto de ferramentas projetado para padronizar a forma como geramos, coletamos e exportamos dados de telemetria (logs, métricas e traces).

Para ter uma visão geral do que é o OpenTelemetry e por que ele é tão importante no desenvolvimento de software moderno, assista aos seguintes trechos de uma excelente palestra de Martin Thwaites na NDC London 2024.

A principal vantagem do OTel é que ele separa a instrumentação do seu código da ferramenta de visualização (o backend). Você instrumenta sua aplicação uma vez com OTel, e pode enviar os dados para o Aspire Dashboard, Azure Monitor, Prometheus, Grafana ou qualquer outra ferramenta compatível, sem alterar seu código.

Instrumentação: Automática vs. Codificada

Existem duas abordagens principais para instrumentar uma aplicação com OpenTelemetry:

1. Auto-instrumentação: Geralmente envolve anexar um agente ao processo da sua aplicação que "injeta" a instrumentação em tempo de execução, sem alterações no código. É rápido para começar, mas oferece menos controle e pode gerar muito "ruído".
2. Instrumentação Codificada (Coded Instrumentation): Envolve adicionar pacotes NuGet e algumas linhas de código na inicialização da sua aplicação para configurar o pipeline do OTel e registrar as bibliotecas de instrumentação desejadas. Isso lhe dá controle total sobre o que é medido e como é medido.

O .NET Aspire utiliza uma abordagem de instrumentação codificada que é tão simplificada e bem integrada que parece automática.

Para entender melhor essa distinção e por que a abordagem codificada é mais poderosa, assista a outro trecho da mesma palestra.

O Mecanismo de Instrumentação do Aspire

Agora que entendemos os conceitos, vamos ver como o Aspire implementa essa instrumentação codificada de forma tão eficaz. O processo ocorre em duas camadas principais: o projeto ServiceDefaults e as integrações de componentes (Client Integrations).

1. A Base: O Projeto ServiceDefaults

Como vimos nas lições anteriores, o projeto ServiceDefaults é um projeto de biblioteca de classes que centraliza configurações comuns. Uma de suas funções mais importantes é configurar o pipeline do OpenTelemetry para todos os serviços que o referenciam.

Vamos analisar como isso é feito.

O que isso significa na prática?

• AddAspNetCoreInstrumentation: Automaticamente cria spans para todas as requisições HTTP que chegam ao seu serviço ASP.NET Core.
• AddHttpClientInstrumentation: Automaticamente cria spans para todas as requisições HTTP de saída feitas usando HttpClient.
• AddRuntimeInstrumentation: Coleta métricas sobre o .NET runtime, como uso de memória e atividade do garbage collector.

Apenas por referenciar o projeto ServiceDefaults e chamar builder.AddServiceDefaults(), seus serviços já ganham uma base sólida de observabilidade para qualquer interação HTTP.

2. A Especialização: Integrações de Componentes (Client Integrations)

A instrumentação HTTP é ótima, mas e quanto às chamadas a bancos de dados, caches e filas? É aqui que as integrações de componentes do Aspire brilham.

Quando você adiciona um pacote NuGet de um componente Aspire, como Aspire.Npgsql ou Aspire.StackExchange.Redis, você não está apenas obtendo a configuração da string de conexão. Você também está adicionando a biblioteca de instrumentação OpenTelemetry específica para esse componente.

O fluxo é o seguinte:

1. Você adiciona Aspire.Npgsql ao seu projeto de API.
2. Este pacote tem uma dependência do OpenTelemetry.Instrumentation.Npgsql.
3. Quando você chama builder.AddNpgsqlDbContext(...) no seu Program.cs, o código de extensão do Aspire faz duas coisas:
   a. Configura o DbContext para usar a string de conexão fornecida pelo AppHost.
   b. Registra a instrumentação do Npgsql no pipeline do OpenTelemetry que foi previamente configurado pelo ServiceDefaults.

O resultado é que cada chamada ao banco de dados feita através do Entity Framework Core agora é automaticamente capturada como um span dentro do trace da sua requisição.

A documentação oficial da Microsoft e um artigo detalhado da comunidade confirmam este comportamento.

A melhor maneira de ver isso é em ação. Quando adicionamos o Redis para cache na lição anterior sobre traces, o Aspire automaticamente incluiu as chamadas ao Redis no trace distribuído.

Conclusão

Nesta lição, desvendamos a "mágica" por trás da observabilidade no .NET Aspire. Vimos que não se trata de mágica, mas sim de uma aplicação inteligente e bem arquitetada do padrão industrial OpenTelemetry.

Principais Pontos:

• .NET Aspire utiliza OpenTelemetry para fornecer observabilidade de primeira classe.
• A abordagem do Aspire é de instrumentação codificada, oferecendo controle e contexto, mas de forma tão simplificada que parece automática.
• O projeto ServiceDefaults estabelece um pipeline de OpenTelemetry centralizado, configurando instrumentações genéricas para ASP.NET Core e HttpClient.
• As integrações de componentes do Aspire (como para PostgreSQL, Redis, RabbitMQ) adicionam automaticamente bibliotecas de instrumentação específicas para essas tecnologias ao pipeline do OTel.
• O resultado é uma telemetria rica e correlacionada (logs, traces, métricas) que flui para o Aspire Dashboard com configuração mínima, cobrindo todo o fluxo de uma requisição através de múltiplos serviços e dependências.

Próxima Lição:
Com esta lição, concluímos nossa profunda imersão no .NET Aspire. Você agora tem uma base sólida sobre como construir, conteinerizar e monitorar aplicações distribuídas prontas para a nuvem.

A partir do próximo módulo, mudaremos nosso foco da orquestração de desenvolvimento local para a orquestração em escala de produção. Começaremos a explorar o Kubernetes, o sistema que se tornou o padrão de fato para gerenciar contêineres em produção. Você verá como os conceitos que aprendemos, como health checks e a exportação de telemetria, são fundamentais para operar aplicações de forma robusta no Kubernetes.