Observabilidade do .NET com o OpenTelemetry

Artigo
10/25/2024

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 medem contadores e medidores, como número de solicitações concluídas, solicitações ativas, widgets que foram 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.
Usando 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?

O 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.
O protocolo de ligação OTLP é uma opção de protocolo de rede neutra do fornecedor para transmitir dados telemétricos. Algumas ferramentas e fornecedores ofecerem 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:

Arquitetura .NET OTel

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.

Nome do Pacote	Descrição
OpenTelemetry	Biblioteca principal que fornece a funcionalidade principal do OTEL
OpenTelemetry.Instrumentation.AspNetCore	Instrumentação para ASP.NET Core e Kestrel
OpenTelemetry.Instrumentation.GrpcNetClient	Instrumentação para o cliente gRPC para acompanhar chamadas gRPC de saída
OpenTelemetry.Instrumentation.Http	Instrumentação para o `HttpClient` e `HttpWebRequest` acompanhar chamadas HTTP de saída
OpenTelemetry.Instrumentation.SqlClient	Instrumentação usada para o `SqlClient` rastrear operações de banco de dados
OpenTelemetry.Exporter.Console	Exportador para o console, normalmente usado para diagnosticar qual telemetria está sendo exportada
OpenTelemetry.Exporter.OpenTelemetryProtocol	Exportador usando o protocolo OTLP
OpenTelemetry.Exporter.Prometheus.AspNetCore	Exportador para Prometheus implementado usando um ponto de extremidade ASP.NET Core
OpenTelemetry.Exporter.Zipkin	Exportador para rastreamento Zipkin

Exemplos

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

OpenTelemetry no .NET Aspire

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

O modelo de projeto Service Defaults inclui os pacotes OTel SDK, ASP.NET, HttpClient e Runtime Instrumentation, e eles são configurados no Extensions.cs arquivo. Para exportar telemetria, o .NET Aspire inclui o exportador OTLP por padrão para que ele possa fornecer visualização de telemetria usando o painel do Aspire.

O Aspire Dashboard 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. Ser capaz de observar as chamadas entre os serviços está provando ser tão útil no momento da depuração quanto na produção. O painel do .NET Aspire é iniciado automaticamente quando você F5 o AppHost projeto do Visual Studio ou dotnet run do AppHost projeto.

Para obter mais detalhes sobre o .NET Aspire, consulte:

Reutilizando o projeto de Padrões de Serviço sem o .NET Aspire Orchestration

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 .NET Aspire, como o AppHost, para orquestração. O projeto Padrões de Serviço está disponível como um modelo de projeto por meio do Visual Studio ou dotnet newdo . Ele configura o OTel e configura 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 .NET Aspire são:

Adicione o projeto ServiceDefaults à solução usando Adicionar Novo Projeto no Visual Studio ou use dotnet new aspire-servicedefaults --output ServiceDefaults
Faça referência ao 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 do OpenTelemetry como parte da inicialização do construtor 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() de ou das funções específicas:

Verificações de integridade com /health e /alive endpoints
Descoberta de serviço que será um no-op sem o resto do .NET Aspire
Configurando a resiliência para HttpClient que repetirá a solicitação em caso de falhas

Compartilhar via