Observabilidade do .NET com o OpenTelemetry

Ao executar um aplicativo, você deseja saber como está o desempenho do aplicativo e detectar possíveis problemas antes que eles se tornem maiores. Você pode fazer isso emitindo dados de telemetria, como logs ou métricas do seu aplicativo, e depois monitorando e analisando esses dados.

O que é observabilidade?

A observabilidade, no contexto de um sistema distribuído, é a capacidade de monitorar e analisar a telemetria sobre o estado de cada componente, observar alterações no desempenho e diagnosticar por que essas alterações ocorrem. Ao contrário da depuração, que é invasiva e pode afetar a operação do aplicativo, a observabilidade destina-se a ser transparente para a operação primária e ter um impacto pequeno no desempenho o suficiente para que ela possa ser usada continuamente.

Normalmente, a observabilidade é feita usando uma combinação de:

• Logs, que registram operações individuais, como uma solicitação de entrada, uma falha em um componente específico ou um pedido sendo feito.
• Métricas, que são contadores de medição e medidores, como número de solicitações concluídas, solicitações ativas, widgets vendidos ou um histograma da latência da solicitação.
• Rastreamento distribuído, que rastreia solicitações e atividades entre componentes em um sistema distribuído para que você possa ver onde o tempo é gasto e rastrear falhas específicas.

Juntos, logs, métricas e rastreamento distribuído às vezes são conhecidos como os três pilares da observabilidade.

Cada pilar pode incluir dados de telemetria de:

• Runtime do .NET, como o coletor de lixo ou compilador JIT.
• Bibliotecas, como do Kestrel (o servidor web do ASP.NET) e HttpClient.
• Telemetria específica do aplicativo emitida pelo código.

Abordagens de observabilidade no .NET

Existem algumas maneiras diferentes de alcançar a observabilidade em aplicativos .NET:

• Explicitamente no código, fazendo referência e usando uma biblioteca como o OpenTelemetry. Se você tiver acesso ao código-fonte e puder recompilar o aplicativo, esse será o mecanismo mais poderoso e configurável.
• Fora do processo usando EventPipe. Ferramentas como o dotnet-monitor podem escutar logs e métricas e processá-los sem afetar nenhum código.
• A usar um gancho de inicialização, os assemblies podem ser injetados no processo que pode coletar a instrumentação. Um exemplo dessa abordagem é a Instrumentação Automática do .NET OpenTelemetry.

O que é o OpenTelemetry?

OpenTelemetry (OTel) é um padrão aberto e multiplataforma para coletar e emitir dados de telemetria. O OpenTelemetry inclui:

• APIs para bibliotecas a serem usadas para gravar dados de telemétricos enquanto o código está em execução.
• APIs que os desenvolvedores de aplicativos usam para configurar qual parte dos dados gravados será enviada pela rede, para onde será enviada e como pode ser filtrada, armazenada em buffer, enriquecida e transformada.
• Convenções semânticas fornecem diretrizes sobre nomenclatura e conteúdo de dados telemétricos. É importante que os aplicativos que produzem dados telemétricos e as ferramentas que recebem os dados cheguem a um acordo sobre o que diferentes tipos de dados significam e quais tipos de dados são úteis para que as ferramentas possam fornecer uma análise eficaz.
• Uma interface para exportadores. Os exportadores são plug-ins que permitem que os dados telemétricos sejam transmitidos em formatos específicos para diferentes back-ends de telemetria.
• Protocolo eletrônico OTLP é uma opção de protocolo de rede neutra do fornecedor para transmitir dados telemétricos. Algumas ferramentas e fornecedores oferecem suporte a esse protocolo, além de protocolos proprietários pré-existentes que possam ter.

O uso do OTel possibilita a utilização de uma ampla variedade de sistemas APM, incluindo sistemas de código aberto, como Prometheus e Grafana, Azure Monitor – produto APM da Microsoft no Azure ou de muitos fornecedores do APM que fazem parceria com o OpenTelemetry.

Há implementações do OpenTelemetry para a maioria dos idiomas e plataformas, incluindo o .NET.

Implementação .NET do OpenTelemetry

A implementação .NET do OpenTelemetry é um pouco diferente de outras plataformas, pois o .NET fornece APIs de registro em log, métricas e atividades na estrutura. Isso significa que o OTel não precisa fornecer APIs para que os autores da biblioteca usem. A implementação do .NET OTel usa essas APIs de plataforma para instrumentação:

• Microsoft.Extensions.Logging.ILogger<TCategoryName> para registro em log
• System.Diagnostics.Metrics.Meter para métricas
• System.Diagnostics.ActivitySource e System.Diagnostics.Activity para rastreamento distribuído

O OTel entra em ação porque coleta a telemetria dessas APIs e de outras fontes (por meio de bibliotecas de instrumentação) e, em seguida, as exporta para um sistema de monitoramento de desempenho de aplicativos (APM) para armazenamento e análise. O benefício que o OTel traz como padrão do setor é um mecanismo comum para coleta, esquemas e semântica comuns para dados telemétricos e uma API para como os APMs podem se integrar ao OTel. Com o uso do OTel, os aplicativos não precisam usar APIs ou estruturas de dados específicas de APM; eles funcionam de acordo com o padrão do OTel. Os APMs podem implementar um componente exportador específico do APM ou usar o OTLP, que é um novo padrão de ligação para exportar dados de telemetria para os sistemas APM.

Pacotes do OpenTelemetry

No .NET, o OpenTelemetry é implementado como uma série de pacotes NuGet que formam algumas categorias:

• API principal
• Instrumentação – esses pacotes coletam instrumentação do runtime e das bibliotecas comuns.
• Exportadores – essas interfaces com sistemas APM como Prometheus, Jaeger e OTLP.

A tabela a seguir descreve os principais pacotes.

Exemplos

Este tópico continua com alguns exemplos de instruções para usar o OpenTelemetry no .NET:

• Exemplo: usar o OTLP e o painel autônomo do Aspire
• Exemplo: usar o OpenTelemetry com o Azure Monitor e o Application Insights
• Exemplo: usar o OpenTelemetry com Prometheus, Grafana e Jaeger

OpenTelemetry no Aspire

O Aspire é um conjunto de extensões para .NET para facilitar a criação e o trabalho com aplicativos distribuídos. Um dos benefícios de usar o Aspire é que a telemetria é interna, usando as bibliotecas OpenTelemetry para .NET. Os modelos de projeto padrão para o Aspire contêm um projeto ServiceDefaults, parte do qual é instalar e configurar o OTel. O projeto Padrões de Serviço é referenciado e inicializado por cada serviço em uma solução Aspire.

O modelo de projeto de Padrões de Serviços inclui os pacotes OTel SDK, ASP.NET, HttpClient e Instrumentação em runtime, e eles são configurados no arquivo Extensions.cs. Para exportar telemetria, o Aspire inclui o exportador OTLP por padrão para que ele possa fornecer visualização de telemetria usando o Painel aspire.

O Painel do Aspire foi projetado para trazer a observação de telemetria para o ciclo de depuração local, o que permite que os desenvolvedores não apenas garantam que os aplicativos estejam produzindo telemetria, mas também usem essa telemetria para diagnosticar esses aplicativos localmente. A possibilidade de observar as chamadas entre os serviços está se mostrando tão útil no momento da depuração quanto na produção. O painel do Aspire é iniciado automaticamente quando você F5 o AppHost Projeto do Visual Studio ou o projeto dotnet runAppHost.

Painel do Aspire

Para obter mais detalhes sobre o Aspire, consulte:

• Visão geral do Aspire
• Telemetria no Aspire
• Painel do Aspire

Reutilizar projeto padrões de serviço sem Orquestração Aspire

Provavelmente, a maneira mais fácil de configurar o OTel para projetos ASP.NET é usar o projeto Aspire Service Defaults, mesmo que não esteja usando o restante do Aspire, como o AppHost para orquestração. O projeto de Padrões de Serviço está disponível como um modelo de projeto por meio do Visual Studio ou do dotnet new. Ele configura o OTel e define o exportador OTLP. Em seguida, você pode usar as variáveis de ambiente OTel para configurar o ponto de extremidade OTLP para enviar telemetria e fornecer as propriedades de recurso para o aplicativo.

As etapas para usar ServiceDefaults fora do Aspire são:

• Adicione o projeto ServiceDefaults à solução usando Adicionar Novo Projeto no Visual Studio ou use dotnet new aspire-servicedefaults --output ServiceDefaults.
• Consulte o projeto ServiceDefaults do seu aplicativo ASP.NET. No Visual Studio, use Adicionar>Referência de Projeto e selecione o projeto ServiceDefaults.
• Chame sua função de configuração OpenTelemetry como parte da inicialização do configurador de aplicativos.

var builder = WebApplication.CreateBuilder(args);
builder.ConfigureOpenTelemetry();

var app = builder.Build();

app.MapGet("/", () => "Hello World!");

app.Run();

Os padrões de serviço podem configurar a seguinte funcionalidade adicional, se necessário, por meio AddServiceDefaults() ou pelas funções específicas:

• Verificações de integridade com /health e /alive endpoints.
• Descoberta de serviço, que será um no-op sem o restante do Aspire.
• Configurando a resiliência do HttpClient, que realiza novas tentativas de solicitações no caso de falhas.